Normalize source values without inventing evidence

Learning objective

Pair output constraints with explicit normalization instructions for inconsistent source formats.

Core idea

A structured extraction needs two contracts: the allowed output structure and the rules for interpreting source values. A schema can require a string in invoice_date; that alone does not decide whether 03/04/26 means March 4 or April 3. A numeric amount likewise does not explain how to read a source that uses commas for decimal fractions.

For an architect designing document extraction, the decision is which requirements belong in the schema and which belong in the prompt. Use strict: true with an extraction tool’s input_schema, or native JSON output through output_config.format, for supported structural constraints. Put interpretation and normalization instructions in the request’s system prompt and field description values. See 4.3.2 for choosing the output interface.

These instructions guide the model; they do not turn an ambiguous source into evidence. Define what happens when the source cannot support one interpretation. See 4.3.4 for the nullable fields and uncertainty categories that make that outcome representable.

How it works

Separate representation from interpretation

Anthropic’s structured outputs support type, required, and selected string format values, including date. Objects must use additionalProperties: false. A schema therefore fixes the fields, their types, and supported formatting constraints. A field with type: "string" and format: "date" constrains the output’s date representation; it does not select a source’s regional convention.

Write the interpretation policy explicitly. For example, instruct the extractor to emit dates as year-month-day, interpret numeric dates using a convention stated in the document or trusted input metadata, and return the contract’s unresolved value if neither settles the order. A supplier’s address can be useful context, but it is weaker than an explicit date-format declaration. Do not silently replace a missing convention with a geographic guess.

The same distinction applies to amounts. A JSON number does not carry a currency symbol or preserve display-only trailing zeros. Decide whether the record contains decimal major units or integer minor units, and name the choice in the field description. In this lesson’s examples, amount uses major units and currency is separate. That is an application contract, not an Anthropic default.

Print rules close to the fields

Anthropic’s prompting guidance recommends explicit desired formats and constraints. Its tool documentation also recommends detailed descriptions of what each parameter means. Use those mechanisms together: shared rules in system, field-specific meaning in input_schema.properties.<field>.description, and targeted examples in the prompt when a transformation is otherwise ambiguous.

For a client extraction tool, input_examples on the tool definition demonstrates normalized target inputs; see 2.1.1. Each example must validate against input_schema: a null date example is valid only if the schema permits null, and an invalid example returns 400. The field shows target values only, so keep source-to-normalized-value pairs in prompt examples.

For an invoice extractor, a normalization policy might say:

Emit dates as YYYY-MM-DD. Interpret numeric dates only when the
document or supplied date_order metadata establishes their order.
Otherwise return null for that date.
Emit amount in major currency units as a JSON number. Use the source's
stated decimal and grouping conventions; keep currency separate.
Preserve identifier characters, including leading zeros.
Do not calculate an unstated due date from payment terms.

date_order is illustrative metadata supplied by this application, not a Messages API field. YYYY-MM-DD describes the intended output shape. The nullable date field must already permit null; a prompt cannot override a schema that requires a non-null string.

For due_date, the field description can say that it is the explicitly stated payment deadline, normalized to the agreed date representation. For invoice_number, say that the value is an identifier whose leading zeros remain intact. This reduces confusion between normalization and changing a value’s meaning.

Show the difficult transformations

Examples should distinguish clear conversions from cases that need more evidence. The following outcomes assume the application contract just defined:

Do not hide a second inference inside an example. Expanding a two-digit year requires a century rule or evidence; changing a date’s separator does not supply that rule. Likewise, converting Net 30 to a stated duration is different from calculating a due date. The latter needs a defined starting date and a policy for the calculation.

Key distinctions and trade-offs

Schema enforcement versus prompt guidance: A supported format constraint participates in constrained output generation. A field description explains how to interpret evidence but is not an additional validator. Keep both when the consumer needs a constrained representation and a particular meaning.

Normalization versus enrichment: Rewriting an explicit date in a canonical representation preserves its meaning. Deriving an unstated payment deadline adds information. Keep derived values separate from extracted values if the workflow needs both.

Consistency versus uncertainty: A uniform guessed date is easy to process and still wrong. A nullable output sacrifices automatic coverage to preserve an unresolved source fact. That is a useful trade when the downstream operation schedules payments.

Supported string formats do not make every JSON Schema constraint available. Anthropic documents unsupported numeric bounds and string-length constraints, and SDK helpers can move those constraints into descriptions. A description can guide generation while local validation still needs to enforce the original requirement. See 4.3.7 for handling that distinction.

Architecture / decision scenario

An accounts-payable service receives three supplier invoices. One writes its date in words. Another states a comma-decimal convention beside its amounts. The third uses 03/04/26 without a date-order declaration. The consumer requires canonical dates, numeric amounts, separate currency, and unchanged invoice identifiers.

The team defines extract_invoice with strict: true. Its input_schema constrains the record and permits a nullable invoice_date. The system prompt carries the shared normalization rules, and each field’s description names its source meaning. A few input/output examples demonstrate a successful conversion and an unresolved numeric date.

The first record receives the unambiguous normalized date. The second receives a numeric amount after interpreting the stated separator convention, with currency in its own field. The third receives null for its date and remains unresolved. The extractor preserves 000731 as a string rather than converting it to a number. A payment term does not become a fabricated due date.

If the output is structurally valid but puts the invoice date in due_date, normalization has not solved the defect. The service applies the semantic checks in 4.3.6. The architectural choice is to use strict constraints for representation, explicit prompts for interpretation, and source-based checks for correctness.

Common exam traps

• Assuming type: "string" makes all extracted dates consistent.
• Assuming format: "date" determines the source’s date order.
• Asking for a canonical output without specifying how to interpret separators.
• Treating a field description as a hard constraint.
• Converting identifiers to numbers and losing leading zeros.
• Using a normalization rule to justify an unstated due date.
• Requiring a non-null value while also instructing the model to return null for unresolved evidence.

What to remember

Use the schema to constrain the output and the prompt to explain the conversion. Name the source convention, target representation, and unresolved outcome. Normalization preserves supported meaning; it does not fill gaps in the source or replace semantic validation.

Knowledge check

References

• Anthropic, Structured outputs
• Anthropic, Define tools
• Anthropic, Claude prompting best practices
• Anthropic, Reduce hallucinations