Keyword Reference & Scopes

This document provides the detailed specification for every keyword introduced by the FAIR Data JSON Schema Annotations Vocabulary (https://highvaluedata.net/fair-data-schema/vocab/annotations).

---

1. Universal Scope (Any Schema Object)

Keywords providing basic identification and semantic context. Can be applied at the dataset, table, or property level.

Keyword	Type	Description & Usage
fair:resourceType	string	The architectural role of the schema object. Standard values: data-product (multi-resource bundle), dataset (collection of variables), variable (individual field). Default at root: dataset.
fair:conceptRef	string (URI)	The URI or CURIE pointing to an authoritative semantic definition (e.g. Wikidata, AGROVOC, LOINC).
fair:concept	string	Human-readable literal name of the underlying concept.
fair:label	string or object	Short title or label. Supports multilingual i18n objects (e.g., {"en": "Salary", "fr": "Salaire"}).
fair:description	string or object	Detailed markdown-formatted description. Supports i18n.
fair:identifiers	array	List of secondary, historical, or domain-specific identifiers (identifier, identifierType, uniquenessScope, isResolvable, resolverUrl).

---

2. Dataset Scope (Container / Resource Level)

Keywords describing provenance, temporal/spatial bounds, licensing, and overall dataset structure.

Keyword	Type	Description & Usage
fair:version	string / object	Version descriptor resource (identifier, date, notes). Semantic Versioning (MAJOR.MINOR.PATCH, e.g., "1.0.0") following SemVer is strongly encouraged.
fair:contributors	array	List of contributor agents (aligned with W3C PROV-O). Each item contains name, contributorRef (URI), type (e.g., Person, Organization), role (e.g., Provider, Author, Curator), and optional startDate/endDate.
fair:license	string	Plain-text license identifier (e.g., "CC-BY-4.0").
fair:licenseRef	string (URI)	Direct URI to the license terms (e.g., "https://spdx.org/licenses/CC-BY-4.0.html").
fair:temporalCoverage	string / object	Plain text or ISO 8601 interval describing the time window (e.g., "2024-01-01/2024-12-31").
fair:spatialCoverageRef	string (URI)	URI reference to a geographical region or gazetteer entity (e.g., NUTS or Geonames URI).
fair:population	string	Target universe or population bounded by time and space (e.g., "Employed active labor force aged 15-64").
fair:structureType	string	Structural payload layout aligned with CDIF Data Structure profile: wide, long, dimensional, or key-value.
fair:quality	array	Measured data quality metrics aligned with W3C DQV (dqv:hasQualityMeasurement). Each item contains metric, metricRef, value, and description.
fair:datasetRelations	array	Inter-dataset relationships (e.g., isPartOf, hasPart, isVersionOf, isContinuedBy).

---

3. Property Scope (Variable / Column Level)

Keywords describing data representation, units, measurement scales, classification schemes, and missing value sentinels.

Keyword	Type	Description & Usage
fair:measurementUnit	string	Plain-text name of the physical unit of measurement (e.g., "Degree Celsius", "kilograms").
fair:measurementUnitRef	string (URI)	Authoritative unit URI (e.g. QUDT or Wikidata URI).
fair:measurementScaleRef	string (URI)	Statistical measurement scale type: nominal, ordinal, interval, ratio, absolute, or relative.
fair:classification	string	Literal name of the classification scheme or code list (e.g., "ISCO-08" or "NUTS").
fair:classificationRef	array of URIs	URIs pointing to the authoritative classification scheme.
fair:sentinel	boolean	Flag indicating that the value is a missing data / suppressed sentinel value (must be paired with const).
fair:unitType	string	Observation entity type for 1 row (e.g., "Person", "Household").
fair:universe	string	Broad population boundary for the variable (e.g., "Active workforce").

Variable Cascade References (DDI & CDIF Alignment)

• fair:variableRef: Generic link to a shared variable definition.

• fair:instanceVariableRef: Link to a dataset-specific variable implementation.

• fair:representedVariableRef: Link to a shared representation/value domain.

• fair:conceptualVariableRef: Link to a high-level conceptual variable.