Migration Guide

This guide documents all of the changes between API Elements 0.6 and API Elements 1.0.

JSON Serialisation

In prior versions of API Elements, an Element (i.e. a type) could be occasionally serialized as a value. This behaviour has since been dropped, so that Elements are always serialized in full form (i.e. as a type, not as a value). For example:

{
  "element": "null",
  "meta": {
    "title": "empty"
  }
}

Elements must always be serialised as an element, for example the following would be valid in API Elements 1.0:

{
  "element": "null",
  "meta": {
    "title": {
      "element": "string",
      "content": "empty"
    }
  }
}

In previous versions of API Elements, both forms were valid so this is not a breaking change. However, we found multiple implementations that were fragile and could break when different forms were used.

Changes to Elements

Category Element

The meta attribute has been renamed to metadata in a Category Element for clarity.

Before

{
  "element": "category",
  "attributes": {
    "meta": {
      "element": "array",
      "content": [
        {
          "element": "member",
          "content": {
            "key": {
              "element": "string",
              "content": "HOST"
            },
            "value": {
              "element": "string",
              "content": "http://polls.apiblueprint.org/"
            }
          }
        }
      ]
    }
  }
}

After

{
  "element": "category",
  "attributes": {
    "metadata": {
      "element": "array",
      "content": [
        {
          "element": "member",
          "content": {
            "key": {
              "element": "string",
              "content": "HOST"
            },
            "value": {
              "element": "string",
              "content": "http://polls.apiblueprint.org/"
            }
          }
        }
      ]
    }
  }
}

Source Map Element

A Source Map Element may contain an optional line and column number to make it easier to handle source map information. Computing the line and column number can often be expensive so it may be provided by a parser. Note however that it is optional and it is down the each individual tooling on whether it is present, some tools only provide line and column number for source maps contained within Annotation Elements.

{
  "element": "sourceMap",
  "content": [
    {
      "element": "array",
      "content": [
        {
          "element": "number",
          "attributes": {
            "line": {
              "element": "number",
              "content": 3
            },
            "column": {
              "element": "number",
              "content": 2
            }
          },
          "content": 4
        },
        {
          "element": "number",
          "attributes": {
            "line": {
              "element": "number",
              "content": 3
            },
            "column": {
              "element": "number",
              "content": 10
            }
          },
          "content": 12
        }
      ]
    }
  ]
}

Data Structure Elements

Enumeration Element

The layout of the Enum Element has been altered. The enumerations have been moved to an enumerations attribute of the element and the content now represents the given value.

Enumerations themselves are an array of the possible enumerations.

Before

{
  "element": "enum",
  "content": [
    {
      "element": "string",
      "content": "north"
    },
    {
      "element": "string",
      "content": "east"
    },
    {
      "element": "string",
      "content": "south"
    },
    {
      "element": "string",
      "content": "west"
    }
  ]
}

After

{
  "element": "enum",
  "attributes": {
    "enumerations": {
      "element": "array",
      "content": [
        {
          "element": "string",
          "content": "north"
        },
        {
          "element": "string",
          "content": "east"
        },
        {
          "element": "string",
          "content": "south"
        },
        {
          "element": "string",
          "content": "west"
        }
      ]
    }
  }
}

The intent of the structure was that it represents an enumeration of north, east, south and west. As the enumerations do not include a fixed type attribute it represents an enumeration where any string is valid and not just the fixed values. This created a limitation that tooling cannot determine the difference between one of the fixed element enumerations, or a type with a value. Thus, when the values are fixed they will now include a fixed type attribute as follows:

{
  "element": "enum",
  "attributes": {
    "enumerations": {
      "element": "array",
      "content": [
        {
          "element": "string",
          "attributes": {
            "typeAttributes": {
              "element": "array",
              "content": [
                {
                  "element": "string",
                  "content": "fixed"
                }
              ]
            }
          },
          "content": "north"
        },
        {
          "element": "string",
          "attributes": {
            "typeAttributes": {
              "element": "array",
              "content": [
                {
                  "element": "string",
                  "content": "fixed"
                }
              ]
            }
          },
          "content": "east"
        },
        {
          "element": "string",
          "attributes": {
            "typeAttributes": {
              "element": "array",
              "content": [
                {
                  "element": "string",
                  "content": "fixed"
                }
              ]
            }
          },
          "content": "south"
        },
        {
          "element": "string",
          "attributes": {
            "typeAttributes": {
              "element": "array",
              "content": [
                {
                  "element": "string",
                  "content": "fixed"
                }
              ]
            }
          },
          "content": "west"
        }
      ]
    }
  }
}