AshOaskit.TypeMapper (AshOasKit v0.4.1)

View Source

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

Decimal output and defaults use exact strings, matching AshJsonApi. Bounds are retained as x-ash-minimum/x-ash-maximum strings and enforced by Ash, since JSON Schema numeric bounds do not apply to decimal strings. Pass direction: :input to accept numeric decimal inputs as well as strings.

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 with an explicit type. $ref schemas use anyOf with a typed, null-only alternative.
  • OpenAPI 3.1: Uses type arrays like ["string", "null"]; $ref schemas are wrapped in anyOf with a null type.

Supported Types

Ash TypeJSON Schema TypeFormat
:stringstring-
:ci_stringstring-
:integerinteger-
:floatnumberfloat
:decimalstringexact decimal pattern
:booleanboolean-
:datestringdate
:timestringtime
:time_usecstringtime
:datetimestringdate-time
:utc_datetimestringdate-time
:utc_datetime_usecstringdate-time
:naive_datetimestringdate-time
:durationstringduration
:uuidstringuuid
:uuid_v7stringuuid
:binarystringbinary
:url_encoded_binarystringbyte
:mapobject-
:keywordobject-
:tupleobject-
:atomstring-
:modulestring-
:term(empty schema)-
:function(empty schema)-
:vectorarray of number-
{:array, type}arrayitems: nested type

Advanced Types

Ash TypeJSON SchemaNotes
Ash.Type.UnionanyOfWith optional discriminator
Ash.Type.StructobjectWith constrained properties
Ash.Type.Filestring (byte)Base64 encoded content
Ash.Type.DurationNamestringEnum from the type's values/0
Ash.Type.Enum implementorsstringEnum from the type's values/0
Ash.TypedStruct modulesobjectTyped properties and required list from the field definitions
Ash.Type.NewType wrappers(subtype schema)Resolved via subtype_of/0
Custom typesCalls json_schema/1If defined on type

Supported Constraints

Ash ConstraintJSON Schema Property
:min_lengthminLength
:max_lengthmaxLength
:minminimum
:maxmaximum
:match (Regex)pattern
:one_ofenum
array :min_lengthminItems
array :max_lengthmaxItems
array :itemsConstraints applied to items
array :nil_items?Nullable items schema
UUIDv7 :strict?Version 7 UUID pattern

Additional Schema Properties

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

Summary

Functions

embedded_types(attr)

Returns embedded resource modules reachable through a field's declared type and constraints.

normalize_type(type)

Normalizes built-in Ash type modules to their atom aliases without resolving custom types.

to_json_schema_30(attr, opts \\ [])

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

to_json_schema_31(attr, opts \\ [])

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

Functions

embedded_types(attr)

@spec embedded_types(map()) :: [module()]

Returns embedded resource modules reachable through a field's declared type and constraints.

normalize_type(type)

@spec normalize_type(atom()) :: atom()

Normalizes built-in Ash type modules to their atom aliases without resolving custom types.

to_json_schema_30(attr, opts \\ [])

@spec to_json_schema_30(map(), keyword()) :: 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, opts \\ [])

@spec to_json_schema_31(map(), keyword()) :: 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"}