API Reference

schema(
    schema_type::Type;
    use_references::Bool = false,
    dict_type::Type{<:AbstractDict} = JSON.Object,
    llm_adapter::LLMAdapter = STANDARD,
    enum_duplicate_policy::Symbol = :dedupe
)::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.

enum_duplicate_policy controls how annotation enum duplicates are handled after conversion to strings:

• :dedupe (default) keeps the first instance and removes repeats.
• :error throws an ArgumentError on duplicates.

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)

schema(
    fn::Function;
    selector::Union{Int,Method,Function}=1,
    method_annotation::Union{Nothing,MethodAnnotation}=nothing,
    use_references::Bool=false,
    dict_type::Type{<:AbstractDict}=JSON.Object,
    llm_adapter::LLMAdapter=STANDARD,
    enum_duplicate_policy::Symbol=:dedupe
)::AbstractDict{String,Any}

Generate a JSON Schema dictionary from a Julia function method.

• selector chooses the function method (index, Method, or selector function).
• method_annotation allows explicit naming/description/per-arg metadata.
• llm_adapter=OPENAI_TOOLS emits a tool/function-calling wrapper.
• llm_adapter=OPENAI emits a structured-output wrapper.

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{Union{String,Symbol}}} — 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

ArgAnnotation(; name, description=nothing, enum=nothing, required=true, llmexclude=false, userprovided=false)

Annotation metadata for one function argument.

MethodAnnotation(; name, description=nothing, argsannot=Dict())

Annotation metadata for a function method.

MethodSignature

Extracted signature model for one Julia function method.

PositionalArg

Internal representation of an extracted positional function argument.

KeywordArg

Internal representation of an extracted keyword function argument.

extractsignature(fn::Function, selector::Union{Int,Method,Function}=1) -> MethodSignature

Extract a function-method signature into a schema-friendly representation.

annotate!(ms::MethodSignature, ma::MethodAnnotation)

Apply method/argument annotations to an extracted method signature.

For safety, all arguments in ms must be present in ma.argsannot.

callfunction(
    fn::Function,
    arguments::Union{AbstractString,AbstractDict};
    selector::Union{Int,Method,Function}=1,
    method_annotation::Union{Nothing,MethodAnnotation}=nothing,
)

Call a Julia function from JSON-like arguments using extracted method metadata.

• arguments can be a JSON string or dictionary-like object.
• Supports OpenAI-style { "arguments": "{...}" } and { "arguments": {...} }.
• Validates required/extra keys, coerces JSON values into Julia argument types, and invokes fn with positional and keyword arguments.

_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.

Normalize annotation enum values for JSON output.

Converts symbols/strings to strings. Duplicate handling is controlled by enum_duplicate_policy:

• :dedupe keeps first-seen order and removes repeats.
• :error throws ArgumentError when a duplicate is found.