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

Glossary

Every term this site uses, each with what it is, what it is not, and how it shows up in the insurance example.

Every term this site uses, in one place. Each card opens the same explainer as the underlined words in the chapters: one line, how it shows up in the insurance example, what it is, what it is not, and related terms.

Three sentences hold the words apart. Parseable is not valid. Valid is not correct. A schema checks shape, not truth.

additionalPropertiesThe keyword that says what to do with keys the schema does not name. By default any extra key is allowed; false closes the object.AjvA JavaScript library that validates JSON against JSON Schema (drafts 04 to 2020-12) and JSON Type Definition, compiling schemas to JavaScript code.Allow-listA fixed list of values that are accepted. Anything else is rejected, never cleaned.attempt_numberA counter that starts at 1 for a run's first output and rises by one with each re-ask.Backward compatibleA new consumer can read data written under the old version.Bean ValidationA Java standard (Jakarta Validation) for declaring constraints as annotations, such as @NotNull, @Pattern or @DecimalMax, and checking an object against them.BoundaryAny place where data passes from one party to another and the receiver depends on its shape.Bounded retryA repair loop with a fixed maximum number of attempts and a defined outcome when it is reached.Breaking changeA change of a contract that makes some live reader or some stored record fail.Business validityLayer 4: the record is true against the policy fixture, the evidence of this run, and who may decide.ClarificationAsking a person for a missing fact instead of guessing it.Closed objectAn object that rejects any key its schema does not name: additionalProperties false in JSON Schema.CoercionThe reader turns a value of the wrong type into the expected type instead of rejecting it, for example the string "0.62" into the number 0.62.Constrained decodingA generation technique: before each token is picked, the tokens that would break a grammar compiled from the schema are removed from the choice.ConsumerThe program or person that reads a payload and does something with it, relying on the contract.Contract testA test that checks one side of a boundary against the shared contract, not against the other side's code.ContractThe agreement between the side that writes data and the side that reads it: the shape, and the rules beyond the shape.Cross-field checkA check that two or more fields of one record agree with each other.Dead letterAn output or message that could not be processed, kept with its reason so a person can look at it and it can be replayed.Deterministic repairA fix by code that cannot change what the output means, such as removing a code fence around correct JSON.DiscriminatorOne field in every branch of a union whose fixed value names the branch, so a reader knows which shape to check.Domain ruleA check that the output is true against the business rules, the facts and the evidence of this run.EnumA fixed list of allowed values. A value outside the list fails, however close its spelling is.EnvelopeA small fixed wrapper around a payload that says what it is, where it belongs and what it rests on.Evidence idA short identifier of one piece of evidence the run gathered, such as the broker's email or the roof assessment.FallbackThe end of a bounded repair loop: stop asking, store a record with no recommendation and the errors, and let a person decide.Field catalogThe list of the 63 fields of a submission: group, type, unit, required, nullable, source, description, example.Field descriptionThe sentence in a schema that says, in words, what a field means and what to write in it.FieldOne value under a name that says what it is, and often in which unit.Final responseThe output a run produces for whoever is outside it: here, the recommendation the underwriter sees.Forward compatibleA consumer built for the old version can read data written under the new one.Free textText written for a reader, where the facts sit among the words and a program has to search and guess to find them.FuzzingFeeding a program large numbers of deliberately broken inputs and checking that each is handled correctly.Golden exampleA fixed input with a fixed expected result, kept with the code and checked on every change.GrammarA set of rules that says, at every point of a text, which characters or tokens may come next.HandoffA payload one agent passes to another agent in the same workflow.Hibernate ValidatorThe library that runs Jakarta Validation constraints; its site calls it the reference implementation of the Bean Validation specification.human_decisionThe record of the underwriter's decision: decided_by (a role), decision, override and reason.JacksonA suite of data-processing tools for Java whose ObjectMapper reads JSON into Java objects and writes them back.Java recordA Java class declared with a header of components; the compiler provides the constructor, accessors, equals, hashCode and toString.JSON LinesA text format with one JSON value per line, UTF-8, lines ending in a newline; files use .jsonl.JSON mappingThe step that reads JSON text into an object of a class, matching keys to fields and converting values to field types.JSON modeA provider setting that makes the output parse as JSON, with no promise about its keys, types or values.JSON PointerA short string such as /citations/0 that names one value inside a JSON document. Defined by RFC 6901.JSON SchemaA standard, written in JSON itself, for describing which shape a JSON value must have. A validator checks a value against it and returns errors.JSONA text format for data, defined by RFC 8259, with six kinds of value: string, number, boolean, null, object and array.LocaleThe set of conventions for writing numbers, dates and units: '2,4' is two point four in many European locales.MigrationRewriting stored records from the old shape to the new one.Negative exampleA golden example that must fail, and says at which stage.Nested typeA field whose value is itself an object or an array with its own schema.NullableA field whose value may be null. Different from optional (the key may be absent) and independent of required (the key must be present).OpenAPIA standard description of HTTP APIs; in version 3.1 its Schema Object is a superset of JSON Schema 2020-12.Optional fieldA field whose key may be left out of the object.Output encodingTurning a value into a form that a particular sink reads as data, not as instructions, at the moment it is written there.OverrideA decision by the underwriter that differs from the agent's recommendation.ParseRead a text and turn it into a value a program can work with, or stop with an error if the text is not well formed.Partial objectThe prefix of a JSON object that has not finished arriving.Policy fixtureThe small, invented set of underwriting rules the example runs on: UW-GUIDE, version 2026.2. Illustrative, not insurance practice.policy_versionThe version of the policy fixture the rules were read from in this run.PolymorphismOne field that can hold values of several different shapes.ProducerThe program, model or person that writes a payload for others to read.Prompt injectionText placed where a model will read it, written so that the model treats it as an instruction.Property-based testA test that states a property for all inputs of some kind, generates many inputs and checks the property on each.ProvenanceThe record of where a value came from: the source, the evidence id and the exact words it was read from.PydanticA Python library: a model is a class inheriting from BaseModel, and reading data into it converts and checks the fields in one call.Re-askSending the validation errors back to the model and asking for a corrected output. It raises attempt_number.RecommendationThe object the underwriting agent writes: one of four words, with reasons, cited rule ids, missing fields, a stated confidence and the policy version.RecordA group of named fields that describe one thing and are read together; in JSON, an object.RefusalA response in which the model declines the task, so the expected object is missing or replaced by a message.RepairAny action that turns a failed output into an accepted output or into a controlled hand-over to a person.Replay artifactEverything needed to validate an output again later and get the same result: raw text, exact schema, facts, evidence, versions.Required fieldA field whose key must be present in the object. Whether its value may be null is a separate decision.Round tripWriting a value out and reading it back, then checking that nothing changed.run_idThe identifier of one execution of the workflow for one submission.SanitizationRemoving or rewriting dangerous parts of a value. Useful in narrow cases; not the main defence for model output.Schema driftThe data a producer really sends moves away from the contract, or from what it used to send, while the contract stays the same.Schema versionA number or name that says which version of the contract a payload follows, so a reader can pick the right schema.SchemaA machine-readable description of which fields a record has, which type each holds, and which values are allowed. Checking against it is layer 2.SDK typeA helper in a model provider's client library that turns a typed model into the provider's schema and parses the response back into a typed object.SemanticsLayer 3: the fields of a record agree with each other, and each value means what the contract says (units, null versus zero).SerializationTurning a value held in a program into text (or bytes) so it can travel or be stored; parsing turns it back.SinkA place where a string is not only stored but interpreted: a web page, a SQL statement, a shell, the next prompt.StreamingThe provider sends the output piece by piece while the model writes it, instead of all at once.Strict modeA reader setting that refuses a value of the wrong type instead of converting it; on this site strict also means unknown fields are rejected.Structured output modeA model provider's feature that takes a JSON Schema with the request and restricts generation so the output follows it.Structured outputOutput written as data with an agreed shape (named fields, known kinds of value) instead of free sentences.SubmissionThe record the intake agent writes from a broker's email: 63 fields, of which the examples carry about ten.SyntaxThe rules a text must follow to be JSON at all: brackets, quotes, commas, the allowed number forms. Layer 1 of four.Tolerant readerA consumer that ignores fields it does not know and needs only the fields it uses.Tool argumentsThe JSON a model writes to fill a tool's input schema when it asks for a tool to run.Tool inputThe arguments a model writes when it asks for a tool to be called.Tool resultWhat a tool returns. Code produced it, often code and data you do not control.trace_idA 32-hex-character identifier of one trace. On this site: one trace per run, each attempt a span.TruncationThe output stopped because a token limit was reached, so the text is the beginning of an object and not a whole one.TypeThe kind of value a field may hold: a number, a piece of text, true or false, a list, or a group of fields.Typed eventA record that something happened, with a declared type and a schema for its data.Typed modelA class whose fields have declared types, built from data, so the rest of the code works with typed values instead of raw JSON.Underwriter cockpitThe web app where a human underwriter sees the submission, the evidence and the recommendation record, and decides.UnderwriterThe person at the insurer who decides whether to accept a risk. In the example, the only one who decides.Underwriting agentThe agent in the example that reads a submission, gathers evidence with tools and writes a recommendation for an underwriter.UnionA value that may take one of several shapes, for example an integer or null, or a found roof assessment or a not-found one.UnitThe scale a number is measured in: square feet or square metres, years or months, dollars or thousands of dollars.Untrusted valueAny value someone outside your control could have written, directly or through the model.UpcastConverting an old-version message into the new shape when it is read, saying what is unknown.Validation errorA small record of one problem: stage, path, code and message.Validation failure rateThe share of outputs that fail validation over a period, best cut by stage, field, code and version.Validation stageOne step of validation with its own input, question and errors. This site has four: parse, schema, cross_field, domain.ValidationChecking a value against a schema or a rule and getting back a list of errors. An empty list means no problem was found by that check.Well-formedA text that follows the rules of JSON syntax and so can be parsed.ZodA TypeScript library whose schemas give both a runtime check and a static type. Its documentation describes "TypeScript-first schema validation with static type inference".

Each term is explained in full on one page and used everywhere else. Which page owns which term, and where the words come from, is on About.