Supported JSON Schema Keywords

OpenAPI 3.0 uses an extended subset of JSON Schema Specification Wright Draft 00 (aka Draft 5) to describe the data formats. “Extended subset” means that some keywords are supported and some are not, some keywords have slightly different usage than in JSON Schema, and additional keywords are introduced.

Supported Keywords

These keywords have the same meaning as in JSON Schema:

• title

• pattern

• required

• enum

• minimum

• maximum

• exclusiveMinimum

• exclusiveMaximum

• multipleOf

• minLength

• maxLength

• minItems

• maxItems

• uniqueItems

• minProperties

• maxProperties

These keywords are supported with minor differences:

• type – the value must be a single type and not an array of types. null is not supported as a type, use the nullable: true keyword instead.

• format – OpenAPI has its own predefined formats and also allows custom formats.

• description – supports CommonMark syntax for rich text representation.

• items – must be present if type is array. The item schema must be an OpenAPI schema and not a standard JSON Schema.

• properties – individual property definitions must follow OpenAPI schema rules and not standard JSON Schema.

• additionalProperties – the value can be a boolean (true or false) or an OpenAPI schema.

• default – the default value must conform to the specified schema.

• allOf – the subschemas must be OpenAPI schemas and not standard JSON Schemas.

• oneOf – the subschemas must be OpenAPI schemas and not standard JSON Schemas.

• anyOf – the subschemas must be OpenAPI schemas and not standard JSON Schemas.

• not – the subschema must be an OpenAPI schema and not a standard JSON Schema.

Unsupported Keywords

• $schema

• additionalItems

• const

• contains

• dependencies

• id,

• $id

• patternProperties

• propertyNames

Additional Keywords

OpenAPI schemas can also use the following keywords that are not part of JSON Schema:

• deprecated

• discriminator

• example

• externalDocs

• nullable

• readOnly

• writeOnly

• xml

References

OpenAPI 3.0 – Schema Object

JSON Schema Validation – JSON Schema keyword reference

JSON Schema Draft Wright 00 – Core JSON Schema Specification