skip to content

In a partner-facing JSON API, what follows from JSON Schema being an optional add-on rather than something the encoding requires?

level: seniorimportance: should knowfreq 48%

answer

  1. the contract lives outside the bytes
  2. the parser never consults it
  3. validation is a step someone runs
  4. valid is a property of a boundary
  5. drift is the default without enforcement

basics

~20 s

The contract lives outside the bytes. Nothing on the decode path consults it, so a document that violates the schema still parses; validation becomes a step each boundary chooses to run, and schema and payload can drift apart unopposed.

solid answer

~50 s

`JSON Schema` and `XSD` are **separate documents in their own languages**, published, versioned and deployed apart from the payload they describe. Three consequences follow. First, **nothing enforces them by default**: a document that contradicts the schema decodes perfectly, because the parser never looks at one. Second, **validation becomes a policy decision at each boundary** — your gateway may validate while a downstream consumer does not, so two parts of the same system disagree about what is legal. Third, **drift is silent**: a producer that adds or renames a field breaks no parser, so the divergence is discovered by a reader, not by a build. The flip side is why the design persists: optionality is what lets a partner integrate on day one with no artifact and adopt the schema later, which is precisely the property that made the family win.

code

json · 10 lines
json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "amountMinor"],
  "properties": {
    "id": { "type": "string" },
    "amountMinor": { "type": "integer" },
    "currency": { "type": "string", "minLength": 3, "maxLength": 3 }
  }
}

go deeper

for a junior

Recall that the schema is a separate published document and that the parser never looks at it. A payload that breaks the contract still decodes successfully.

for a middle

Explain the mechanism: decoding turns characters into values and consults nothing external, so enforcement requires a validator that some component deliberately runs.

for a senior

Bring the operational consequences: validity is a property of the boundary that checked, drift fails no build, and a published-but-stale schema misleads partners. Name the countermeasures you would actually deploy.

for a principal

Own the trade deliberately. Decide where validation is mandatory, what strictness each consumer applies, how the schema is versioned against the emitting service, and accept that you are buying frictionless integration with enforcement you must build yourself.

## Where the contract actually lives In this family, the schema is **not part of the encoding**. `JSON Schema` is itself a `JSON` document, in a vocabulary of its own, that describes what other documents must look like. `XSD` is an `XML` document that does the same for markup. Both are artifacts you publish, version and serve separately from the payload. That is a design decision with teeth, and its whole content is one sentence: **the decode path does not consult the schema**. A parser turns characters into values. It has no idea a contract exists. ## The three consequences 1. **A violating document parses fine.** Send a payload with a field missing, an extra field present, or a number where a string was promised, and every parser on the receiving side accepts it. The failure surfaces later, deeper in the code, usually as something unrelated-looking. 2. **Validation is a per-boundary choice.** Somebody has to *run* a validator. Whether that happens at the edge, in a consumer, in a test, or nowhere is a deployment decision, and different parts of one system commonly make it differently. The practical result is that "valid" is not a global property of a document; it is a property of the boundary that checked it. 3. **Drift is silent and cumulative.** Nothing stops the payload and the schema diverging, because divergence breaks no build. The schema becomes documentation that was true once, which is more dangerous than no schema at all — a partner reads it and believes it. ## Why the design is not a mistake It is tempting to file all this as a weakness. The counterargument is strong and an interviewer wants to hear it: - A partner can integrate **before** any contract artifact exists, and adopt the schema afterwards without redoing anything. - The same payload can be described by **different schemas for different purposes** — a strict one for the gateway, a lenient one for an archive reader — because no single schema is privileged by the format. - A schema can be introduced to an already-running integration without a flag day, since adding one changes nothing about how the bytes decode. Contrast this with encodings where a schema is required simply to read the bytes: there, drift is impossible because there is nothing to read without the contract, and that rigidity is paid for at integration time. ## What a team does about it | Practice | What it fixes | | --- | --- | | Validate at the trust boundary, on every request | Turns "valid" from an assumption into a checked fact at one known place | | Generate the published documentation from the schema | Stops the human-readable contract and the machine-readable one drifting apart | | Run the schema against recorded real traffic in tests | Catches drift in the direction that actually happens — the producer moved | | Version the schema alongside the service that emits it | Makes "which contract did this document promise to satisfy" answerable | Note the second row. The most common real failure is not that a schema is missing; it is that a schema exists, is published to partners, and stopped matching production six months ago. ## A detail worth knowing The markup side has a longer-established validation ecosystem, with more than one schema language available and document-level hints that point a validator at a contract. Even there, though, the same rule holds: the hint is an instruction to a validator someone chose to run, not something that decoding enforces. The lesson generalises across the whole family — **in these encodings, a contract is only as real as the step that checks it**. ## The sentence to land in an interview "The schema is a document about documents. It is published beside the payload, not inside it, so it constrains nothing until some component runs a validator — which makes contract enforcement an operational decision rather than a property of the format, and makes drift the default outcome unless something in the pipeline actively opposes it."

  • A partner reports that your published schema no longer matches what your API returns. How did that become possible?
    Because the schema is an external artifact that nothing on the emit path consults. A producer change that adds, renames or retypes a field breaks no parser and fails no build, so the divergence is invisible until a human compares them. The usual countermeasure is to validate recorded production traffic against the published schema in continuous integration, so drift fails a build instead of a partner.
  • Two services in one system disagree about whether the same document is valid. How is that possible when they share a schema?
    Validity is not carried by the document; it is produced by whichever component ran a validator. If the edge validates and a downstream consumer does not, or they pin different schema versions, the same bytes are legal in one place and rejected in another. Making validity meaningful requires naming one boundary that checks and a single versioned artifact it checks against.
  • What does the optionality of the schema buy, given all these costs?
    Integration without an artifact. A partner can send a first request the same afternoon, adopt the schema later, and never coordinate a generator version. It also lets different consumers apply different strictness to identical payloads, because no schema is privileged by the encoding.

saying these in an interview costs you the question

  • Thinks the parser rejects documents that violate the schema
  • Says publishing a schema is the same as enforcing one
  • Believes validity is a property of the document itself
  • Treats the optional schema as purely a weakness
  • Assumes every consumer validates because the gateway does