Mechanism 4: $defs Keyword Refinements

The $defs keyword provides a standard location for reusable schema definitions. In the context of FAIR vocabularies, we use it to provide shared “mixins” and common structures (like URIs or multilingual strings) that authors can import via $ref instead of repeating complex annotation patterns on every property.

Provided Definitions (Refinements Vocabulary)

The vocab/refinements vocabulary provides several core definitions:

Definition	Purpose
FairAnnotated	Mixin: attach via allOf to enable FAIR annotations on a property. Enforces exclusivity for Variable Cascade references (*VariableRef).
FairUri	A string with format:uri plus specific annotations for persistence and identification.
FairCodedValue	A structure for handling coded values, rich labels, and machine-actionable semantic mappings.
FairDatasetDescriptor	A base object shape for common dataset-level metadata, including global Universe/Population binding.

Specification

For a full list of supported refinement types and their structures, see the SPEC.md.

Example

Importing the FairAnnotated definition to ensure the property is valid against our custom keywords while remaining a standard integer:

"population": {
  "type": "integer",
  "allOf": [
    { "$ref": "https://highvaluedata.net/fair-data-schema/vocab/refinements#/$defs/FairAnnotated" }
  ],
  "fair:conceptRef": "https://www.wikidata.org/wiki/Q1203",
  "fair:unitRef": "https://example.org/vocabs/units/persons"
}

$ref Syntax

Context	$ref pattern
Within same schema	"#/$defs/FairUri"
Cross-schema	Full canonical URI + JSON Pointer fragment
Local Development	Automatically resolved via the fair-data-schema Python registry

Working Example File

../../../examples/mechanism-4-refinements.json

{
    "$schema": "https://highvaluedata.net/fair-data-schema/dev",
    "$id": "https://example.org/schemas/mechanism-4-refinements",
    "title": "Mechanism 4: $defs Refinements Example",
    "description": "Demonstrates reusing shared keyword patterns from the FAIR refinements vocabulary via $ref. Instead of repeating annotation declarations on each property, we $ref shared definitions.",
    "type": "object",
    "required": [
        "id",
        "title",
        "population",
        "gdp",
        "region_code"
    ],
    "properties": {
        "id": {
            "$ref": "https://highvaluedata.net/fair-data-schema/dev/vocab/refinements#/$defs/FairUri",
            "title": "Record Identifier",
            "$comment": "FairUri enforces format:uri and adds fair:persistent:true annotation — both standard validation and FAIR annotation from a single $ref."
        },
        "title": {
            "type": "string",
            "title": "Record Title"
        },
        "population": {
            "type": "integer",
            "minimum": 0,
            "allOf": [
                {
                    "$ref": "https://highvaluedata.net/fair-data-schema/dev/vocab/refinements#/$defs/FairAnnotated"
                }
            ],
            "fair:concept": "https://www.wikidata.org/wiki/Q1203",
            "fair:unit": "person",
            "fair:label": {
                "en": "Population"
            },
            "$comment": "FairAnnotated mixin documents which fair: annotations are valid here. The actual annotation values are set inline."
        },
        "gdp": {
            "type": "number",
            "minimum": 0,
            "allOf": [
                {
                    "$ref": "https://highvaluedata.net/fair-data-schema/dev/vocab/refinements#/$defs/FairAnnotated"
                }
            ],
            "fair:concept": "https://www.wikidata.org/wiki/Q132821",
            "fair:unit": "USD",
            "fair:label": {
                "en": "Gross Domestic Product"
            }
        },
        "region_code": {
            "allOf": [
                {
                    "$ref": "https://highvaluedata.net/fair-data-schema/dev/vocab/refinements#/$defs/FairCodedValue"
                }
            ],
            "enum": [
                "DE",
                "FR",
                "IT",
                "ES",
                "PL"
            ],
            "fair:classification": [
                "https://ec.europa.eu/eurostat/ramon/nomenclatures/index.cfm?TargetUrl=LST_NOM_DTL&StrNom=CL_AREA"
            ],
            "$comment": "FairCodedValue provides the SKOS concept annotation. The enum keyword (standard JSON Schema) restricts the allowed values."
        }
    },
    "$comment": "This schema uses $ref to import shared definitions from the refinements vocabulary meta-schema. The Python registry.py resolves those URIs to local files during development, while GitHub Pages resolves them in production."
}