google--langextract/docs/examples/output_schema.md

# Custom Output Schema Example

LangExtract usually derives provider schema constraints from examples. For
advanced cases, pass `output_schema` to constrain the raw model output more
directly. This example restricts a `status` attribute to the enum values
`present` and `absent`.

Examples are optional when `output_schema` is provided. When examples are
included, they still guide the prompt; `output_schema` replaces only the
provider schema constraint. The schema must describe LangExtract's JSON output
envelope with a top-level `extractions` array.

Gemini and OpenAI support `output_schema`. Ollama does not currently support
user-provided output schemas.

The helper emits `additionalProperties: False` so schemas work with OpenAI
strict structured outputs. Gemini receives user-provided schemas through its
native JSON Schema field, so JSON Schema keywords such as
`additionalProperties` are preserved.

## Full Pipeline Example

```python
import langextract as lx

# Text with one affirmed and one negated condition.
input_text = "Patient has hypertension. Patient denies diabetes."

# Define extraction prompt.
prompt_description = """
Extract medical conditions and classify each condition status as present or
absent. Use exact text from the input for extraction_text.
"""

# Define example data. The status values mirror the enum in output_schema.
examples = [
    lx.data.ExampleData(
        text="Patient has asthma. Patient denies fever.",
        extractions=[
            lx.data.Extraction(
                extraction_class="condition",
                extraction_text="asthma",
                attributes={"status": "present"},
            ),
            lx.data.Extraction(
                extraction_class="condition",
                extraction_text="fever",
                attributes={"status": "absent"},
            ),
        ],
    )
]

# Build a LangExtract output envelope with an enum-constrained attribute.
output_schema = lx.schema.extractions_schema(
    lx.schema.extraction_item_schema(
        "condition",
        attributes={
            "status": {
                "type": "string",
                "enum": ["present", "absent"],
            }
        },
    )
)

result = lx.extract(
    text_or_documents=input_text,
    prompt_description=prompt_description,
    examples=examples,
    model_id="gemini-3.5-flash",
    output_schema=output_schema,
    temperature=0.0,
)

print(f"Input: {input_text}\n")
print("Extracted conditions:")
for extraction in result.extractions:
    status = extraction.attributes["status"]
    print(f"• {extraction.extraction_text}: {status}")
```

This will produce output similar to:

```text
Input: Patient has hypertension. Patient denies diabetes.

Extracted conditions:
• hypertension: present
• diabetes: absent
```

## Multiple Extraction Classes

For heterogeneous extraction classes, pass multiple item schemas. The helper
wraps them in `anyOf` under `extractions.items`:

```python
output_schema = lx.schema.extractions_schema(
    lx.schema.extraction_item_schema("condition"),
    lx.schema.extraction_item_schema("medication"),
)
```

## Raw Schema Equivalent

For full control, pass a raw JSON schema dictionary. When targeting OpenAI
strict mode, every object schema must declare `required` fields and
`additionalProperties: False`.

Attribute objects use the `<extraction_class>_attributes` property name.
LangExtract's resolver expects that suffix when parsing raw model output.
Each extraction item should use extraction-class text keys such as
`condition`; generic fields such as `extraction_class`, `extraction_text`,
and `attributes` are not resolver output keys. Extraction class names ending
in `_attributes` are reserved for attribute objects.

The full pipeline example above produces this equivalent envelope:

```python
output_schema = {
    "type": "object",
    "properties": {
        "extractions": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "condition": {"type": "string"},
                    "condition_attributes": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "enum": ["present", "absent"],
                            }
                        },
                        "required": ["status"],
                        "additionalProperties": False,
                    },
                },
                "required": ["condition", "condition_attributes"],
                "additionalProperties": False,
            },
        }
    },
    "required": ["extractions"],
    "additionalProperties": False,
}
```

Use raw schemas when you need JSON Schema constructs that the helpers do not
cover directly, such as custom `anyOf` variants. OpenAI strict structured
outputs support `anyOf`; use `strict=False` only in lower-level provider code
if you need to experiment with schema features outside OpenAI's strict subset.

## Optional Attributes

The helper marks every supplied attribute as required by default so the schema
is compatible with OpenAI strict structured outputs. To allow an attribute to
be absent in practice, make the value nullable while keeping the key required:

```python
output_schema = lx.schema.extractions_schema(
    lx.schema.extraction_item_schema(
        "condition",
        attributes={
            "status": {
                "anyOf": [
                    {"type": "string", "enum": ["present", "absent"]},
                    {"type": "null"},
                ]
            }
        },
    )
)
```

If you need a schema where an attribute key may be omitted entirely, use a raw
schema for that provider-specific shape.

## Errors and Pitfalls

- Invalid envelopes raise `InferenceConfigError` before provider construction.
- `output_schema` can be passed with either `model_id`/`config` or a
  preconfigured `model` when the provider supports user schemas.
- Examples are optional with `output_schema`. When supplied, keep example
  classes and attribute names aligned with the schema to avoid confusing the
  model.
- `output_schema` requires raw JSON provider output. Leave `format_type` unset
  or set it to `lx.data.FormatType.JSON`, and do not force fences.
- Keep the resolver's default `"_attributes"` suffix. Custom
  `attribute_suffix`/`extraction_attributes_suffix` settings are incompatible
  with the raw schema envelope.
- Do not combine `output_schema` with provider schema kwargs such as
  `response_format`, `response_schema`, or `response_json_schema`.
- When targeting Gemini 2.0 models, add Gemini's `propertyOrdering` keyword
  to object schemas that need an explicit property order. The LangExtract
  helpers stay provider-neutral and do not add that Gemini-specific extension.
- Raw schemas must describe `extractions.items` inline, including each
  extraction text key and `<extraction_class>_attributes` object. LangExtract
  does not resolve `$ref` for those resolver keys before provider construction.
- Use `anyOf`, not `oneOf`, for item unions. Gemini treats `oneOf` like
  `anyOf`, and OpenAI strict structured outputs reject `oneOf`.
- `lx.schema.extraction_item_schema(..., additional_properties=False)` applies
  that setting to both the outer extraction item object and its nested
  `<extraction_class>_attributes` object.
- OpenAI uses strict structured outputs by default with LangExtract's default
  schema name. The lower-level `OpenAISchema.from_schema_dict(...,
  schema_name=..., strict=False)` constructor is an escape hatch for callers
  configuring provider models directly.
- LangExtract validates only the output envelope locally; the provider API
  validates the JSON schema itself. OpenAI strict mode requires every object
  to list all properties in `required` and set
  `additionalProperties: false` — the `lx.schema` helpers emit compliant
  schemas, and the OpenAI API reports the exact path of any violation in
  hand-written schemas. Schema size/depth limits, enum limits, and keyword
  support also vary by provider, model, and endpoint.
- Avoid `stop`/`stop_sequences` with `output_schema`: stop sequences can
  truncate schema-constrained JSON mid-document while the response still
  reports a normal finish reason.