JSON Schema Format

The JSON Schema format supports import and export of JSON Schema definitions, enabling integration with API specifications and data validation workflows.

Overview

The JSON Schema format (identifier: jsonschema) provides bi-directional transformation between Mauro models and JSON Schema definitions. It supports multiple JSON Schema draft versions including:

  • Draft 4
  • Draft 6
  • Draft 7 (default)
  • Draft 2019-09
  • Draft 2020-12

Format Identifier

Format: jsonschema

File Extension: .json

MIME Type: application/schema+json

Direction Support

Direction Supported Version
Import Yes 1.3.0
Export Yes 1.3.0

Parameters

Parameter Direction Type Default Description
draft Both Choice draft-07 JSON Schema draft version: draft-04, draft-06, draft-07, 2019-09, 2020-12
includeExamples Export Boolean true Include example values in schema
$schema Export String (auto) Custom $schema URI (overrides draft parameter)
resolveRefs Import Boolean true Resolve $ref references during import

Schema Mapping

Mauro model elements map to JSON Schema as follows:

DataModel
Maps to root JSON Schema object with $schema and definitions
DataClass
Maps to object type with properties
DataElement
Maps to property with type constraints
DataType
Maps to type definition (string, number, boolean, object, array, null)
Enumeration
Maps to enum constraint

Import JSON Schema Draft 7

MauroImportExport.Cli import jsonschema schema.json model.json --param draft=draft-07

Export to JSON Schema 2020-12

MauroImportExport.Cli export jsonschema model.json schema.json \
    --param draft=2020-12 \
    --param includeExamples=true

Convert JSON Schema to DITA

MauroImportExport.Cli convert jsonschema dita schema.json documentation \
    --in-param resolveRefs=true \
    --out-param dita.generateMaps=true

Supported JSON Schema Features

  • Type validation: string, number, integer, boolean, object, array, null
  • String constraints: minLength, maxLength, pattern, format
  • Numeric constraints: minimum, maximum, multipleOf
  • Array constraints: minItems, maxItems, uniqueItems
  • Object constraints: properties, required, additionalProperties
  • Composition: allOf, anyOf, oneOf, not
  • References: $ref, $defs, definitions
  • Metadata: title, description, examples, default

Best Practices

  • Use draft-07 for maximum compatibility unless newer features are required
  • Include examples to aid schema understanding and testing
  • Use $ref for schema reuse and modularity
  • Provide descriptive titles and descriptions for all properties
  • Validate exported schemas using JSON Schema validators
  • Consider additionalProperties settings for API evolution