JSON Schema 2020-12 for Contracts and Content

_Locale: en-US · Lesson: DAT-012 · Public order: 69_

Outcome and working artifact

This lesson produces a JSON Schema Contract Verification Record v1: a decision artifact that separates observations, assumptions, limits, and required evidence. The goal is a transferable model, not memorized tool names.

می‌تواند «JSON Schema 2020-12 برای Contracts و Content» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.

Boundary model

JSON Schema 2020-12 can express a machine-checkable structural contract, but validation is bounded by a declared dialect, selected vocabularies, implementation configuration, and the assertions actually written. A valid instance is not proof of every business invariant. A useful contract therefore includes positive fixtures, deliberate invalid fixtures, and a compatibility decision for each schema change.

Keep three labels throughout the work: observed, bounded inference, and needs verification. When evidence is unavailable, record unknown. A product name or a passing happy path is not a substitute for evidence.

1. Declare the dialect

Use $schema to identify the intended meta-schema. Without an explicit dialect, two tools can interpret keywords or supported vocabularies differently.

2. Separate assertions and annotations

Keywords such as type, required, and numeric bounds constrain validity. Descriptive metadata such as title, description, and many uses of format do not automatically add the domain enforcement people may assume.

3. Model objects and arrays intentionally

For objects, decide required properties and extension policy. For arrays, distinguish tuple-like prefixItems from a repeated items schema and state uniqueness or size constraints only when the domain needs them.

4. Test rejected data

A schema that only sees valid fixtures has not demonstrated its boundary. Missing fields, wrong types, unknown fields, boundary numbers, and ambiguous unions should be deliberate probes.

5. Compatibility has a direction

Tightening a consumer schema can reject old data; loosening a producer can emit data old consumers reject. Classify changes against producer/consumer direction and retained data, not with one 'breaking' label.

Five-step method

1. Write the instance boundary and the invariants that are truly structural.
2. Pin draft 2020-12 and encode the smallest assertion set that represents those invariants.
3. Create positive fixtures plus one negative fixture for every decisive boundary.
4. Run the same suite under the selected validator configuration and record how format and referenced schemas are handled.
5. For each proposed schema diff, classify producer and consumer impact and keep application-only invariants outside the schema record.

Worked case

A content card requires id, kind, and title; kind selects one of two payload shapes. The contract declares draft 2020-12, uses a discriminator-like oneOf with mutually exclusive required fields, and leaves a named extensions object open while closing unknown top-level properties. Tests include a valid article, a valid video, a missing title, an ambiguous payload, and an unknown top-level key. Adding an optional extension is evaluated separately from making an existing optional field required.

Decision and evidence matrix

Failure probes and repair

• JSON Schema validation proves all business invariants or cross-record consistency.
• The format keyword is always an assertion in every 2020-12 implementation configuration.
• A schema version identifier is automatically the same thing as an application data-version policy.
• Closing unknown properties is universally correct for every extensible contract.

For each statement, narrow the claim, create a counterexample, and name the observation that could confirm or reject it.

Transfer challenge

Change the scenario so that one assumption in the worked case no longer holds. Rebuild the JSON Schema Contract Verification Record v1 without copying the earlier decision, then explain what changed in the input and what stayed stable in the decision rule.

What this does not prove

This lesson does not claim certification, production guarantees, or coverage of every implementation. Its conclusion is valid only within the scenario boundary, dated sources, and recorded observations.

Self-check

• [ ] Did I separate responsibilities from framework or tool names?
• [ ] Did I state at least one failure probe and its predicted observable?
• [ ] Are fact, inference, and design choice visibly separated?
• [ ] Did I record non-claims and missing evidence?
• [ ] Did I complete transfer in a changed context without a prepared answer?

Sources and freshness boundary

Sources were reviewed for the frozen Bible as of 2026-09-19. A review_due date triggers a versioned requalification; it does not authorize silent in-place edits.

• JSONSCHEMA-SPEC — Official specification index; current published JSON Schema version and document set. (https://json-schema.org/specification; review: 2026-12-31)
• JSONSCHEMA-2020-12 — Draft 2020-12 overview, meta-schema and release semantics. (https://json-schema.org/draft/2020-12; review: 2026-12-31)
• JSONSCHEMA-CORE — Core dialect, vocabulary, reference and schema-resource semantics. (https://json-schema.org/draft/2020-12/json-schema-core; review: 2026-12-31)
• JSONSCHEMA-VALIDATION — Validation and format vocabulary semantics. (https://json-schema.org/draft/2020-12/json-schema-validation; review: 2026-12-31)