Background & Motivation

Background & Motivation#

[!CAUTION] EARLY DEVELOPMENT STAGE: This meta-schema and its vocabularies are currently in early development for prototyping and testing only. Focus is on implementing core vocabularies and ensuring architectural consistency. Avoid production-ready assumptions.

The Challenge#

JSON Schema is the industry-standard language for describing and validating JSON data structures. It is widely adopted across the information technology ecosystem, powering everything from web APIs (OpenAPI) to data integration tools and modern AI agents.

However, standard JSON Schema was primarily designed for technical validation (e.g., “is this a string?”, “is this integer between 1 and 100?”). It lacks the semantic depth necessary for the effective discovery, exchange, and stewardship of high-value data. In the world of FAIR Data (Findable, Accessible, Interoperable, and Reusable), we need to capture much more:

  • Semantic concepts (what does this variable mean?)

  • Controlled vocabularies and classifications.

  • Units of measure and quantity kinds.

  • Temporal and spatial coverage.

  • Data provenance, lineage, and licensing.

An Enrichment of Common IT Practice, Not a New Dataset Model#

Traditional metadata standards (such as DDI, DCAT, SKOS, and Croissant) provide rich domain metadata, but they often impose a steep learning curve and rely on niche Semantic Web technologies (RDF, SPARQL, OWL, triplestores, complex XML schemas). This creates a barrier for software engineers, data architects, and IT professionals who build modern web applications and data pipelines.

FAIR Data JSON Schema is explicitly NOT a new metadata model created to replace existing dataset specifications. Rather, it is an enrichment of the established, ubiquitous IT practice of describing datasets and data payloads as JSON Schemas. Software engineers and data engineers already write JSON Schemas every day to define API payloads, database tables, and validation contracts. FAIR Data JSON Schema simply enriches these standard technical schemas with semantic fair: metadata annotations:

  1. 100% Compatible with the JSON Schema Ecosystem: Because FAIR keywords are defined as standard annotations in JSON Schema Draft 2020-12, any standard JSON Schema validator across any programming language (Python, JS, Go, Rust, Java, C#, PHP) handles FAIR schemas out of the box. Standard tools perform normal data validation and treat fair: keywords as rich metadata annotations, integrating natively with OpenAPI/Swagger, VS Code intellisense, form generators, and data pipelines with zero lock-in.

  2. Zero New Language to Learn: Produce FAIR-compliant dataset documentation using standard JSON Schema—the format and tooling developers already use every day.

  3. No Semantic Web Overhead: Achieve FAIR data compliance and interoperability without having to learn RDF triples, SPARQL endpoints, or complex ontology frameworks.

  4. Instant AI Readiness & MCP Integration: Because JSON Schema is the native tongue of LLMs, function-calling, and the Model Context Protocol (MCP), FAIR-enriched dataset schemas can be directly ingested and acted upon by AI agents out of the box.

The 2-Tier Usability Model#

To make adoption as effortless as possible, the vocabulary is structured into two clear tiers:

🟢 Tier 1: Essential Properties (Get Started in Minutes)#

Simple, intuitive keywords designed for 90% of everyday use cases with minimal effort:

  • Dataset title, description, license (fair:license / Ref), and contributors (fair:contributors).

  • Row entity definition via fair:unitType (e.g. "Person", "Household").

  • Units of measure (fair:measurementUnit / Ref), classifications (fair:classification / Ref), and concepts (fair:conceptRef).

🔵 Tier 2: Advanced & Extended Properties (Optional Deep-Dive)#

For users interested in digging deeper into formal data stewardship, these properties are 100% optional and ready when needed:

  • Formal variable cascades (fair:conceptualVariableRef, fair:representedVariableRef, fair:instanceVariableRef).

  • Population and universe bounds (fair:universe / Ref, fair:population / Ref).

  • Physical quantity kinds and measurement scale types.

  • Cross-dataset join relationships and lineage (fair:datasetRelations).

What is a JSON Meta-Schema?#

A JSON Schema defines the structure and validation rules for a JSON document (an “instance”). A JSON Meta-Schema is a schema that defines the structure and validation rules for other schemas. Essentially, it is a “schema for schemas.”

In this project, the meta-schema defines the FAIR Dialect of JSON Schema. It:

  • Declares Standards: Specifies which version of the JSON Schema standard is being used (Draft 2020-12).

  • Defines Keywords: Introduces custom FAIR keywords (e.g., fair:concept, fair:measurementUnit) and specifies where they can be used and what values they should hold.

  • Enables Interoperability: Bundles specialized vocabularies into a single cohesive dialect, allowing FAIR-aware tools, APIs, and AI agents to recognize and act upon the metadata.