JSON Schema Document Support
These requirements, validations, and restrictions apply only for JSON Schemas parsed with the new JSON Schema configuration.
- JSON Schema draft 3
- JSON Schema draft 4
- JSON Schema draft 7
- JSON Schema draft 2019-09 (partially supported, more info in this section)
The input JSON Schema MUST:
- Contain the
$schemakeyword specifying the draft version
- Contain the sub-schemas under the key
definitions(valid for all the draft versions) or
$defs(valid for draft 2019-09)
- Contain only one declaration keyword,
$defs, not both.
The JSON Schema spec does not define a lot of logical validations of the schemas. For example, if you declare a JSON Schema that is unsatisfiable by definition (eg. empty enum), the schema definition is valid but will always fail when validating any instance.
In order to ensure that the schemas could be used from any API, AMF adds some schema validations on top of the basic JSON Schema validations.
Some of this
extra validations are:
- Max like constraints must be greater than min like constraints. e.g.: if an array schema has maxItems and minItems, the value of maxItems must be greater than the value of minItems.
- Enum cannot be empty
- Pattern format is validated
The references from an API could not point to any part of the JSON Schema. It must point to the root schema or to one sub-schema definition.
API RAML 1.0 with a valid JSON Schema reference
title: Some API
type: !include /schemas/schema.json#/$defs/PersonName
API RAML 1.0 with an invalid JSON Schema reference
title: Some API
type: !include /schemas/schema.json#/$defs/Person/properties/name