FAIR Mappings Schema
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.
Related work
- RDA FAIR Mappings Working Group: use cases, recommendations and the conceptual model this schema implements
- SSSOM: the Simple Standard for Sharing Ontological Mappings
- LinkML-Map: schema mappings with executable transformation rules
- Semantic Mapping Vocabulary (semapv)
License
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.