Understanding the Generated JSON Schema

Understanding the generated JSON Schema

If you've turned on the JSON Schema generation, Jsonix Schema Compiler will produce one more JSON Schema files for each your modules according to the configuration.

Single-mapping module

We'll start with a single-maping module, that is, a module which contains just one mapping (see Modules and Mappings for more information).

The JSON Schema for a single-mapping module will contain:

• the id of the schema (see Mapping Configuration);
• the definitions sections which declares complex and enum types;
• the anyOf section which lists possible top-level elements as qualified name/expected value type pair.

Here's what it looks like:

{
    "id":"MyMapping.jsonschema#",
    "definitions":{
        "MyComplexType":{ "type":"object", ... },
        "MyEnumType":{ "type":"string", ... },
        ...
    },
    "anyOf":[
        {
            "type":"object",
            "properties":{
                "name":{
                    "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
                },
                "value":{
                    "$ref":"#/definitions/MyComplexType"
                }
            },
            "elementName":{
                "localPart":"myComplexElement",
                "namespaceURI":""
            }
        },
        ...
    ]
}

Mapping schema id

The id of the mapping schema is generated based on the Mapping Configuration (see the schemaId attribute). By default this will be ${mapping.targetNamespace}#. For example, for the XLink 1.0 XML Schema you'll get http://www.w3.org/1999/xlink# as JSON Schema id, but you may also configure your own value.

The schema id is important as it will be used to refer to that schema using the $ref property (see [the specification](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-030 for more information).

Multi-mapping module

If the module contains several mappings, it's structure will be a bit more complex:

• the module schema will get its own schema id (see Module Configuration);
• the definitions sections will contain schemas for individual mappings;
• the anyOf section will refer to the schemas of the individual mappings via $ref - id.

Here's what it looks like:

{
    "id":"A_B.jsonschema#",
    "definitions":{
        "A":{"id":"A.jsonschema#", "definitions" : {...}, "anyOf" : [ ... ]},
        "B":{"id":"B.jsonschema#", "definitions" : {...}, "anyOf" : [ ... ]}
    },
    "anyOf":[
        { "$ref":"A.jsonschema#" },
        { "$ref":"B.jsonschema#" }
    ]
}

Module schema id

Module schema gets its own identifier. By default this is ${module.name}.jsonschema#, so you'll get a schema id A_B.jsonschema# for the module named A_B. Module schema id is also configurable.

Top-level elements

The anyOf-section of the JSON Schema for mappings declares JSON structures for the top-level elements.

In the standard mapping style top-level elements are represented by the following structure:

• name - qualified name of the element;
• value - typed value associated with this element.

Accordingly, JSON Schema for top-level elements is declared as follows:

{
    "type":"object",
    "properties":{
        "name":{
            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
        },
        "value":{
            "$ref":"#/definitions/MyComplexType"
        }
    },
    "elementName":{
        "localPart":"myComplexElement",
        "namespaceURI":""
    }
}

Explanation:

• the structure is an object with two properties name and value;
• the name property is a qualified name (referring to the QName XML Schema type);
• the value property refers to the schema of th type associated with this top-level element (typically declared in the definitions section);

The top-level element schema also contains and additional elementName section which provides the name of the top-level element. This is not a JSON Schema keyword but is helpful to understand thereference to the original XML Schema.

Schemas of the top-level elements are listed in the anyOf section of the mapping's JSON Schema. The semantic of this is "any of this elements is exected on the top level".

Types

Jsonix mapping typically declares several types. Each type defined in the mapping will get its own schema which will be declared in the definitions section. Names of types will be used keys as keys in the definitions section; values are schemas of individual types.

Example:

{
    "id":"PurchaseOrder.jsonschema#",
    "definitions":{
        "Items.Item":{ ... },
        "PurchaseOrderType":{ ... },
        "USAddress":{ ... },
        "Items":{ ... },
    }
    "anyOf":[ ... ]
}

## Complex types

Complex types are described in JSON Schema as follows:

* `type` is `object`;
* `title` is the name of the type;
* `properties` lists properties of this complex type;

JSON Schema for complex types also contains the following non-standard sections:

* `typeType` is `classInfo` (Jsonix type of the type);
* `typeName` - qualified name of the type in the originating XML Schema;
* `propertiesOrder` - the order of properties of this type (this is irrelevant for JSON but useful for XML serialization).

Example:

```json
{
    "type":"object",
    "title":"USAddress",
    "properties":{
        "name":{ ... },
        "street":{ ... },
        "city":{ ... },
        "state":{ ... },
        "zip":{ ... },
        "country":{ ... }
    },
    "typeType":"classInfo",
    "typeName":{
        "localPart":"USAddress",
        "namespaceURI":""
    },
    "propertiesOrder":[
        "name",
        "street",
        "city",
        "state",
        "zip",
        "country"
    ]
}

## Inheritance

If the type extends another type, then it's schema is combined with the schema of the base type using the `allOf` keyword.

For example, assume the `OffsetCurveType` extends the `AbstractCurveSegmentType`. The schema for the `OffsetCurveType` will be composed as follows:

```json
"OffsetCurveType":{
    "allOf":[
        {
            "$ref":"#/definitions/AbstractCurveSegmentType"
        },
        {
            "type":"object",
            "title":"OffsetCurveType",
            ...
        }
    ]
}