2019-12-15 13:28

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.

Permalink — Comments or kudos? Find me on Twitter.

Check out my new product Releasewise. It's a project inbox for product owners.