Python Package and API

Quick Example (Load, Validate, Save)

from models import DatasetSchema
from fair_data_schema.validator import validate_schema

# 1. Load schema from file
schema = DatasetSchema.from_file("my-schema.json")

# 2. Validate schema against FAIR meta-schema
errors = validate_schema(schema.to_dict())
assert not errors, f"Validation failed: {errors}"
print("✓ Schema is valid FAIR Data JSON Schema!")

# 3. Save modified schema to file
schema.title = "Updated FAIR Dataset 2024"
schema.to_file("my-schema-output.json")

Package API Reference

fair_data_schema — Python tooling for the FAIR Data JSON Schema dialect.

CLI entry point: fair-data-schema (see cli.py)

fair_data_schema.to_ro_crate(schema)

Convert a FAIR Data JSON Schema into an RO-Crate 1.1 compliant metadata dictionary.

Parameters:

schema (dict[str, Any] | Path | str) – A schema dictionary, or path (Path/str) to a schema JSON file.

Return type:

dict[str, Any]

Returns:

A dictionary formatted as a flat @graph RO-Crate 1.1 metadata document.

Schema URI registry.

Maps canonical https://highvaluedata.net/fair-data-schema/ URIs to local file-system paths so that cross-schema $ref resolution works during development without network access, and so that tests are fully offline.

fair_data_schema.registry.all_schemas()

Return a dict mapping full URIs to parsed schema dicts.

Return type:

dict[str, Any]

fair_data_schema.registry.resolve_uri(uri)

Resolve a canonical schema URI to a local Path.

Return type:

Path

fair_data_schema.registry.schema_uris()

Return all registered canonical schema URIs.

Return type:

list[str]

Schema validator.

Wraps jsonschema’s Draft202012Validator with a local referencing.Registry so that cross-schema $ref resolution works offline using the local file mappings defined in registry.py.

fair_data_schema.validator.is_valid_json(path)

Return True if path contains valid JSON, False otherwise.

Return type:

bool

fair_data_schema.validator.validate(instance, schema)

Validate instance against schema using the FAIR dialect-aware validator.

Returns a (possibly empty) list of ValidationError objects. Raises nothing — all errors are collected and returned.

Return type:

list[ValidationError]

fair_data_schema.validator.validate_file(schema_path, instance_path=None)

Validate a schema file (optionally against an instance file).

If instance_path is None, validates the schema itself against the standard JSON Schema 2020-12 meta-schema (i.e. checks the schema is a valid schema document).

Return type:

list[ValidationError]

CLI entry point for fair-data-schema.

Commands:

validate – validate a JSON instance against a schema (or a schema against the meta-schema) lint – check all schema files for JSON syntax validity info – show registered schema URIs

fair_data_schema.cli.export_cdif(schema, output=None)

Export a FAIR Data JSON Schema into a CDIF v1.1 profile JSON-LD metadata document.

Return type:

None

fair_data_schema.cli.export_croissant(schema, output=None)

Export a FAIR Data JSON Schema into an MLCommons Croissant 1.1 JSON-LD metadata document.

Return type:

None

fair_data_schema.cli.export_ro_crate(schema, output=None)

Export a FAIR Data JSON Schema into an RO-Crate 1.1 metadata document.

Return type:

None

fair_data_schema.cli.info()

Show registered schema URIs and their local file mappings.

Return type:

None

fair_data_schema.cli.lint(directory=PosixPath('.'))

Check all JSON files in schemas/ and examples/ for syntax validity.

Return type:

None

fair_data_schema.cli.serve(host='127.0.0.1', port=8000, root_path='', reload=False, workers=1)

Start the FAIR Data JSON Schema REST API server.

Return type:

None

fair_data_schema.cli.validate(schema, instance=None)

Validate a JSON instance against a schema, or a schema against the meta-schema.

Return type:

None

fair_data_schema.cli.version()

Print the package version.

Return type:

None

FAIR Pydantic Models (Standalone)

FAIR Data Schema — Pydantic models (auto-generated).

class models.DatasetRelation(**data)

One relationship entry within fair:datasetRelations.

class models.DatasetSchema(**data)

Root-level FAIR dataset schema.

Extends SchemaNode with a $schema declaration that defaults to the FAIR dialect URI for version dev.

classmethod from_dict(data)

Parse a FAIR schema from a plain dictionary.

Return type:

DatasetSchema

classmethod from_file(path)

Load and parse a FAIR schema from a JSON file.

Return type:

DatasetSchema

classmethod from_json(text)

Parse a FAIR schema from a JSON string.

Return type:

DatasetSchema

to_file(path, indent=2)

Write this schema to a JSON file.

Return type:

None

models.I18nString = str | dict[str, str]

“Âge”}.

Type:

A string or a BCP-47 language-mapped dict, e.g. {“en”

Type:

“Age”, “fr”

models.I18nText = str | dict[str, str]

A Markdown-formatted string or a language-mapped dict of Markdown strings.

models.JsonType

Valid JSON Schema type values.

alias of Literal[‘string’, ‘integer’, ‘number’, ‘boolean’, ‘array’, ‘object’, ‘null’]

class models.SchemaNode(**data)

A node in a FAIR-extended JSON Schema document.

Covers the full JSON Schema Draft 2020-12 vocabulary (all seven vocabularies declared in the FAIR dialect) plus FAIR annotation extensions.

All FAIR extension fields use the fair_ prefix to mirror the fair: JSON prefix and to prevent any naming collision with standard JSON Schema keywords, both present and future.

to_dict()

Serialise to a FAIR JSON Schema dict (fair: prefixed keys, no nulls).

Return type:

dict[str, Any]

to_json(indent=2)

Serialise to a FAIR JSON Schema string.

Return type:

str

class models.TemporalCoverage(**data)

Time period covered by the dataset (fair:temporalCoverage).