@callback allowed_combinations() :: [combination()]

Returns the list of supported schema combination types.

This specifies which JSON Schema combinators are allowed during conversion. Common values include :any_of, :one_of, and :all_of, corresponding to anyOf, oneOf, and allOf in the JSON Schema specification.

You can override this in a specific converter module if a provider supports only a subset.

@callback function_calling(schema :: map(), opts :: keyword()) :: json_schema :: map()

Converts a schema into a provider-specific JSON schema for function calling (tool use).

The resulting JSON schema can be used as the parameters field in a tool/function definition.

Options

The supported options are:

• :ordered_properties - If set to true, the properties of objects will be ordered according to the order they are defined in the schema. Default is false.

  When this option is enabled, the properties in the object schema should ideally be provided as a keyword list to preserve the order, since maps in Elixir do not retain insertion order. For providers like Gemini that support a separate propertyOrdering field, using a map may still work. However, if you're targeting multiple AI providers, using a keyword list is recommended to ensure consistent ordering behavior.

  Ordered properties may be serialized using Jason.OrderedObject to retain order in the resulting JSON string. This assumes that Jason is used for final serialization; other encoders are not currently supported for ordered output.

@callback keywords() :: map()

Returns a map of keyword-specific processors.

Each key represents a JSON Schema keyword (e.g., :pattern, :nullable), and its value is a module responsible for processing that keyword during conversion.

If a keyword is not explicitly handled, the behavior defined in LangSchema.Keyword.Default is applied.

See LangSchema.Keyword for more details about keyword processing and extension.

By default, returns an empty map.

@callback structured_output(schema :: map(), opts :: keyword()) :: json_schema :: map()

Converts a schema into a JSON schema wrapped in the provider-specific envelope for structured output.

This calls function_calling/2 internally and then passes the result through wrap/2.

Accepts the same options as function_calling/2, plus any provider-specific options used by wrap/2 (e.g., :name and :description for OpenAI).

@callback types() :: map()

Returns a map of custom type converters.

This allows overriding or extending the default type conversion logic for each type. Keys must be atoms (e.g., :string, :object), and values must implement the corresponding conversion logic.

See LangSchema.Type modules for how to define custom type converters.

By default, returns an empty map.

@callback wrap(json_schema :: map(), opts :: keyword()) :: json_schema :: map()

Wraps the resulting JSON schema into a final structure required by the target provider for structured output.

This function is used when a provider requires the JSON schema to be embedded within an additional enclosing structure. For example, OpenAI's Chat Completion expects the schema to be placed under a "schema" field.

This function is also designed to be compatible with the json_schema input expected by the LangChain library.

By default, it returns the JSON schema as-is. You can override this function in a specific converter module to modify the wrapping behavior.