Differences with the standard

We had to limit our notion of JSON Schema in order to make it more readable and user-friendly. Here are the differences between our grammar and the latest draft specification.

JSON Schemas are JSON Documents.

And we are assuming that JSON objects cannot have two values with the same keys. This is to avoid these types of examples, which will probably not work properly in several implementations:

{
    "type": "string",
    "type": object
}

We do not support the inclusion of additional keywords or items in schemas.

Every key and every value in the document must conform to the JSON Schema specification, and in particular we do not allow mixing schemas with other JSON information. We are aware that certain implementations may support schemas with additional non-schema information, but we believe this deeply complicates the examples and jeopardises the readability of JSON Schema documents.

Our grammar clearly specifies an upper level, where a title and a description keywords can be defined, and with an optional definitions object (see below). The rest has to conform to JSON Schema specification.

We norm the use of a separate “definitions” section.

This is also an effort to reduce information overload in JSON schemas. In all the schemas we have seen there is always a definitions object at the topmost level of the schema, and the rest of the document only references documents inside this definitions section. For this reason we decided to divide JSON schemas into two parts: a "definitions" object that contains several schemas under different keywords, and a schema object where all the schema keywords come in. In other words, we mandate all schemas to have the following form:

{
    "definitions": {
        "Name1": {
            < a valid schema > 
        }, 
        "Name2": {
            < another valid schema > 
        }, 
        .
        .
        .
    },

   .
   .
   Here comes the top level schema
   .
   .     
}

We do not include the "default" keywords, nor any other way of specifying default values.

We don't think the use of "default" is clear enough in the specification, so we decided to leave out this functionality. To name just a few examples where the use of default is not clear, consider the following schemas:

{
    "anyOf": [
        {"type": "number"}, 
        {"type": "number", "default":0}
    ]
}

Is this equivalent to a number object whose default is 0? What about an "anyOf" schema? this is even more complicated when different default values are given:

{
    "allOf": [
        {"type": "number", "default": 10}, 
        {"type": "number", "default":0}
    ]
}

These two are very specific examples, but the underlying problem is that the default keyword is not clear enough in the specification.

We do not support $schema as a way of specifying the location of a schema.

In fact, we do not support the $schema keyword at all, but this is just to avoid different uses (for us it is just a uri specifying the address of the schema).

We rule out schemas that are not well formed.

From our point of view JSON Schema validators should analyze whenever schemas are not well formed, and give a syntax error. This is why we rule out badly formed schemas in our syntax.