# `Zoi.JSONSchema`
[🔗](https://github.com/phcurado/zoi/blob/v0.18.1/lib/zoi/json_schema.ex#L1)

[JSON Schema](https://json-schema.org/) 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:

```elixir
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):

```elixir
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](https://json-schema.org/)

# `encode`

```elixir
@spec encode(Zoi.schema()) :: map()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*