TypeScript Package & API Reference

The TypeScript package (@fair-data-schema/core or schemas/<version>/typescript/index.ts) provides auto-generated TypeScript interfaces and Zod validation schemas for the FAIR Data JSON Schema dialect.

Quick Example (Load, Validate, Save)

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

// 1. Load schema JSON from disk
const rawJson = JSON.parse(fs.readFileSync("my-schema.json", "utf-8"));

// 2. Validate at runtime using Zod
const schema: DatasetSchema = DatasetSchemaSchema.parse(rawJson);
console.log("✓ Valid FAIR dataset:", schema.title);

// 3. Save modified schema to disk
schema.title = "Updated FAIR Dataset 2024";
fs.writeFileSync("my-schema-output.json", JSON.stringify(schema, null, 2));

---

Exported Interfaces

DatasetSchema

Root-level FAIR dataset schema interface extending SchemaNode.

export interface DatasetSchema extends SchemaNode {
  $schema?: string;
}

SchemaNode

Core recursive interface representing a FAIR-extended JSON Schema node.

export interface SchemaNode {
  $id?: string;
  $ref?: string;
  $anchor?: string;
  $defs?: Record<string, SchemaNode>;
  $vocabulary?: Record<string, boolean>;
  $comment?: string;

  title?: string;
  description?: string;
  default?: any;
  deprecated?: boolean;
  readOnly?: boolean;
  writeOnly?: boolean;
  examples?: any[];

  type?: JsonType | JsonType[];
  enum?: any[];
  const?: any;
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: number;
  exclusiveMaximum?: number;
  multipleOf?: number;
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;
  minContains?: number;
  maxContains?: number;
  required?: string[];
  dependentRequired?: Record<string, string[]>;
  minProperties?: number;
  maxProperties?: number;

  properties?: Record<string, SchemaNode>;
  patternProperties?: Record<string, SchemaNode>;
  additionalProperties?: SchemaNode | boolean;
  items?: SchemaNode;
  prefixItems?: SchemaNode[];
  contains?: SchemaNode;
  allOf?: SchemaNode[];
  anyOf?: SchemaNode[];
  oneOf?: SchemaNode[];
  not?: SchemaNode;
  if?: SchemaNode;
  then?: SchemaNode;
  else?: SchemaNode;

  unevaluatedProperties?: SchemaNode | boolean;
  unevaluatedItems?: SchemaNode | boolean;

  format?: string;
  contentEncoding?: string;
  contentMediaType?: string;
  contentSchema?: SchemaNode;

  // FAIR Annotations
  "fair:resourceType"?: string;
  "fair:conceptRef"?: string;
  "fair:concept"?: I18nString;
  "fair:label"?: I18nString;
  "fair:description"?: I18nText;
  "fair:datasetRelations"?: DatasetRelation[];
  "fair:contributors"?: Record<string, any>[];
  "fair:provider"?: I18nString;
  "fair:providerRef"?: string;
  "fair:license"?: I18nString;
  "fair:licenseRef"?: string;
  "fair:temporalCoverage"?: TemporalCoverage;
  "fair:temporalCoverageRef"?: string;
  "fair:spatialCoverage"?: I18nString;
  "fair:spatialCoverageRef"?: string;
  "fair:population"?: I18nString;
  "fair:populationRef"?: string;
  "fair:structureType"?: string;
  "fair:quality"?: Record<string, any>[];
  "fair:classification"?: I18nString;
  "fair:classificationRef"?: any[];
  "fair:measurementUnit"?: I18nString;
  "fair:measurementUnitRef"?: string;
  "fair:measurementTechnique"?: I18nString;
  "fair:measurementTechniqueRef"?: string;
  "fair:quantity"?: I18nString;
  "fair:quantityRef"?: string;
  "fair:measurementScale"?: I18nString;
  "fair:measurementScaleRef"?: string;
  "fair:unitType"?: I18nString;
  "fair:unitTypeRef"?: string;
  "fair:universe"?: I18nString;
  "fair:universeRef"?: string;
  "fair:variableRef"?: string;
  "fair:instanceVariableRef"?: string;
  "fair:representedVariableRef"?: string;
  "fair:conceptualVariableRef"?: string;
  "fair:sentinel"?: boolean;
}

Helper Interfaces

• TemporalCoverage: { description?: I18nString; start?: string; end?: string; }

• DatasetRelation: { relationType: string; targetRef: string; sourceVariables?: string[]; targetVariables?: string[]; cardinality?: string; description?: I18nString; }

---

Exported Zod Validation Schemas

• DatasetSchemaSchema: z.ZodType<DatasetSchema> — Validates root FAIR dataset schemas.

• SchemaNodeSchema: z.ZodType<SchemaNode> — Lazy recursive Zod schema for any schema node.

• TemporalCoverageSchema: Zod schema for fair:temporalCoverage.

• DatasetRelationSchema: Zod schema for fair:datasetRelations.

• I18nStringSchema: z.union([z.string(), z.record(z.string(), z.string())]).

• I18nTextSchema: z.union([z.string(), z.record(z.string(), z.string())]).

• JsonTypeSchema: z.enum(["string", "integer", "number", "boolean", "array", "object", "null"]).