ChangeLog

Geraint edited this page Jul 18, 2013 · 23 revisions

Note

This page lists differences with draft v3.

Links:

General

  • Specification is split: core, validation, hyperschema, others?

Core specification

  • Mandate JSON Reference (and, therefore, JSON Pointer) support.
  • Define canonical/inline addressing; add example for inline addressing.
  • Define JSON equality, root schema, subschema, instance, keyword.
  • Define schema/instance correlation using existing protocol headers.

Validation specification

  • Highlight interoperability concerns: numeric instances, regular expressions.
  • Reword keyword section completely; separate instance validation from children validation.

New keywords

The following new keywords have been introduced:

  • anyOf (match at least one schema in the schema array),
  • allOf (match all schemas in the schema array),
  • oneOf (match exactly one schema in the schema array),
  • not (do not match the schema),
  • multipleOf (replaces divisibleBy),
  • minProperties and maxProperties (the minimum and maximum number of members in an object instance),
  • definitions (standardized container for inlined subschemas).

Keyword differences

type

When the value is an array, schemas are no longer allowed as elements. Also, the array must have at least one element.

Before:

{
    "type": [ "string", { "other": "schema" } ]
}

Now:

{
   "anyOf": [
       { "type": "string" },
       { "other": "schema" }
    ]
}

dependencies

A single string in a property dependency is no longer allowed, only arrays are allowed.

Before:

{
    "dependencies": { "a": "b" }
}

Now:

{
    "dependencies": { "a": [ "b" ] }
}

required

Before, it was an attribute of subschemas in properties. It is now a first level keyword playing the same role, and has a string array as an argument.

Before:

{
    "properties": {
        "p": {
            "type": "string",
            "required": true
        },
        "q": {
            "type": "string",
            "required": true
        }
    }
}

Now:

{
    "properties": {
        "p": { "type": "string" },
        "q": { "type": "string" }
    },
    "required": [ "p", "q" ]
}

Removed keywords

disallow

Use a combination of not and anyOf according to the situation.

Before:

{
    "disallow": [ "string", "boolean" ]
}

Now:

{
    "not": { "type": [ "string", "boolean" ] }
}

Before:

{
    "disallow": [ "string", { "other": "schema" } ]
}

Now:

{
    "not": {
        "anyOf": [
            { "type": "string" },
            { "other": "schema" }
        ]
    }
}

extends

Use allOf.

Before:

{
    "a": "b",
    "extends": { "c": "d" }
}

Now:

{
    "allOf": [
        { "a": "b" },
        { "c": "d" }
    ]
}

divisibleBy

Replaced with multipleOf.

Before:

{
    "divisibleBy": 3.2981
}

Now:

{
    "mutipleOf": 3.2981
}

Hyperschema

Added

Link Description Objects: mediaType

This is an "advisory content type" for the link, modeled on the "type" attribute in HTML's <a> elements and a similar parameter in the "Link" HTTP Header

Changed

Link Description Objects: href

It now uses RFC 6570, the URI Templating standard.

Knock-on effects:

  • In order to be able to specify variable names with a wider range of characters than RFC 6570 allows (alpha-numeric + percent-encoded), there are now some pre-processing rules. Essentially, all variable names should be percent-encoded, but you can use brackets ((/)) to escape them, e.g. /some/url/{(Hello, world!)} -> /some/url/{Hello%20world%21}
  • The templating language is much more powerful - however, you now have to specify whether you want the values to be percent-encoded or not. For example, /browse/{path} might end up as /browse/dir%2FsubDir, but /browse/{+path} would end up as /browse/dir/subDir.

Moved

mediaType and contentEncoding -> media

Before:

{
    "title": "A base64-encoded PNG file",
    "type": "string",
    "contentEncoding": "base64",
    "mediaType": "image/png"
}

Now:

{
    "title": "A base64-encoded PNG file",
    "type": "string",
    "media": {
        "binaryEncoding": "base64",
        "type": "image/png"
    }
}

Link Description Objects: enctype -> encType

BecauseEverythingElseUsesCamelCase