Skip to content

Understanding the Generated JSON Schema

Jump to bottom Edit New page
Alexey Valikov edited this page May 2, 2015 · 18 revisions

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:

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

Enum types

Enum types will be represented in JSON Schema as follows:

  • title is the name of the type;
  • enum types are considered to extend their base type (see the #Inheritance section below);
  • TODO - to be implemented the enum section lists the possible enum values;

Additional, non-standard sections are:

  • typeType is enumInfo;
  • typeName is the qualified name of the type in the originating XML Schema;

Example:

"ActuateType":{
    "allOf":[
        {
            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/string"
        }
    ],
    "enum":["onLoad", "onRequest", "other", "none"],
    "typeType":"enumInfo",
    "typeName":{
        "localPart":"actuateType",
        "namespaceURI":"http://www.w3.org/1999/xlink"
    }
}

Built-in types

Jsonix uses a number of "built-in" types, for instance all the XML Schema simple types. To use these types, we refer to the standard pre-defined JSON Schema for XML Schema:

http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema

The id of the type is formed by using the http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema# prefix and appending the local part of the type name. For example, xs:string will be referenced as follows:

{
    "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/string"
}

A few types are defined in the Jsonix own standard pre-defined JSON Schema:

http://www.jsonix.org/jsonschemas/jsonix/Jsonix.jsonschema

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:

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

Properties

Complex types may contain properties. In JSON Schema, these properties will be declared in the properties section of the JSON Schema of the comple type.

Property schemas will be explained in examples below. Structure of the property schemas depend on the type of the property (attribut, value, element property and so on), but have the following common parts:

  • title - name of the property;
  • allOf - declares the schema of the property contents;
  • propertyType - type of the property, one of:
    • value
    • attribute
    • anyAttribute
    • element
    • elements
    • elementRef
    • elementRefs
    • anyElement

Collection properties

If a property is a collection property, schema of the collection items will be wrapped in the array schema.

Example:

"coord":{
    "title":"coord",
    "allOf":[
        {
            "type":"array",
            "items":{
                "$ref":"#/definitions/CoordType"
            }
        }
    ],
    "propertyType":"element",
    "elementName":{
        "localPart":"coord",
        "namespaceURI":"http://www.opengis.net/gml"
    }
}

This is a collection property with CoordType-typed elements.

Value property

Example:

"value":{
    "title":"value",
    "allOf":[
        {
            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/string"
        }
    ],
    "propertyType":"value"
}

Attribute property

The attribute property contains the following additional sections:

  • attributeName - qualified name of the attribute in the originating XML Schema.

Example:

"codeSpace":{
    "title":"codeSpace",
    "allOf":[
        {
            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/string"
        }
    ],
    "propertyType":"attribute",
    "attributeName":{
        "localPart":"codeSpace",
        "namespaceURI":""
    }
}

Any attribute property

"otherAttributes":{
    "title":"otherAttributes",
    "allOf":[
        {
            "type":"object",
            "additionalProperties":{
                "type":"string"
            }
        }
    ],
    "propertyType":"anyAttribute"
}

Element property

The element property contains the following additional sections:

  • elementName - qualified name of the element in the originating XML Schema;
  • wrapperElementName - qualified name of the wrapper element (optional).
"billTo":{
    "title":"billTo",
    "allOf":[
        {
            "$ref":"#/definitions/USAddress"
        }
    ],
    "propertyType":"element",
    "elementName":{
        "localPart":"billTo",
        "namespaceURI":""
    }
}

Elements property

The elements property maps several elements and uses different types depending on the specific element name.

This is represented by the anyOf section of the property. The anyOf section lists possible element mappings. Each of the element schemas refers to a certain type and includes a non-standard elementName section which specifies the name of the element for this type.

The element property contains the following additional sections:

  • wrapperElementName - qualified name of the wrapper element (optional).
"geometricPositionGroup":{
    "title":"geometricPositionGroup",
    "allOf":[
        {
            "anyOf":[
                {
                    "anyOf":[
                        {
                            "$ref":"#/definitions/DirectPositionType"
                        }
                    ],
                    "elementName":{
                        "localPart":"pos",
                        "namespaceURI":"http://www.opengis.net/gml"
                    }
                },
                {
                    "anyOf":[
                        {
                            "$ref":"#/definitions/PointPropertyType"
                        }
                    ],
                    "elementName":{
                        "localPart":"pointProperty",
                        "namespaceURI":"http://www.opengis.net/gml"
                    }
                }
            ]
        }
    ],
    "propertyType":"elements"
}}

Element reference property

Example:

"name":{
    "title":"name",
    "allOf":[
        {
            "type":"object",
            "properties":{
                "name":{
                    "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
                },
                "value":{
                    "$ref":"#/definitions/CodeType"
                }
            },
            "elementName":{
                "localPart":"name",
                "namespaceURI":"http://www.opengis.net/gml"
            }
        }
    ],
    "propertyType":"elementRef",
    "elementName":{
        "localPart":"name",
        "namespaceURI":"http://www.opengis.net/gml"
    }
}

Element references property

Example:

"scalarValueList":{
    "title":"scalarValueList",
    "allOf":[
        {
            "anyOf":[
                {
                    "type":"object",
                    "properties":{
                        "name":{
                            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
                        },
                        "value":{
                            "$ref":"#/definitions/MeasureOrNullListType"
                        }
                    },
                    "elementName":{
                        "localPart":"QuantityList",
                        "namespaceURI":"http://www.opengis.net/gml"
                    }
                },
                {
                    "type":"object",
                    "properties":{
                        "name":{
                            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
                        },
                        "value":{
                            "type":"array",
                            "items":{
                                "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/string"
                            }
                        }
                    },
                    "elementName":{
                        "localPart":"CountList",
                        "namespaceURI":"http://www.opengis.net/gml"
                    }
                }
            ]
        }
    ],
    "propertyType":"elementRefs"
}

Any element property

Example:

"any":{
    "title":"any",
    "allOf":[
        {
            "anyOf":[
                {
                    "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/dom"
                },
                {
                    "type":"object",
                    "properties":{
                        "name":{
                            "$ref":"http://www.jsonix.org/jsonschemas/w3c/2001/XMLSchema.jsonschema#/definitions/QName"
                        },
                        "value":{
                        }
                    }
                }
            ]
        }
    ],
    "propertyType":"anyElement"
}
Add a custom footer
Clone this wiki locally