Function schema

Converts a resource shape into a JSON Schema.

A resource is described as an object with one property per member. Like the shape, the object is closed and admits no other property. Members requiring at least one value are required, and a member admitting more than one value is described as an array of its range. Identifier and class members are left out, as they name the resource rather than describe it, so a payload stating them is rejected. A reference is described as the IRI it carries, and an embedded resource as a nested object. A union is described as the alternatives it admits, so the schema accepts a value conforming to any one of its branches.

Value constraints are carried through: the bounds of a number and whether it is an integer, and the values, length bounds and lexical pattern of a string. A string in a well-known lexical form also carries the matching format, a hint for the consumers that recognise it about the kind of value expected and how to present or check it:

• url as uri, iri as iri-reference
• email as email
• date as date, time as time
• instant and timestamp as date-time

Values are still held to the pattern alone: a validator asserting formats may reject values the shape admits, such as a time with no zone offset, so formats are best read as annotations rather than as constraints.

The name and description of a resource and of each member are carried as title and description. A member admitting more than one value annotates the array rather than its items. Localised names and descriptions are carried in English, and are left out if they are stated in no English, as a schema has room for one language only.

A strict schema keeps to the subset of JSON Schema accepted by strict structured output generators. Every member is required. An optional single-valued member also admits null for an absent value, and an absent multi-valued member is stated as an empty array. A payload generated under a strict schema therefore conforms to the shape only once its null members are dropped. No string carries the uri or iri-reference format: IRI strings are held to their pattern, and references only to being strings, as strict generators reject both formats.

The returned schema is deeply immutable. Conversions are cached, so converting the same shape again with the same options returns the same schema at no cost, whether the shape is passed as is or deferred. Cached schemas are kept for the lifetime of the module, so shapes are best declared once rather than built anew on each conversion.