All chapters
  1. Start hereParseable is not valid. Valid is not correct
  2. Foundations · 1From free text to fields and records: why contracts matter
  3. Foundations · 2Syntax, schema, semantics, business validity: four different kinds of right
  4. Foundations · 3JSON and JSON Schema: types, enums, nullable fields, unions and nested objects
  5. Building · 4Typed models: Pydantic in Python, records and Bean Validation in Java
  6. Building · 5Provider output modes: prompting, JSON mode, constrained decoding and tool arguments
  7. Building · 6Tool input, tool result, agent handoff, final response: four contracts on one path
  8. Building · 7Schema design: names, required or optional, and where each value came from
  9. Operating · 8Validation stages: parse, schema, cross-field, domain rules
  10. Operating · 9Errors and repair: retry, clarify, correct within bounds, fall back
  11. Operating · 10Schema evolution: versions, compatibility and migrations
  12. Operating · 11Security: a valid string can still be an attack
  13. Operating · 12Observing contracts: validation failures, schema drift and replay artifacts
  14. Operating · 13Testing contracts: golden examples, property-based tests, fuzzing and contract suites
  15. Reference · 14Frameworks and standards: what each one checks for you
  16. Reference · 15Advanced: partial objects in a stream, polymorphism, multilingual data and typed events
  17. Reference · 16The insurance lab: one submission, four contracts, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Reference · 15

Advanced: partial objects in a stream, polymorphism, multilingual data and typed events

What can be trusted before the object is complete, how one field can hold several shapes safely, what language and locale do to typed data, and events as contracts.

What you will understand
Partial objects
What may be shown while a recommendation streams in, and why nothing may be acted on.
Polymorphism
One field, several shapes, and a discriminator that makes errors readable.
Language and locale
"2,4 Mio." and "03/04/2026": where typed data meets human writing.
Typed events
A recommendation as an event with its own contract, read by consumers you do not know yet.

The earlier chapters treated an output as one finished object, checked once. Four situations break that picture. The underwriter cockpit wants to show the recommendation while the model is still writing it. An evidence list mixes emails, roof assessments and guidance passages, each with a different shape. A broker abroad writes "2,4 Mio. EUR" and "1.858 m²". And the recommendation, once stored, becomes an event that other systems consume. This page takes each in turn. Each section is short; the expert layer is in the folded blocks.

The model here is a scripted stand-in, so these results show how the mechanism works, not how good any model is.

Partial objects in a stream#

