API Reference

generate_schema(T; ctx=SchemaContext(), simplify=true, inline_all_defs=false)

Variant of generate_schema! that clones the provided context before generation. The original ctx is unaffected.

If simplify=true (default), the schema is simplified by removing unused definitions, inlining single-use references, and sorting definitions.

If inline_all_defs=true, all $ref references are expanded inline and the $defs section is removed entirely (except for recursive definitions which must remain in $defs). This option takes precedence over simplify.

generate_schema!(T; ctx=SchemaContext(), simplify=true, inline_all_defs=false)

Materialize a schema for T using the provided mutable context. ctx is updated in-place and the function returns a named tuple with doc (the JSON schema document) and unknowns (newly encountered unsupported types).

If simplify=true (default), the schema is simplified by removing unused definitions, inlining single-use references, and sorting definitions.

If inline_all_defs=true, all $ref references are expanded inline and the $defs section is removed entirely (except for recursive definitions which must remain in $defs). This option takes precedence over simplify.

SchemaContext

Holds all state required while generating JSON Schemas. The context tracks $defs, previously computed keys, the current traversal path, override registrations, and knobs for auto-detecting optional fields. Construct a context with SchemaContext() and pass it to the API helpers.

UnknownEntry

Represents a type that could not be processed, with a reason.

Fields

• type::Any: The type that could not be processed
• path::Tuple{Vararg{Symbol}}: The path where the type was encountered
• reason::String: The reason why processing failed

override_abstract!(ctx, A; variants, discr_key, tag_value, require_discr=true)

Register a discriminator schema for the abstract type A. variants must be a vector of concrete subtypes, discr_key the discriminator field name, and tag_value a Dict mapping each variant to a JSON scalar tag. When require_discr is true the discriminator field is marked as required.

override!(generator, ctx)

Append a generic override function. generator receives the live SchemaContext and must return a replacement schema Dict or nothing to allow later overrides/default generation to run. Exceptions are caught; when ctx.verbose is true a warning is logged before falling back to the next candidate.

override_type!(generator, ctx, T)

Convenience wrapper over override! that only fires when the currently generated type is exactly T. The supplied generator should return the full replacement schema for that type.

override_field!(generator, ctx, T, field)

Register a context-aware override for the field field on struct T. The override runs while the field is visited and may return any schema Dict. Returning nothing falls back to downstream overrides or the default $ref.

optional!(ctx, T, fields...)

Mark specific fields on T as optional regardless of their declared types. fields may be supplied as a collection of Symbols or as varargs.

describe!(ctx, T, field, description)

Register a description for the field field on struct T. The description will be added to the JSON Schema as the description property. Manual registration takes priority over automatic extraction via REPL.fielddoc.

Enable automatic Union{T,Nothing} → optional field detection.

Enable automatic Union{T,Missing} → optional field detection.

auto_optional_null!(ctx)

Helper that enables both Union{T,Nothing} and Union{T,Missing} detection in one call.

skip!(ctx, T, fields...)

Mark specific fields on T to be completely skipped (excluded from schema generation). Skipped fields will not appear in properties or required. fields may be supplied as a collection of Symbols or as varargs.

only!(ctx, T, fields...)

Mark that only the specified fields on T should be included in the schema. All other fields will be skipped. This is the inverse of skip!. fields may be supplied as a collection of Symbols or as varargs.

defaultvalue!(ctx::SchemaContext, instance) -> Nothing

Register default values for all fields of a struct instance (recursively).

Example

ctx = SchemaContext()
defaultvalue!(ctx, ServerConfig("localhost", 8080))

defaultvalue_serializer!(ctx::SchemaContext, serializer::Function) -> Nothing

Register a custom serializer for default values.

Serializers are evaluated in FIFO order. Return nothing to fall through.

Example

defaultvalue_serializer!(ctx) do field_type, value, ctx
    value isa MyType ? serialize_my_type(value) : nothing
end

defaultvalue_type_serializer!(ctx::SchemaContext, T::Type, serializer::Function) -> Nothing

Register a custom serializer for all values of type T.

Example

defaultvalue_type_serializer!(ctx, Color) do value, ctx
    "#" * join(string.(value.r, value.g, value.b), base=16, pad=2)
end

defaultvalue_field_serializer!(ctx::SchemaContext, Parent::Type, field::Symbol, serializer::Function) -> Nothing

Register a custom serializer for a specific field.

Example

defaultvalue_field_serializer!(ctx, Metrics, :created_at) do value, ctx
    Int(datetime2unix(value))
end