AshOaskit.TypeMapper (AshOasKit v0.2.1)

Maps Ash types to JSON Schema types for OpenAPI 3.0 and 3.1.

This module handles the conversion of Ash resource attributes to their corresponding JSON Schema representations, respecting the differences between OpenAPI versions.

Version Differences

OpenAPI 3.0: Uses nullable: true for nullable fields. $ref schemas are wrapped in allOf first, because 3.0 ignores sibling keys next to $ref.
OpenAPI 3.1: Uses type arrays like ["string", "null"]; $ref schemas are wrapped in oneOf with a null type.

Supported Types

Ash Type	JSON Schema Type	Format
`:string`	`string`	-
`:ci_string`	`string`	-
`:integer`	`integer`	-
`:float`	`number`	`float`
`:decimal`	`number`	`double`
`:boolean`	`boolean`	-
`:date`	`string`	`date`
`:time`	`string`	`time`
`:time_usec`	`string`	`time`
`:datetime`	`string`	`date-time`
`:utc_datetime`	`string`	`date-time`
`:utc_datetime_usec`	`string`	`date-time`
`:naive_datetime`	`string`	`date-time`
`:duration`	`string`	`duration`
`:uuid`	`string`	`uuid`
`:uuid_v7`	`string`	`uuid`
`:binary`	`string`	`binary`
`:url_encoded_binary`	`string`	`byte`
`:map`	`object`	-
`:keyword`	`object`	-
`:tuple`	`object`	-
`:atom`	`string`	-
`:module`	`string`	-
`:term`	(empty schema)	-
`:function`	(empty schema)	-
`:vector`	`array` of `number`	-
`{:array, type}`	`array`	items: nested type

Advanced Types

Ash Type	JSON Schema	Notes
`Ash.Type.Union`	`anyOf`	With optional discriminator
`Ash.Type.Struct`	`object`	With constrained properties
`Ash.Type.File`	`string` (`byte`)	Base64 encoded content
`Ash.Type.DurationName`	`string`	Enum from the type's `values/0`
`Ash.Type.Enum` implementors	`string`	Enum from the type's `values/0`
`Ash.TypedStruct` modules	`object`	Typed properties and required list from the field definitions
`Ash.Type.NewType` wrappers	(subtype schema)	Resolved via `subtype_of/0`
Custom types	Calls `json_schema/1`	If defined on type

Supported Constraints

Ash Constraint	JSON Schema Property
`:min_length`	`minLength`
`:max_length`	`maxLength`
`:min`	`minimum`
`:max`	`maximum`
`:match` (Regex)	`pattern`
`:one_of`	`enum`

Additional Schema Properties

description - Copied from attribute description
default - Copied from attribute default (non-function values only)

Summary

Functions

to_json_schema_30(attr)

Convert an Ash attribute to a JSON Schema for OpenAPI 3.0.

to_json_schema_31(attr)

Convert an Ash attribute to a JSON Schema for OpenAPI 3.1.

Functions

to_json_schema_30(attr)

@spec to_json_schema_30(map()) :: map()

Convert an Ash attribute to a JSON Schema for OpenAPI 3.0.

In OpenAPI 3.0, nullable is represented with a boolean flag: {"type": "string", "nullable": true}

Examples

iex> attr = %{type: :string, allow_nil?: false}
...> AshOaskit.TypeMapper.to_json_schema_30(attr)
%{"type" => "string"}

iex> attr = %{type: :string, allow_nil?: true}
...> AshOaskit.TypeMapper.to_json_schema_30(attr)
%{"type" => "string", "nullable" => true}

to_json_schema_31(attr)

@spec to_json_schema_31(map()) :: map()

Convert an Ash attribute to a JSON Schema for OpenAPI 3.1.

In OpenAPI 3.1, nullable is represented as a type array: {"type": ["string", "null"]} instead of {"type": "string", "nullable": true}

Examples

iex> attr = %{type: :string, allow_nil?: false}
...> AshOaskit.TypeMapper.to_json_schema_31(attr)
%{"type" => "string"}

iex> attr = %{type: :string, allow_nil?: true}
...> AshOaskit.TypeMapper.to_json_schema_31(attr)
%{"type" => ["string", "null"]}

iex> attr = %{type: :uuid, allow_nil?: false}
...> AshOaskit.TypeMapper.to_json_schema_31(attr)
%{"type" => "string", "format" => "uuid"}