Changelog JSON Specification

This document attempts to describe how a changelog can be stored in JSON format. The reason for posting this specification is that I needed a public format for https://releasewise.com/, and I was unable to find anything on the web.

But first, what is a changelog? Keep A Changelog defines it as follows:

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

I proposes the following structure:

{
  "releases": [
    {
      "version": "",
      "codename": "",
      "released": "",
      "changelog": [
        {
          "title": "",
          "released": "",
          "label": "",
          "module": "",
          "language": "",
          "author": "",
          "description_group": [
            {
              "media_type": "",
              "body": ""
            }
          ],
          "urgency": "",
          "url_group": [
            {
              "url": "",
              "title": "",
              "url_type": "",
              "media_type": ""
            }
          ]
        }
      ]
    }
  ]
}

Example of a typical changelog:

{
  "releases": [
    {
      "version": "1.2.10",
      "codename": "Big Electric Cat",
      "released": "2019/03/30",
      "changelog": [
        {
          "title": "Tasks can now be dragged between projects",
          "released": "2019/03/28",
          "label": "Added",
          "module": "ui",
          "language": "en",
          "author": "David",
          "description_group": [
            {
              "media_type": "text/plain",
              "body": "Previously you had to cut a task and paste it into a project column in order to move tasks. With this change you can now drag and drop tasks between project columns."
            }
          ],
          "urgency": "low",
          "url_group": [
            {
              "url": "https://example.com/assets/screenshot.jpg",
              "title": "Dragging and dropping a task",
              "url_type": "image",
              "media_type": "image/jpeg"
            }
          ]
        }
      ]
    }
  ]
}

• releases[]: array of { "version", "codename", "released", "changelog" } elements
• version: version number, preferably based on Semantic Versioning (required)
• codename: code name
• released: release date of version formatted as ISO 8601 date or Unreleased
• changelog: array of entries describing new features, bug fixes, etc
  • title: short description of the feature, preferably less than 50 characters (required)
  • released: release date of change formatted as ISO 8601 date or Unreleased
  • label: see below (required)
  • module: module name, useful for mono repos
  • language: ISO 639-1 language code
  • author: name of author
  • description_group: array of { "media_type", "body" } elements
  • media_type: allowed values are text/plain, text/html, text/markdown
  • body: description of the change
  • urgency: allowed values are low, medium, high, critical indicating importance of this change
  • url_group: array of { "url", "title", "url_type", "media_type" } elements
  • url: link to web page, image, document, or other URL-addressable asset (required)
  • title: description of resource URL points to
  • url_type: allowed values are web, image, video, audio, document
  • media_type: media/MIME type

Notes on label

The Keep A Changelog site recommends:

• Added for new features
• Changed for changes in existing functionality
• Deprecated for soon-to-be removed features
• Removed for now removed features
• Fixed for any bug fixes
• Security in case of vulnerabilities

Other often used labels are:

• Unreleased
• Improved
• Refactored
• Performance
• Enhancement
• Feature
• Other

This specification doesn't specify a required set of label values. Although this would be preferable it seems there are too many variations out in the wild.