Zoi.JSONSchema (Zoi v0.7.1)

View Source

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.object(%{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:

Metadata

Zoi.to_json_schema/1 will attempt to parse metadata defined on types. For more information, check the Zoi.metadata/1 documentation. The following metadata will be parsed on JSON Schema conversion:

  • :description - Adds a description field to the JSON Schema.
  • :example - Adds an example field to the JSON Schema.
iex> schema = Zoi.string(metadata: [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!"
}

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

Summary

Functions

encode(schema)

Functions

encode(schema)

@spec encode(Zoi.Type.t()) :: map()