project_json_schema_plus_jsonld

Approved Monday 20 April 2026 by Rich: “i agree with the JSON Schema + JSON-LD combined approach. please save this.”

Context: Rich asked for a head-to-head schema/format scorecard. After v1.0 (JSON Schema 47) the bias criteria were removed (see memory feedback_inherit_v2_evaluation_criteria.md); v1.1 rescored with formal-semantics + multilingual criteria added. Result: JSON Schema 43, JSON-LD 40, gap tightened to +3. The conclusion: JSON Schema as primary + JSON-LD as Day-1 additive layer is the architecture.

The combined approach

JSON Schema (primary structural format, Apache 2.0):

• Pydantic v2 as the generative source
• Type validation + structural constraints
• OpenAPI 3.1 type system compatibility
• Best-in-class AI-vendor consumption (OpenAI / Anthropic / Google tool_use natively consume JSON Schema)

JSON-LD (additive semantic layer, Apache 2.0):

• IRI-identified concepts (semantic interop)
• @language tags + @direction for bidi (multilingual)
• Cross-jurisdiction modelling via IRI namespaces
• Graceful degradation — any consumer that ignores @context sees valid JSON

Why combined, not either/or

• JSON-LD does not replace JSON Schema’s structural-validation role — use JSON Schema for type safety + constraint validation.
• JSON Schema does not replace JSON-LD’s semantic role — use JSON-LD for multilingual + cross-jurisdiction + formal-semantics precision.
• Combined, they cover what plain JSON Schema scored 3/5 on (formal-semantics + multilingual) without paying RDF/OWL’s practical consumption costs (RDF/OWL scores 5/5 on fundamentals but 2/5 on codegen + AI-vendor consumption).

Lineage

• Prior research: docs/superpowers/specs/foundation-arch-research/12-json-ld.md (recommend ADOPT v4.0.0 — 12b JSON-LD only, additive)
• Scorecard: docs/superpowers/specs/2026-04-20-schema-format-scorecard.md v1.2 (status approved); §6 v1.0→v1.1 rescoring delta table
• Option G: docs/superpowers/specs/2026-04-18-inherit-v2-architecture-options/option-G.md v1.6 §3 adds JSON-LD row as Apache 2.0 Day-1 additive layer
• Head-to-head: docs/superpowers/specs/2026-04-20-inherit-v6-vs-v2-head-to-head.md v1.0 §3.1 shows JSON-LD as a present-in-v2, absent-in-v6.6 capability

How to apply

• For any new INHERIT v2 schema work, generate both JSON Schema AND a JSON-LD context file from the Pydantic v2 source.
• For multilingual or multi-jurisdictional content, use JSON-LD’s @language + @direction + IRI namespacing. Do NOT invent new JSON Schema conventions to cover these.
• For AI-vendor tool_use (OpenAI / Anthropic / Google), expose JSON Schema (not JSON-LD) because AI vendors consume JSON Schema natively.
• For semantic-web + governance-body audiences (OIDF / W3C / OASIS / ISO), expose JSON-LD + RDF serialisations as needed — JSON-LD is the bridge.
• Do NOT treat JSON-LD as an alternative to JSON Schema — they cover different roles. Both land in openinherit/code-standard/ under Apache 2.0.

What was rejected

• RDF/OWL/SHACL as primary format — rejected (scored 38/50 in v1.1; practical consumption costs on codegen + AI-vendor are the blocker). Retained as optional serialisation target via JSON-LD for semantic-web consumers.
• XSD — rejected (32/50; declining industry trend).
• Akoma Ntoso as primary — rejected (33/50; category mismatch for estate data). Adopted as statute-citation URI field per 11-akoma-ntoso.md.
• Protobuf / Avro — rejected (27/50; wrong problem domain).

Open follow-ups

• Akoma Ntoso citation URI field adoption — format scorecard §9 still open.
• FHIR resource-modelling discipline (CapabilityStatement + profile pattern) — format scorecard §9 still open.

Both are small-scope additive decisions in the same spirit as JSON-LD; easy approvals when Rich is ready.