JSON Schema is a declarative language for annotating and validating JSON document's structure, constraints, and data types. It helps you standardize and define expectations for JSON data.

Zoi provides functionality to convert its type definitions into JSON Schema format, enabling seamless integration with systems that utilize JSON Schema for data validation and documentation.

Example

iex> schema = Zoi.map(%{name: Zoi.string(), age: Zoi.integer()})
iex> Zoi.to_json_schema(schema)
%{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  type: :object,
  properties: %{
    name: %{type: :string},
    age: %{type: :integer}
  },
  required: [:name, :age],
  additionalProperties: false
}

Supported Types

The following Zoi types are supported for conversion to JSON Schema:

• Zoi.string/0
• Zoi.integer/0
• Zoi.float/0
• Zoi.number/0
• Zoi.decimal/0 - (converted to JSON Schema number)
• Zoi.boolean/0
• Zoi.literal/1
• Zoi.null/0
• Zoi.array/1
• Zoi.tuple/1
• Zoi.enum/1
• Zoi.map/2
• Zoi.intersection/1
• Zoi.union/1
• Zoi.nullable/1
• Zoi.date/0 and Zoi.ISO.date/0
• Zoi.datetime/0 and Zoi.ISO.datetime/0
• Zoi.naive_datetime/0 and Zoi.ISO.naive_datetime/0
• Zoi.time/0 and Zoi.ISO.time/0

Metadata

Zoi.to_json_schema/1 can also incorporate description, example, and deprecated metadata into the resulting JSON Schema:

iex> schema = Zoi.string(description: "A simple string", example: "Hello, World!")
iex> Zoi.to_json_schema(schema)
%{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  type: :string,
  description: "A simple string",
  example: "Hello, World!"
}

When a schema is marked as deprecated, the generated JSON Schema will include deprecated: true (the deprecation message itself is not part of JSON Schema):

iex> schema = Zoi.string(deprecated: "Use another field")
iex> Zoi.to_json_schema(schema)
%{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  type: :string,
  deprecated: true
}

Limitations

• Complex types or custom types not listed above will raise an error during conversion.
• Some advanced Zoi features may not have direct equivalents in JSON Schema.
• Refinements are partially supported, primarily for string patterns and length constraints.
• Additional properties in objects are disallowed by default (additionalProperties: false).

References

• JSON Schema Official Website