JSON Schema generated by Wizard
JSON Schema output
The wizard can generate a JSON Schema for a message model specification as part of step 3. The generated schema follows JSON Schema 2020-12 and comes with an example message. Besides JSON, the schema can also be downloaded as YAML.
This page explains how the wizard maps the elements of a message model to JSON Schema. JSON Schema as input describes the opposite direction.
Structure
| Message model | JSON Schema |
|---|---|
| Element with sub elements or attributes | object with properties |
| Element without sub elements, maximum multiplicity of 1 or less | A simple type, see datatype mapping |
| Element with a maximum multiplicity above 1 (or unbounded) | array, with minItems and maxItems for the multiplicities |
| Minimum multiplicity above 0 | The property is listed under required |
| Maximum multiplicity of 0 (forbidden) | The property is left out, because JSON Schema cannot express forbidden properties |
| Element definition | description |
| Additional properties allowed or not | additionalProperties |
The wizard offers two schema design styles: Russian Doll, where everything is defined in place, and Venetian Blinds, where reusable types are placed under $defs and referenced with $ref, for example "$ref": "#/$defs/Party". $defs is the location for reusable schemas in JSON Schema 2020-12, the version of the generated schema. The older definitions keyword is not used. The OpenAPI output has no $defs: there the reusable types are placed under components/schemas.
Value constraints such as patterns, ranges, fixed values and enumerations are added to the type as well, and take precedence over the default of the datatype. For example, a minInclusive on an xs:int replaces the default minimum of an xs:int.
Datatype mapping
The datatype of an element is usually one of the built-in XML Schema datatypes, which are also used by datatype properties in RDFS/OWL. The following tables show the JSON Schema type that the wizard generates for each of them.
Datatypes that are not listed in the tables below are not recognized. This also holds for an element without a datatype. Such an element is considered to refer to an individual of a class, so it becomes a string with format: uri-reference.
Text
| XML Schema datatype | JSON Schema |
|---|---|
xs:string, xs:normalizedString, xs:token, xs:language | string |
xs:Name, xs:NCName, xs:NMTOKEN, xs:NMTOKENS | string |
xs:ID, xs:IDREF, xs:IDREFS, xs:ENTITY, xs:ENTITIES | string |
xs:anyURI, xs:QName, xs:NOTATION | string |
xs:anySimpleType, xs:anyAtomicType | string |
xs:anyType | No type, so any value is allowed |
Numbers
| XML Schema datatype | JSON Schema |
|---|---|
xs:decimal, xs:float, xs:double | number |
xs:integer | integer |
xs:nonNegativeInteger | integer, minimum: 0 |
xs:positiveInteger | integer, minimum: 1 |
xs:nonPositiveInteger | integer, maximum: 0 |
xs:negativeInteger | integer, maximum: -1 |
xs:long | integer, range of a 64-bit signed integer |
xs:int | integer, range of a 32-bit signed integer |
xs:short | integer, range of a 16-bit signed integer |
xs:byte | integer, range of an 8-bit signed integer |
xs:unsignedLong, xs:unsignedInt, xs:unsignedShort, xs:unsignedByte | integer, from 0 up to the maximum of the unsigned type |
xs:totalDigits and xs:fractionDigits cannot be expressed in JSON Schema and are ignored, see value constraints.
Boolean and binary
| XML Schema datatype | JSON Schema |
|---|---|
xs:boolean | boolean |
xs:base64Binary | string, contentEncoding: base64 |
xs:hexBinary | string, contentEncoding: base16 |
Dates, times and durations
| XML Schema datatype | JSON Schema |
|---|---|
xs:dateTime, xs:date, xs:time | string with a pattern, see below |
xs:dateTimeStamp | string, format: date-time |
xs:duration, xs:dayTimeDuration, xs:yearMonthDuration | string, format: duration |
xs:gYear, xs:gYearMonth, xs:gMonth, xs:gMonthDay, xs:gDay | string |
Timezones
The timezone is optional in xs:dateTime, xs:date and xs:time, but required in xs:dateTimeStamp:
xs:dateTimehas an optional timezone, so both2026-11-03T12:56:55and2026-11-03T12:56:55+01:00are valid.xs:dateandxs:timehave an optional timezone as well, so2026-11-03and2026-11-03Z, or12:56:55and12:56:55+01:00are valid.xs:dateTimeStamphas a required timezone, so only values like2026-11-03T12:56:55+01:00or2026-11-03T12:56:55Zare valid.
The JSON Schema date-time format always requires a timezone (this comes from following RFC3339). Therefore xs:dateTimeStamp maps exactly to format: date-time. If xs:dateTime were mapped to date-time, values without a timezone would be rejected by a strict validator, even though they are valid according to XML Schema. The same holds for the JSON Schema time format, which requires a timezone, and the date format, which does not allow one. So for xs:dateTime, xs:date and xs:time the wizard generates a pattern that follows the XML Schema notation, with an optional timezone, instead of a format. Each of them gets a $comment in the schema that explains this.
If you need a stricter value for such an element, for example a specific format, add a pattern to the element. It replaces the generated pattern.
The generated patterns do not check whether the day exists in the month, so a value like 2026-02-31 is accepted.
Patterns
A pattern in a message model follows the XML Schema regular expression notation. The wizard converts it for JSON Schema:
- XML Schema patterns always have to match the whole value, while JSON Schema patterns match any part of it. So the wizard adds
^and$. When the pattern contains alternatives, likeNL|BE, it is grouped, resulting in^(?:NL|BE)$. - The XML Schema escapes
\iand\c(and their negations\Iand\C) for characters allowed in XML names have no JSON Schema equivalent. They are replaced by the equivalent character classes. Characters outside the basic multilingual plane are not included.
Other XML Schema specific notations, such as character class subtraction ([a-z-[aeiou]]) and block escapes (\p{IsBasicLatin}), are not converted.
Limitations
- Validators may ignore
format: since JSON Schema 2019-09 theformatkeyword is only an annotation by default. Check whether your validator has format validation enabled. - The
durationformat was introduced in JSON Schema 2019-09. Validators that only support older versions ignore it. - XML Schema and JSON Schema use different regular expression dialects, see patterns.