Make missing and uncertain evidence representable

Learning objective

Design schemas for absent and ambiguous evidence using nullable fields, unclear, and extensible other plus detail values.

Core idea

A schema should permit the facts your document can support, including the fact that it does not support a value. If every invoice must produce a non-null purchase-order number, a document without one cannot be represented faithfully: the required non-null field pressures Claude to supply a value even when the source lacks one. Strict mode guarantees its permitted type, not that the value appears in the document.

Design separate representations for three cases: a value is absent, a category is ambiguous, or a category is clear but missing from your enum. Nullable fields handle absent values. An unclear enum member handles unresolved classification. An other member with a detail field preserves a known category outside the named list.

These are application-defined meanings, not built-in Anthropic category values. You define them in the schema and explain them in the prompt and field descriptions. The API enforces the supported shape; your consumer decides what each state permits downstream.

How it works

Distinguish presence from a nullable value

JSON Schema’s required array controls whether a property must exist. A property’s type controls its permitted value types. Those are independent decisions, as introduced in 0.3.

For an extraction record, po_number with type: ["string", "null"] and a place in required must exist but can carry null; omitting it from required independently permits the key to be absent. See 0.3 for the full presence-versus-value mechanics.

For a fixed extraction record, a required nullable field is often clearer for consumers: every record has the same keys, while null represents missing source evidence. That is a contract choice rather than a universal requirement of strict mode. Anthropic supports optional properties as well as null types.

Do not use the string "null" or a placeholder purchase-order number for the missing state. A schema permitting JSON null makes the absence explicit without requiring the consumer to recognize a special string. State the intended meaning: “Use null when the source does not state a purchase-order number; do not substitute the invoice or shipment reference.”

Give categories two different escape values

A closed enum such as goods, services, and freight is convenient for reporting, but not every document fits it. Add other when the document clearly identifies something outside that list, and a category_detail string to retain what it identifies.

For example, an invoice explicitly labelled “customs duty” can produce category: "other" and category_detail: "customs duty". The detail lets a consumer preserve that evidence without immediately changing its main category enum. Adding a dedicated category later changes the contract; preserving the detail lets you defer that decision without losing the source category.

Use unclear when the source does not support a confident category. “Q3 support pack” without an explanation might not distinguish a physical goods bundle from a service. That is different from recognizing customs duty and finding no matching enum member. Do not use other as a catch-all for both known unlisted categories and unresolved interpretation.

Describe when to choose each value in the field’s description. Keep the categories explicit rather than relying on ordinary English meanings to establish your pipeline’s handling policy. Anthropic documents an enum-capitalization exception for strict tool use and JSON outputs: compare values case-insensitively and avoid enum members whose only distinction is capitalization.

Define the record and the consumer rules

The following input_schema fragment makes each of those states representable:

{
  "type": "object",
  "properties": {
    "po_number": {
      "type": ["string", "null"],
      "description": "Purchase-order number stated in the source; null if absent."
    },
    "category": {
      "type": "string",
      "enum": ["goods", "services", "freight", "other", "unclear"],
      "description": "Use other for a clear unlisted category and unclear for unresolved evidence."
    },
    "category_detail": {
      "type": ["string", "null"],
      "description": "Name the evidenced category for other; otherwise use null."
    }
  },
  "required": ["po_number", "category", "category_detail"],
  "additionalProperties": false
}

Use this fragment inside a strict extraction tool, or as the schema in output_config.format for native JSON outputs. It uses the documented supported basic types, enum, required properties, and closed object shape.

The fragment makes a non-null detail possible; it does not enforce the relationship between category and category_detail. In the consumer, require an evidence-backed, nonempty detail when category is other. If category is unclear, hold the record for the application’s review path rather than allowing category-dependent automation. If po_number is null, do not issue an order-match operation that requires a stated number. These checks implement the meanings you assigned; they are not API behavior associated with the words other or unclear.

A legal missing value also does not prove faithful extraction. Claude can still omit evidence by selecting null despite a number on the page, or select a specific category when the document is ambiguous. Sample against source evidence and apply the semantic checks owned by 4.3.5.

Key distinctions and trade-offs

Use the following states to keep downstream decisions separate:

Optional keys can fit sparse records, while required nullable keys make absence uniform for consumers. Neither choice prevents invention by itself. Descriptions and prompts must make missing evidence a legitimate answer, and validation must check that the result follows those semantics.

Nullable fields also consume schema complexity. Anthropic’s structured-output limits allow 16 union-type parameters across the combined strict tool schemas and JSON output schemas in a request; type arrays such as ["string", "null"] count. The optional-parameter limit is 24 across that same combined scope. Keep the extraction record focused or split stages when those boundaries matter. Do not remove needed null states merely to make a large schema compile.

Architecture / decision scenario

A service receives three supplier documents. The first has no purchase-order number but clearly describes freight. The second names customs duty. The third only says “Q3 support pack.” All three must return a stable record shape without inventing classification evidence.

For the first, required nullable po_number carries null, while category carries freight and category_detail carries null. The order-match dispatcher checks po_number and does not attempt to search using a fabricated reference.

For the second, the extractor returns other with category_detail: "customs duty". The consumer checks that the detail is nonempty and supported by the document, then preserves it for category mapping. It does not reinterpret the unlisted category as uncertainty.

For the third, the extractor returns unclear. The consumer sends the record to the review path and blocks category-dependent automation. Tightening the enum to only three named categories would remove the faithful representation of this ambiguity. Retrying with the same insufficient evidence would not establish which category is correct.

The deciding design is the combination of legal missing states and explicit consumer branches. Strict mode makes these records structurally usable; evidence checks determine whether the chosen states are justified.

Common exam traps

• Treating optional and nullable as synonyms.
• Making every extracted value a required non-null string.
• Using "null" instead of JSON null.
• Treating other and unclear as the same condition.
• Adding other without a detail field or checking its meaning.
• Assuming a required detail key guarantees a nonempty explanation.
• Assuming nullable fields eliminate hallucination or prove absence.

Where the exam guide differs

What to remember

Make missing evidence legal without collapsing its meaning. Null represents an absent field value, unclear represents unresolved classification, and other plus detail preserves a recognized unlisted category. Required keys and nullable values are independent; consumer checks turn those states into permitted next actions.

Knowledge check

References

• Anthropic, Structured outputs
• Anthropic, Define tools
• JSON Schema, object
• JSON Schema, type
• Anthropic, Claude Certified Architect – Foundations Exam Guide