API Reference

schema(
    schema_type::Type;
    use_references::Bool = false,
    dict_type::Type{<:AbstractDict} = JSON.Object,
    llm_adapter::LLMAdapter = STANDARD
)::AbstractDict{String, Any}

Generate a JSON Schema dictionary from a Julia type.

When llm_adapter is OPENAI, the schema is wrapped for the OpenAI response-format structured-output API ("schema" key).

When llm_adapter is OPENAI_TOOLS, the schema is wrapped for OpenAI function / tool calling ("parameters" key).

Both OpenAI modes enforce strict: true, additionalProperties: false, and require all fields (optional fields use ["type", "null"]).

When use_references is true, nested struct types are factored out into $defs and referenced via $ref.

Examples

struct Person
    name::String
    age::Int
end

DescribedTypes.annotate(::Type{Person}) = DescribedTypes.Annotation(
    name="Person",
    description="A person.",
    parameters=Dict(
        :name => DescribedTypes.Annotation(name="name", description="The person's name"),
        :age  => DescribedTypes.Annotation(name="age", description="The person's age")
    )
)

# Plain JSON Schema
schema(Person)

# OpenAI response-format (uses "schema" wrapper key)
schema(Person, llm_adapter=OPENAI)

# OpenAI tool/function calling (uses "parameters" wrapper key)
schema(Person, llm_adapter=OPENAI_TOOLS)

Annotation(; name, description="", markdown="", enum=nothing, parameters=nothing)

Metadata attached to a Julia type (or one of its fields) for JSON Schema generation.

Fields

• name::String — display name used in the schema
• description::String — human-readable description
• markdown::String — optional Markdown documentation
• enum::Union{Nothing,Vector{String}} — allowable enum values (if any)
• parameters::Union{Nothing,Dict{Symbol,Annotation}} — per-field annotations

annotate(::Type{T}) -> Annotation

Return the Annotation for type T.

Override this method to attach descriptions and field metadata to your types:

DescribedTypes.annotate(::Type{MyType}) = DescribedTypes.Annotation(
    name = "MyType",
    description = "A short description.",
    parameters = Dict(
        :field1 => DescribedTypes.Annotation(name="field1", description="..."),
    )
)

LLMAdapter

Enum selecting the LLM-provider schema format.

• STANDARD — plain JSON Schema
• OPENAI — wrapped for OpenAI structured-output response format ("schema" key)
• OPENAI_TOOLS — wrapped for OpenAI function/tool calling ("parameters" key)
• GEMINI — (placeholder) Google Gemini format

_is_openai_mode(adapter::LLMAdapter) -> Bool

Return true for any OpenAI-flavoured adapter (OPENAI or OPENAI_TOOLS). Used internally so that schema-generation rules shared by both modes are written once.