Skip to main content

FAIR Mappings Schema

Build and test Docs PyPI Python versions DOI Built with LinkML License

A minimal metadata schema for describing mapping specifications — SSSOM mapping sets, LinkML-Map transformations, R2RML, XSLT and the like — so that they can be found, cited, assessed and reused. It records what a mapping specification is, who made it, what it maps between and where to get it. It does not model the individual mappings themselves.

The schema is developed by the RDA FAIR Mappings Working Group and written in LinkML, so JSON Schema, Python classes, OWL and SHACL can all be generated from it.

Documentation: https://mapping-commons.github.io/fair-mappings-schema

What it describes

Class Describes
MappingSpecification A mapping artefact: identifier, type, version, license, method, documentation and where to download it
Source What is being mapped from (subject_source) or to (object_source): an ontology, vocabulary, schema, database or API
Agent Who was involved, as author, creator or reviewer: a Person (ORCID), an Organization (ROR) or a piece of Software

Supported specification types: sssom, linkml_map, r2rml, rml, yarrrml, sparql, xslt, shacl and other.

A minimal mapping specification:

id: https://example.org/mappings/anatomy
name: Anatomy ontology A to B
type: sssom
version: "3.0.0"
license: https://creativecommons.org/publicdomain/zero/1.0/
mapping_method: semi-automated matching followed by manual review
content_url: https://example.org/mappings/anatomy.sssom.tsv
author:
  - id: orcid:0000-0002-1825-0097
    type: Person
    name: Ada Curator
creator:
  - id: example:exomatch
    type: Software
    name: exomatch
    version: "0.4.2"
subject_source:
  name: Example Anatomy Ontology A
  type: ontology
  version: "2024-05-01"
object_source:
  name: Example Anatomy Ontology B
  type: ontology
  version: "2024-05-20"

Installation

pip install fair-mappings

This installs the schema, the generated Python data model and the fair-mappings command line tool. Python 3.10 or newer is required.

Usage

Command line

Extract a FAIR Mappings description from an existing SSSOM mapping set or LinkML-Map transformation:

$ fair-mappings parse -I sssom hp-mp.sssom.tsv
Wrote hp-mp.fms.yml
id: https://w3id.org/sssom/mappings/hp-mp
name: HP to MP mappings
description: Phenotype mappings between the Human Phenotype Ontology and the Mammalian
  Phenotype Ontology
license: https://creativecommons.org/licenses/by/4.0/
type: sssom
subject_source:
  id: obo:hp
object_source:
  id: obo:mp

Validate a description against the schema. With -I, the source document is converted first, so you can check an SSSOM file directly:

$ fair-mappings validate hp-mp.fms.yml
OK: hp-mp.fms.yml is valid.

$ fair-mappings validate -I sssom hp-mp.sssom.tsv
OK: hp-mp.sssom.tsv is valid.

validate exits non-zero and prints the errors to stderr when an instance is invalid, so it can be used in CI. Run fair-mappings --help for all options.

Python

from fair_mappings_schema import load_mapping, validate_instance

spec = load_mapping("hp-mp.sssom.tsv", "sssom")  # a MappingSpecification dict
errors = validate_instance(spec)                 # [] if valid

parse_sssom_tsv also accepts an iterable of lines, so the metadata header of a remote mapping set can be read from a streamed response without downloading the whole file.

Identifiers

Schema https://w3id.org/fair-map/schema
Schema source https://w3id.org/fair-map/schema.yaml
Prefix fairmap → https://w3id.org/fair-map/, e.g. fairmap:MappingSpecification

Development

The project uses uv and the command runner just:

git clone https://github.com/mapping-commons/fair-mappings-schema
cd fair-mappings-schema
uv sync --dev
just test       # schema checks, Python tests and example validation
just gen-doc    # regenerate the documentation
just testdoc    # build and serve the docs locally

Run just to list all recipes. The schema lives in src/fair_mappings_schema/schema/fair_mappings_schema.yaml; the Python data model in src/fair_mappings_schema/datamodel/ is generated from it with just gen-python and should not be edited by hand.

Contributions are welcome. See CONTRIBUTING.md and the issue tracker.

Citing

If you use the FAIR Mappings Schema, please cite it through its Zenodo record: doi:10.5281/zenodo.24086059.

License

Apache License 2.0.

This project was generated from linkml-project-copier (doi:10.5281/zenodo.15163584).

Metadata

Release files for fair-mappings 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fair-mappings 1.0.1
File Size Uploaded Provenance Actions
fair_mappings-1.0.1.tar.gz 195.4 kB With provenance Details for fair_mappings-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fair-mappings 1.0.1
File Interpreter ABI Platform Actions
fair_mappings-1.0.1-py3-none-any.whl Python 3 none any Details for fair_mappings-1.0.1-py3-none-any.whl

Total release size: 220.1 kB

Release files / fair_mappings-1.0.1.tar.gz

Download URL fair_mappings-1.0.1.tar.gz
Size 195.4 kB
Tags Source
SHA-256 checksum
How to use checksums
266f4094e2a8eac1fe58f9064127731236f1a4bb163fcbe72c06e83c6c3b1198
BLAKE2b-256 checksum
How to use checksums
acf34634f511407263888219a85e8b394402590165bef54f408c4a144914f492
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / fair_mappings-1.0.1-py3-none-any.whl

Download URL fair_mappings-1.0.1-py3-none-any.whl
Size 24.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22c00992928c690049400a1633e2d512b49eb6d77bc82d718210ebcc248525c2
BLAKE2b-256 checksum
How to use checksums
e1ba90099652fac6915d6dedb80c12ad1b9231406a89c2ae914c12c64fa0e8e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for fair-mappings 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fair_mappings-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page