TypeScript SDK — Types & Zod Schemas

The FAIR Data JSON Schema project provides auto-generated TypeScript interfaces and Zod schemas for client-side web applications, Node.js API servers, and AI / MCP tool-calling integrations.

Overview

The generated TypeScript code is located in schemas/<version>/typescript/index.ts (and mirrored in the web distribution at dist/<version>/typescript/index.ts).

It provides:

• Compile-time TypeScript interfaces: SchemaNode, DatasetSchema, TemporalCoverage, DatasetRelation

• Runtime validation Zod schemas: SchemaNodeSchema, DatasetSchemaSchema, TemporalCoverageSchema, DatasetRelationSchema

• Type Aliases: I18nString, I18nText, JsonType

Installation

To validate data at runtime using Zod, install zod in your JavaScript/TypeScript project:

npm install zod

Basic Usage

Parsing & Validating Schemas (Zod)

You can validate incoming JSON dataset schemas at runtime using DatasetSchemaSchema:

import { DatasetSchemaSchema, DatasetSchema } from "./schemas/dev/typescript/index.ts";

const rawJson = {
  $schema: "https://highvaluedata.net/fair-data-schema/dev",
  title: "Environmental Sensor Station Observations 2024",
  "fair:license": "CC-BY-4.0",
  "fair:unitType": "SensorStation",
  type: "object",
  properties: {
    air_temperature: {
      title: "Ambient Surface Air Temperature",
      type: "number",
      "fair:measurementUnit": "Degree Celsius",
      "fair:measurementUnitRef": "http://qudt.org/vocab/unit/DEG_C"
    }
  }
};

// Validate raw JSON schema at runtime
const schema: DatasetSchema = DatasetSchemaSchema.parse(rawJson);

console.log(schema.title); // "Environmental Sensor Station Observations 2024"
console.log(schema["fair:license"]); // "CC-BY-4.0"

TypeScript Compile-Time Autocomplete

When authoring schemas programmatically in TypeScript, use the DatasetSchema and SchemaNode interfaces for full IDE autocomplete:

import { DatasetSchema, SchemaNode } from "./schemas/dev/typescript/index.ts";

const ageVariable: SchemaNode = {
  type: "integer",
  title: "Age",
  minimum: 0,
  "fair:measurementUnit": "years",
  "fair:quantity": "Time duration"
};

const myDataset: DatasetSchema = {
  $schema: "https://highvaluedata.net/fair-data-schema/dev",
  title: "Census 2024",
  "fair:license": "CC-BY-4.0",
  "fair:population": "Total Resident Population",
  properties: {
    age: ageVariable
  }
};

Auto-Generation

The TypeScript definition file schemas/<version>/typescript/index.ts is auto-generated from the FAIR annotation meta-schemas using Jinja2 templates.

To regenerate TypeScript models for the development track:

uv run python scripts/generate_typescript.py --version dev