A team building the underwriting workflow asks a fair question at this point: "We are not going to ship minischema.py. What do we use instead, and what will it do for us?" The honest answer has three parts, and confusing them is the most common mistake on this subject. A standard says what valid means (JSON, JSON Schema). A library checks values in your code against a standard or against its own model (Pydantic, Zod, Ajv). A product is a feature of a model provider that shapes what the model writes in the first place. A product does not replace a library, a library does not replace the domain stage, and no standard knows your policy fixture.
This page profiles each one with the same template, from its own documentation read on 2026-11-17. "Documented shape; not run here" marks code that was not run for this site. The Pydantic and Java behaviour that was run comes from the recorded run in examples/uw-contracts/twins/ (Pydantic 2.14.3; Jackson 2.23.0; Hibernate Validator 9.1.6.Final). No profile says "best"; none quotes a price.
Which stage each one covers#
Before the profiles, the summary they lead to. "yes" means the tool does this for you; "partly" means it does part of it or only when configured; "no" means it is your code.
| Tool | Kind | Language | Parse | Schema | Cross-field | Domain | Emits JSON Schema |
|---|---|---|---|---|---|---|---|
| JSON (RFC 8259) | standard | any | partly | no | no | no | no |
| JSON Schema 2020-12 | standard | any | no | yes | partly | no | yes |
| Jakarta Validation 3.1 | standard | Java | no | yes | partly | no | no |
| OpenAPI 3.1 | standard | any | no | yes | partly | no | yes |
| Pydantic | library | Python | yes | yes | partly | no | yes |
| Zod | library | TypeScript | no | yes | partly | no | yes |
| Jackson | library | Java | yes | partly | no | no | no |
| Hibernate Validator | library | Java | no | yes | partly | no | no |
| Ajv | library | JavaScript | no | yes | partly | no | no |
| jsonschema (Python) | library | Python | no | yes | partly | no | no |
| Provider output modes | product | any | partly | partly | no | no | no |
Read the Domain column first. Every row says no. Whatever you choose, the check that the output is true for this run (the rule applies, the policy version is the one read, the evidence was gathered) is code you write, as on the validation page. "Partly" under Cross-field means the tool offers a hook (a validator method, a refinement, conditional keywords) where you write the rule yourself.
Standards#
JSON (RFC 8259)#
What it is. The text format: six kinds of value, a grammar, and a few rules about interchange. The problem it solves. Any program in any language can read what another wrote. Model. Objects, arrays, strings, numbers, true, false, null. RFC 8259 says "The names within an object SHOULD be unique" (a SHOULD, not a MUST, which is why parsers differ on duplicate keys), that "A fraction part is a decimal point followed by one or more digits", and that JSON exchanged between systems that are not part of a closed ecosystem "MUST be encoded using UTF-8". Minimum example. {"recommendation": "escalate"}. Strengths. Universal. Limits. No dates, no comments, no schema, and the duplicate-key and number-precision questions are left to parsers. When plain code is better. Never: everything on this site sits on top of it. Integration and security. Choose a parser whose duplicate-key and NaN behaviour you know; the four layers page shows a strict and a lenient parser disagreeing. Read. rfc-editor.org/rfc/rfc8259, 2026-11-17.
JSON Schema (draft 2020-12)#
What it is. A vocabulary for describing the shape of JSON values, with a validation specification and an output format. Problem. One machine-readable contract that many languages and tools can check. Model. Keywords such as type, required, enum, properties, additionalProperties, oneOf, $ref; title and description are annotations, which the validation specification says "decorate a user interface with information about the data". The core specification defines four output formats (flag, basic, detailed, verbose) whose results carry JSON Pointers to the instance location. Minimum example. The site's recommendation.v1.json, run by the example's validator on every page. Strengths. Language-neutral, widely implemented, and the format most provider structured-output features accept. Limits. It describes shape; conditional keywords can express some cross-field rules awkwardly, and nothing in it can see your policy fixture. When plain code is better. Cross-field and domain rules: write them as code with stable error codes. Integration. Keep schemas in the repository with the code, versioned (see evolution). Read. json-schema.org/draft/2020-12, 2026-11-17.
Jakarta Validation 3.1 (Bean Validation)#
What it is. The Java standard for declaring constraints on objects with annotations. Problem. One way to state constraints on Java types, checked by any compliant provider. Model. Annotations on fields and record components: @NotNull ("must not be null"), @NotEmpty, @Pattern, @DecimalMin, @AssertTrue; container elements can be constrained, as in List<@Positive Integer>. Several constraints treat null as valid: for @AssertTrue and @Pattern the specification says "null elements are considered valid", so @NotNull must be added separately. It also says @DecimalMin and @DecimalMax do not support double and float "due to rounding errors". Minimum example (the record that was run in twins).
// documented shape; this record WAS run in examples/uw-contracts/twins (see that README)
public record Recommendation(
@NotNull Decision recommendation,
@NotEmpty List<@NotBlank String> reasons,
@NotNull List<@Pattern(regexp = "^R-[A-Z]+-[0-9]{2}$") String> citations,
@NotNull List<String> missing,
@DecimalMin("0.0") @DecimalMax("1.0") double statedConfidence,
@NotNull @AssertTrue Boolean requiresHuman,
@NotNull String policyVersion) {}
Strengths. Declarative, standard, integrated into Java frameworks. Limits. It checks an object that already exists: it cannot see an absent key, a duplicate key or a conversion the JSON mapper made before it. When plain code is better. Cross-field and domain rules beyond a class-level constraint. Read. jakarta.ee/specifications/bean-validation/3.1, 2026-11-17.
OpenAPI 3.1#
What it is. A description format for HTTP APIs. Version 3.1.0 (February 2021) "defines a standard, programming language-agnostic interface description for HTTP APIs". Problem. One document that describes requests and responses for clients, servers, documentation and tests. Model. Its Schema Object "is a superset of JSON Schema Specification Draft 2020-12", plus a Discriminator Object that "can be used to aid in serialization, deserialization, and validation" when payloads "may be one of a number of different schemas", naming the property that holds the type (propertyName). Minimum example. A POST /recommendations operation whose request body references recommendation.v1.json (documented shape; not run here). Strengths. Ties schemas to endpoints, with tooling that generates clients and server stubs. Limits. Describes HTTP; a model's output inside a workflow has no endpoint. When plain code is better. For contracts that never cross an HTTP API, a plain JSON Schema file is enough. Read. spec.openapis.org/oas/v3.1.0, 2026-11-17.
Libraries#
Pydantic (Python)#
What it is. A Python library that validates data into typed models defined with type hints. Problem. Turning untrusted dictionaries and JSON into Python objects you can rely on. Model. A class with typed fields; model_validate_json parses and validates in one call; ConfigDict(strict=True) turns off conversions; extra="forbid" rejects unknown keys (the default, per its configuration page, is 'ignore'). Its documentation says it allows "automatic creation and customization of JSON schemas from models" (model_json_schema), compliant with "JSON Schema Draft 2020-12" and "OpenAPI Specification v3.1.0". Minimum example. python/models.py in twins/, run with Pydantic 2.14.3. What the run showed. Default mode turned "0.62" into 0.62 and "yes" into true, and dropped an unknown premium_usd; strict mode with extra="forbid" rejected all three. A duplicate key passed in both modes, keeping the last value. Strengths. Parse, conversion and constraints in one call, with one error list. Limits. Defaults are lax; duplicate keys are not caught. When plain code is better. Domain rules. Read. pydantic.dev/docs, 2026-11-17. The typed models page has the full comparison.
Zod (TypeScript)#
What it is. Its documentation calls it "TypeScript-first schema validation with static type inference": a schema written in TypeScript gives both a runtime check and a static type. The documentation read is for Zod 4 and lists "Built-in JSON Schema conversion" among its features. Problem. One definition for the type the compiler checks and the value the program receives. Minimum example (documented shape; not run here).
// documented shape; not run here
import { z } from "zod";
const Recommendation = z.object({
recommendation: z.enum(["approve", "decline", "request_info", "escalate"]),
reasons: z.array(z.string().min(1).max(400)).min(1),
citations: z.array(z.string().regex(/^R-[A-Z]+-[0-9]{2}$/)),
missing: z.array(z.string()),
stated_confidence: z.number().min(0).max(1),
requires_human: z.literal(true),
policy_version: z.string(),
}).strict();
Strengths. Types and checks never drift apart in a TypeScript codebase. Limits. Lives in one language; whether an object rejects unknown keys depends on how it is declared (read the current documentation). When plain code is better. Domain rules, as everywhere. Read. zod.dev, 2026-11-17.
Jackson (Java)#
What it is. Its README says "Jackson is a suite of data-processing tools for Java (and the JVM platform)", with a streaming parser and data binding. It has two lines: 2.x under com.fasterxml.jackson and 3.x under tools.jackson, with different packages, so one is not a drop-in replacement for the other. Problem. Reading JSON into Java objects and writing them back. What the run showed (2.23.0). The default ObjectMapper converted "0.62" to a double and 7 to the string "7", turned null into 0.0 for a primitive double, and rejected an unknown field. Nine settings in a strict mapper (listed in the twins README) rejected all of these. The 3.0 release notes say several of these defaults change in 3.x; 3.x was not run here. Strengths. Fast, configurable, ubiquitous in Java. Limits. It is a mapper first: constraints come from Bean Validation, after mapping. When plain code is better. Never for parsing; always for domain rules. Read. github.com/FasterXML/jackson, 2026-11-17, and the feature pages cited in the twins README.
Hibernate Validator (Java)#
What it is. Its site calls it "the reference implementation for the Bean Validation specification", that is, the implementation of the Jakarta Validation standard profiled above; the site lists 9.1 as the latest stable line. Problem. Running the annotations. What the run showed (9.1.6.Final). It enforced @DecimalMax("1.0") on a double (the standard says providers need not support double) and reported constraint violations by record component name. Limits. Runs only on an object Jackson already built, so a type error and a range error are never reported together. Read. hibernate.org/validator, 2026-11-17.
Ajv (JavaScript)#
What it is. A JSON Schema validator for JavaScript. Its site says it lets you implement "complex data validation logic via declarative schemas for your JSON data, without writing code", supports JSON Schema drafts 04, 06, 07, 2019-09 and 2020-12 and JSON Type Definition, and "Compiles your schemas to optimized JavaScript code". Problem. Checking JSON against a JSON Schema in Node or the browser. Minimum example. Compile recommendation.v1.json, call the compiled function on a parsed value, read its errors (documented shape; not run here). Strengths. Follows the standard; the same schema file as every other language. Limits. Shape only. When plain code is better. When the contract is defined in TypeScript and never shared, a TypeScript-first library may fit better. Read. ajv.js.org, 2026-11-17.
jsonschema (Python)#
What it is. "an implementation of the JSON Schema specification for Python", with "Full support for Draft 2020-12, Draft 2019-09, Draft 7, Draft 6, Draft 4 and Draft 3", and "Lazy validation that can iteratively report all validation errors". Problem. Validating against the shared JSON Schema file from Python, without a model class. Minimum example. A validator for the draft, then its error iterator over a parsed value (documented shape; not run here). This site's minischema.py is a small teaching version of the same idea; use the library in production. Strengths. The standard, exactly; all errors at once. Limits. Gives you a validated dictionary, not a typed object. Read. python-jsonschema.readthedocs.io, 2026-11-17.
Products: provider output modes and SDK types#
What they are. Features of model providers' APIs that make the model's output follow a format: JSON mode, schema-constrained output, strict tool arguments, and SDK helpers that turn a Pydantic or Zod model into the provider's schema and parse the response back into a typed object. Problem. Fewer outputs that fail at the parse and schema stages. Limits that every provider's documentation leaves in place, in some form: a cut-off output can still be incomplete, a refusal can still replace the object, a supported subset of JSON Schema applies, and a well-shaped value can still be false. Each provider's exact parameters, supported keywords and guarantees change often; the provider modes page records what each provider's documentation said on the day it was read, with links, and this site does not repeat those details here. When plain code is better. Never instead: a product shapes the output; your stages still check it.
Diagram: Standards, libraries, products · what each kind does, and what stays yours
Read left to right. A product shapes what the model writes. A standard defines valid. A library checks values in your code. The domain stage, true for this run, is always your own code.
- Product
- Provider output mode: JSON mode, schema-constrained output, strict tool arguments, SDK types.
- Standard
- JSON, JSON Schema, Jakarta Validation, OpenAPI: Says what a valid value is, independent of language.
- Library
- Pydantic, Zod, Jackson, Hibernate Validator, Ajv, jsonschema: Parses, converts (if allowed) and checks constraints.
- Yours
- Cross-field and domain checks: Rules about combinations, the policy fixture, the evidence of this run.
Choosing, in one table#
| If your situation is | Start from | And still write |
|---|---|---|
| Python workflow, model output into typed objects | Pydantic in strict mode with unknown keys forbidden | cross-field and domain checks as code |
| A shared contract read by several languages | one JSON Schema file, validated by Ajv, jsonschema or your language's validator | the same domain checks in each consumer, or in one service |
| A Java service consuming model output | a strict Jackson mapper plus Bean Validation, with @NotNull next to every constraint that treats null as valid | domain checks; a test that null is not silently 0.0 |
| A TypeScript service or UI | Zod, strict objects | domain checks |
| HTTP API around the workflow | OpenAPI 3.1 referencing the same JSON Schema files | nothing new: the schema is shared |
| Fewer parse and schema failures | a provider's schema-constrained mode, if your schema fits its subset | all four stages anyway |
Before AI. None of these tools is new to a backend engineer, and that is the point: the same libraries that validate an HTTP request body validate a model's output. What changes is the defaults you can tolerate. A lax default that converts"0.62"to0.62was a convenience for forms; for a model, it hides drift that the observability page wants to count.
What this is not. Tool schemas and how tools are exposed and executed (including MCP) are profiled on tools.sammuthu.com. Evaluation frameworks are profiled on eval.sammuthu.com.
For a coding agent. A coding agent's change_report is checked in CI by whatever the CI language offers: a JSON Schema file and a standard validator is the most portable choice, because the agent's harness and the CI may be written in different languages. See diff-to-deploy.sammuthu.com.
Diagram: One contract, several languages · the shared schema in the middle
Read left to right. One JSON Schema file per contract is the source. Each language validates against it with its own library, or generates its model from it. The domain checks are written once per consumer that needs them.
- Source
- JSON Schema file: The contract, in the repository, with its version.
- Each language
- Python: A strict model or a standard validator.
- TypeScript: A strict object or a compiled schema.
- Java: A strict mapper, then Bean Validation.
- Then
- Domain checks: The same rules, wherever a consumer acts on the value.
Checklist#
- Name the kind of each tool you adopt: standard, library or product; expect each to do only its kind of job.
- Keep one JSON Schema per contract as the shared source; generate or check language models against it.
- Turn on strict modes: no conversions, unknown keys rejected, duplicate keys caught where the parser allows it.
- In Java, put
@NotNullnext to every constraint that treats null as valid; avoid primitives for fields that may be null. - Write cross-field and domain checks as your own code, whatever the library.
- Record the version of every library and the date you read its documentation; rerun the comparison when versions change.
Schema first or model firstWhich is the source of truth
Two workable designs. Schema first: the JSON Schema file is the contract; language models are generated from it or tested against it. Model first: a Pydantic or Zod model is the contract and the JSON Schema is generated from it for other languages and for the provider. Model first is faster in a one-language team; schema first keeps several languages honest. Either way, commit the generated artifact and test that it matches its source, so a library upgrade that changes generation shows up in a diff.
Two libraries, one schema, different answersWhy the twins run exists
Two validators that both claim JSON Schema support can still disagree on details: formats, duplicate keys, number handling, unknown keywords. A mapper plus a validator (the Java path) behaves differently from a single parse-and-validate call (Pydantic). The only reliable way to know is to run the same payloads through both and compare, as examples/uw-contracts/twins/ does with 22 payloads. Run it again when you upgrade.
In one breath#
Standards say what valid means, libraries check values against them in your code, and provider products shape what the model writes; none of them knows your rules, so the domain stage is always your code. Pick one shared JSON Schema per contract, turn every library's strict settings on, add the Java @NotNull that the standard does not imply, and treat a provider's schema mode as a way to fail less often, not as a reason to check less. Read each tool's own documentation with a date, and rerun your comparison when versions move.
The last chapter takes the contracts into harder territory: partial objects in a stream, one field with several shapes, data in other languages, and events. That is advanced.