# 🚀 Executive Overview: Metadata Curators & Data Stewards

> **Achieve high semantic precision, govern controlled vocabularies, manage complex classifications, and implement DDI variable cascades with ease.**

---

## 1. At a Glance: The FAIR Data JSON Schema Breakthrough

Standard JSON Schema `enum` keywords only support flat string arrays (`["EMP", "UNE"]`), stripping out category labels, descriptions, and classification URIs. FAIR Data JSON Schema brings DDI social science precision into JSON—enabling variable cascades (`instance` ➔ `represented` ➔ `conceptual`), rich code lists (`fair:refinements`), and offline vocabulary resolution.

FAIR Data JSON Schema introduces dedicated vocabulary extensions (`fair:refinements`, `fair:classification`, `fair:conceptRef`, `fair:representedVariableRef`). Curators update central variable registries once, and all institutional dataset schemas inherit updated code lists, labels, and concept links automatically.

```
                    ┌──────────────────────────────────────────────┐
                    │            CONCEPTUAL VARIABLE               │
                    │  "Marital Status" (Domain Concept URI)       │
                    └──────────────────────┬───────────────────────┘
                                           │
                                           ▼
                    ┌──────────────────────────────────────────────┐
                    │           REPRESENTED VARIABLE               │
                    │  Standardized Code List & Category Labels    │
                    └──────────────────────┬───────────────────────┘
                                           │
                                           ▼
                    ┌──────────────────────────────────────────────┐
                    │            INSTANCE VARIABLE                 │
                    │  Physical Column Header in 2026 Microdata    │
                    └──────────────────────────────────────────────┘
```

---

## 2. Your New Curation Superpowers

### 🏷️ 1. Advanced Classifications Beyond Flat Enums
Replace flat `enum` arrays with self-documenting code lists carrying human category labels, descriptions, and official classification references:

```json
{
  "employment_status": {
    "type": "string",
    "fair:classification": "https://example.org/cv/employment-status-v1.json",
    "fair:refinements": {
      "codes": [
        { "code": "EMP", "label": "Employed", "description": "Working for pay or profit." },
        { "code": "UNE", "label": "Unemployed", "description": "Actively seeking work." }
      ]
    }
  }
}
```

### 🔁 2. Reusable DDI Variable Cascades
Re-use variable definitions across institutional microdata files using `$ref` and variable cascade keywords (`fair:conceptualVariableRef`, `fair:representedVariableRef`). Update a central variable definition once; all dataset schemas inherit the updated metadata automatically.

### 🌐 3. Instant Offline Vocabulary Registry
Validate complex microdata schemas using `fair_data_schema` without relying on external network calls. The built-in registry (`fair_data_schema.registry`) resolves canonical URIs to local cached schema files automatically.

---

## 3. Why It Beats the Alternatives

| Curation Dimension | Flat JSON Enums | Excel Crosswalks | FAIR Data JSON Schema |
| :--- | :--- | :--- | :--- |
| **Semantic Depth** | Strings only (`["EMP"]`) | Disconnected text | **Full labels, URIs & descriptions** |
| **Variable Reuse** | Duplicated in every file | Manual copy-paste | **Centralized DDI cascades (`$ref`)** |
| **Validation Speed** | Network calls to URIs | Manual review | **Instant offline registry resolution** |

---

## 4. Transform Your Curation Workflows Today

Achieve high semantic precision and eliminate vocabulary drift across microdata files:

1. **Build Central Controlled Vocabularies**: Define standard code lists in `/cv/*.json` files carrying human labels and descriptions.
2. **Implement DDI Variable Cascades**: Create represented variable files for reusable items and reference them in dataset schemas via `$ref`.
3. **Validate Offline**: Test `fair_data_schema.registry` to verify classification compliance offline without external network dependencies.

### 📚 Essential Metadata Curation Resources
* **[Refinements & Classifications Specification](../../specs/keywords.md#refinements)**
* **[Controlled Vocabularies Directory](https://github.com/hvdnet/json-meta-schema/tree/main/schemas/cv)**
* **[Variable Cascades Cookbook](../../cookbook/index.md)**