Plain English. Streaming means the provider sends the output piece by piece while the model writes it, instead of all at once at the end. For example: the cockpit receives {"recommendation": "esc first, then alate", "reasons": ["The application says, and so on.

Plain English. A partial object is the prefix of an object that has not finished arriving. For example: after 136 of 370 characters, the recommendation word is complete and the first reason is complete, but the second reason is still being written.

The temptation is obvious: the underwriter waits a few seconds for each recommendation, so show what has arrived. The danger is just as obvious once named. Here is the UW-004 recommendation read at four points, with parse_partial() from examples/uw-contracts/partial.py (real run in a scratch copy):

after 23 of 370 characters, closed=False
   recommendation     partial   safe=False show=None
after 136 of 370 characters, closed=False
   recommendation     complete  safe=True  show=escalate
   reasons            partial   safe=True  show=1 item(s)
after 316 of 370 characters, closed=False
   recommendation     complete  safe=True  show=escalate
   reasons            complete  safe=True  show=2 item(s)
   citations          complete  safe=True  show=1 item(s)
   missing            complete  safe=True  show=0 item(s)
   stated_confidence  partial   safe=False show=None
after 370 of 370 characters, closed=True
   recommendation     complete  safe=True  show=escalate
   reasons            complete  safe=True  show=2 item(s)
   citations          complete  safe=True  show=1 item(s)
   missing            complete  safe=True  show=0 item(s)
   stated_confidence  complete  safe=True  show=0.62
   requires_human     complete  safe=True  show=True
   policy_version     complete  safe=True  show=2026.2

Three rules come out of it, and they are design rules of this site, not a standard:

Kind of valueWhen it may be shownWhy
an enum wordonly when completeesc could become escalate or something that is not a word of the enum
a numberonly when something after it proves it endedat 316 characters the text ends in 0.6; the next character may make it 0.62 or 0.65
a listits complete items, as "so far"a complete reason will not change; the list may grow
true, false, null, a closed stringwhen completethey cannot grow
the whole objectonly after all four stagesuntil then, nothing is acted on

The last row is the one that matters. Showing is not acting. A complete "escalate" at character 30 is still unvalidated: the object may end with requires_human: false, or cite a rule that does not exist, or be cut off by the output limit. Routing the case to a senior underwriter's queue before the object is closed and has passed the four stages of the validation page acts on a value no check has seen. So the cockpit may render progress, labelled as provisional; it may not route, store or notify.

Moment (characters of 370)What is safe to showWhat is not
23nothingrecommendation is partial (esc)
136escalate; one complete reason, so farthe second reason
316the word, both reasons, the citation, missingstated_confidence (0.6 may grow)
370everything, as provisionalacting on it, until the four stages pass
Production pitfall. A stream that ends early (the output limit, a dropped connection) leaves a partial object that looks a lot like a complete one. Case UW-S03 is exactly that. The parser at the end must be the strict one, and a partial object must never be "completed" by code to make it parse (see repair).

Polymorphism: one field, several shapes#

Plain English. Polymorphism means one field can hold values of several different shapes. For example: an evidence item can be an email (with a quote), a roof assessment (with a roof age) or a guidance passage (with a rule id).

JSON Schema expresses this with oneOf: exactly one of the listed shapes must match. It works, and its errors are hard to read. The reason is in how oneOf decides: it tries every branch, and if none matches, all it can honestly say is "none matched". Here is a small evidence schema with three branches, run on three items (the schema is written for this page and run with the example's validator):

a roof assessment                  oneOf: ok
                                   by kind (roof_assessment): ok
kind says email, fields say roof   oneOf: matches 0 of 3 shapes; exactly one is required
                                   by kind (email):  missing required property "quote"; /evidence_id "EV-ROOF-0412" does not match ^EV-EMAIL-[0-9]{4}$; /roof_age_years property "roof_age_years" is not allowed
no kind at all                     oneOf: matches 0 of 3 shapes; exactly one is required
                                   by kind: unknown or missing kind

Plain English. A discriminator is a field whose value says which shape the rest of the object has. For example: "kind": "roof_assessment" says "validate me as a roof assessment".

With a discriminator, validation becomes two steps: read kind, then validate against that one branch and report that branch's errors. The second item shows the difference. oneOf alone says "matches 0 of 3 shapes". Validation by kind says the item claims to be an email and then lists exactly what is wrong for an email. A re-ask built from the second message gets fixed; one built from the first gets guessed at. The JSON Schema page covers unions and the discriminator pattern in the language itself.

Before AI. Java services that read polymorphic JSON usually add a type field that tells the reader which class to build, and event consumers on Kafka usually switch on an event type before reading the payload. Same idea: never make a reader guess the shape from the fields.

Language and locale#

Plain English. A locale is the set of conventions a person writes numbers, dates and units in. For example: in many European locales "2,4" is two point four and "1.858" is one thousand eight hundred fifty-eight.

JSON itself has no locale. RFC 8259 says "A fraction part is a decimal point followed by one or more digits", and that JSON text exchanged between systems that are not part of a closed ecosystem "MUST be encoded using UTF-8". So the contract side is fixed: numbers with a decimal point, text in UTF-8. The trouble is on the way in. The broker writes in their locale; the model reads it and writes JSON. Four places where that goes wrong:

What the broker writesRiskContract defence
"1.858 m²"read as 1.858 square metres, or as 1858 square feetarea_sq_ft integer, unit in the name, provenance with a declared conversion (case UW-S18)
"2,4 Mio. EUR"a string, a decimal in the wrong place, or the wrong currencybuilding_value_usd integer; currency conversion done by code, not by the model
"03/04/2026"3 April or 4 Marchdates as YYYY-MM-DD (format: date), and the quote kept in provenance
"Lagerhalle" (warehouse)an enum value in another languagethe enum stays English; the model maps the word, and the quote shows what it mapped

The last row deserves a sentence of its own. An enum is part of the contract, not of the language of the source. occupancy stays one of office, warehouse, retail, manufacturing, restaurant, mixed, whatever language the email was in. Translating enum values per locale multiplies every consumer's work and every check. Names of people and businesses are the opposite: they are free text, kept exactly as written, in UTF-8, with no "cleaning" that strips accents.

In our insurance agent. Every value read from a document carries its quote. For a non-English email the underwriter sees "1.858 m² (converted to 20,000 sq ft)" and "Lagerhalle (warehouse)", so a mistake in mapping is visible at a glance. The illustrative numbers are those of SUB-1004.

Typed events#

Plain English. A typed event is a record that something happened, with a declared type and a schema for its data. For example: "a recommendation was recorded for SUB-1004", of type recommendation.recorded, whose data follows recommendation_record.v1.

The recommendation record does not stay in one database. The audit export reads it, a reporting job counts it, a notification tells the senior underwriter, and next year some consumer nobody has planned yet. Each of them depends on its shape. Publishing the record as an event with an envelope makes that dependency explicit.

CloudEvents is a vendor-neutral specification for this envelope: it describes itself as "a vendor-neutral specification for defining the format of event data". Its required attributes are id ("Producers MUST ensure that source + id is unique for each distinct event"), source, specversion and type, and an optional dataschema names the schema of the data; the specification read on 2026-11-17 says producers "MUST use a value of 1.0" for specversion. A recommendation event in that shape (documented shape; not run here):

{
  "specversion": "1.0",
  "id": "run-7f01-rec",
  "source": "/underwriting/workflow",
  "type": "recommendation.recorded",
  "dataschema": "https://schema.sammuthu.com/schemas/recommendation_record.v1.json",
  "data": {"schema_version": 1, "submission_id": "SUB-1004", "run_id": "run-7f01", "attempt_number": 2, "status": "recommendation_ready", "requires_human": true, "human_decision": null}
}

(The data above is shortened; a real event carries the whole record.) Two properties of the envelope do the work. type lets a consumer decide whether it cares before it parses the data. dataschema names the exact contract, so a consumer can validate, and a breaking change gets a new URI, which is how evolution stays visible downstream.

Plain English. JSON Lines is a format with one JSON value per line. For example: a file of failure records, one per line, that can be appended to and read line by line. The format's page lists three rules: UTF-8, "Each Line is a Valid JSON Value", and lines ending in \n, with the extension .jsonl. It is the usual shape for logs of events and for replay sets of model outputs.

What this is not. Delivering events (brokers, ordering, retries, exactly-once) belongs to reliability and orchestration (reliable.sammuthu.com, orchestrate.sammuthu.com). Messages between agents as a protocol belong to a2a.sammuthu.com. This section is about the contract of the event's data.
For a coding agent. A coding agent streams its plan to a terminal while it writes it: the same rules apply. Show complete steps as "so far"; run nothing until the whole plan is closed and validated. Its change_report can be published as a typed event for CI and for dashboards. The runtime that streams it is on harness.sammuthu.com.

Diagram: Showing is not acting · what the cockpit may do while a recommendation streams in

Read left to right. Pieces of text arrive. The partial reader marks each field complete, partial or absent. Complete values may be shown as provisional. Only the closed object, after the four stages, may be routed or stored.

  1. Arrives
    1. Text so far: The provider sends the output piece by piece.
  2. Read
    1. Partial reader: Marks each field complete, partial or absent.
  3. May show
    1. Provisional view: Complete enum words, finished numbers, complete list items.
  4. May act
    1. Closed and validated: Only now route, store or notify.

Diagram: A stored record becomes a typed event · type and schema URI for consumers you do not know yet

Read left to right. Code writes the recommendation record, wraps it in an event envelope with a type and the URI of its schema, and publishes it. Each consumer decides by type and validates the data against the named schema.

  1. Written
    1. Recommendation record: The validated record with stamped identifiers.
  2. Wrapped
    1. Event envelope: Says what happened and which contract the data follows.
  3. Consumed
    1. Audit export: Appends events to a log, one JSON value per line.
    2. Notification: Cares only about escalations; ignores the rest by type.

Checklist#

Incremental validation of a streamFailing early on a prefix

Some checks can run on a prefix: a complete enum word that is not one of the four can be rejected at character 30, and the stream cancelled, saving the rest of the output. That is an optimization, safe only for checks whose answer cannot change as more text arrives (a complete value of the wrong type, an unknown key in a closed object). Cross-field and domain checks need the whole object. Cancel early on a definite schema failure; never accept early.

Unions under constrained decodingThe part of JSON Schema support that varies most

Providers that constrain output to a schema support a subset of JSON Schema, and unions, oneOf and $ref are where the subsets differ most. A discriminated union whose branches each have a const discriminator is the shape most likely to be supported and the easiest to validate afterwards. Check the current provider documentation before relying on it; the provider modes page records what each documentation said on the day it was read.

Event schemas outlive their producersConsumers you have never met

An event published today is read by consumers written next year, and replayed from a log in three years. So event schemas need the strictest evolution discipline of all contracts on this site: additive changes only within a schema URI, a new URI for anything breaking, and old URIs kept resolvable as long as events that name them exist. The tolerant reader is the norm for event consumers, with the caveats of the evolution page.

In one breath#

A stream hands you a prefix: show complete enum words, finished numbers and complete list items as provisional, and act on nothing until the whole object has passed the four stages. A field that can hold several shapes needs a discriminator, so a validator reports the errors of the shape the value claims to be. Locale belongs to the source, not the contract: numbers with a decimal point, dates as YYYY-MM-DD, enums in one language, conversions declared and quotes kept. And a stored record that others consume is an event with a type and a schema URI, evolved as carefully as any public API.

That completes the chapters. The insurance lab runs the whole example end to end, with every contract and case in one place.