class

JSON::Schema::Definitions

Inherits Reference < Object

Collects the definitions of the types referenced while introspecting.

Passing an instance as refs to json_schema or JSON::Schema.introspect emits nested JSON::Serializable types and enums as $refs, instead of inlining them, and builds each referenced type's definition once:

refs = JSON::Schema::Definitions.new
MyType.json_schema(refs: refs) # nested types are {"$ref": "#/$defs/Nested"}
refs.resolve                   # => {"Nested" => {type: "object", ...}}

Types are named by type, never by shape, so two enums with the same members remain distinct definitions.

Constructors

new(prefix : String = "#/$defs/", &namer : String -> String)

Source

new(prefix : String = "#/$defs/")

Source

Class methods

normalise(type_name : String) : String

converts a type name into a definition name, using only the characters that OpenAPI allows in component names ([a-zA-Z0-9._-]).

The conversion is reversible, so distinct types never share a name. . and - never appear in a type name, they encode its separators: :: is ., (, ), , and | are -o, -c, -n and -p, and any other character is -u followed by its six digit hex code point.

normalise("Api::User")       # => "Api.User"
normalise("Page(Api::User)") # => "Page-oApi.User-c"

Source

Instance methods

name_for(type_name : String) : String | Nil

the definition name of a referenced type

Source

prefix

the $ref prefix, i.e. #/components/schemas/ for an OpenAPI document

Source

reference(klass : T.class, openapi : Bool | Nil = nil, nullable : Bool = false, description : String | Nil = nil) : JSON::Any forall T

registers the type, returning a reference to its definition

A description sits beside the $ref in JSON Schema 2020-12. OpenAPI 3.0 ignores siblings of a $ref, so there the reference is wrapped in an allOf along with nullable and the type of the definition (3.0.3 only applies nullable with a type)

Source

reference?(schema) : Bool

is the schema a bare $ref to one of these definitions

Source

resolve

builds the definitions of all the referenced types, returning schemas

Source

schemas

definition name => definition

Source

type_name(name : String) : String | Nil

the type name of a definition

Source