The registry aggregates mapping metadata from external mapping registries listed in mapping-server.yml. Each registry points to a YAML file that lists individual mapping sets (typically SSSOM TSV files). During the ETL, each mapping set's metadata is extracted and transformed into the FAIR Mappings Schema using linkml-map.
mapping-server.yml
└── external registry YAML (e.g. registry.yml in another repo)
└── mapping_set_references
└── SSSOM TSV files (metadata extracted, not the mappings themselves)
└── linkml-map transform → MappingSpecification JSON
To add a new mapping registry to the Mapping Commons:
-
Create a registry YAML file in your mapping repository. Follow the SSSOM registry format:
mapping_registry_id: https://example.org/my-mappings registry_title: My Mapping Project registry_description: Mappings between X and Y homepage: https://github.com/org/my-mappings documentation: https://github.com/org/my-mappings/blob/main/README.md mapping_set_references: - mapping_set_id: https://example.org/my-mappings/foo_bar.sssom.tsv mapping_set_group: my_group local_name: foo_bar.sssom.tsv
-
Ensure your SSSOM files have good metadata in their headers. The following fields are extracted:
mapping_set_id(required) — unique identifiermapping_set_title— displayed as the mapping namemapping_set_description— shown in search resultslicense— e.g.https://creativecommons.org/publicdomain/zero/1.0/mapping_set_versionsubject_source/object_source— what's being mapped (see docs/per_mapping_source.md if your sources vary per mapping)mapping_tool— how the mappings were createdpublication_date
-
Open a PR to add your registry to
mapping-server.yml:registries: # ... existing entries ... - id: my-mappings uri: https://raw.githubusercontent.com/org/my-mappings/main/registry.yml
-
The CI will automatically fetch your registry, extract metadata from each mapping set, and include it in the site.
The linkml-map transforms that convert mapping formats into the FAIR Mappings Schema, and the slot-level SSSOM sets that document them, live in fair-mappings-schema (src/fair_mappings_schema/transformations/ and src/fair_mappings_schema/mappings/). That repository is their source of truth, and this one only registers them. Currently supported:
| Format | Transform | Source type |
|---|---|---|
| SSSOM | https://w3id.org/fair-map/transforms/sssom-to-fair | mapping set |
| LinkML-Map | https://w3id.org/fair-map/transforms/linkmlmap-to-fair | TransformationSpecification |
To add support for a new mapping format:
-
Add the transform (and its slot-level SSSOM set) to fair-mappings-schema, following the linkml-map specification. The transform maps your format's metadata to
MappingSpecificationfields. -
Give it a PURL under
https://w3id.org/fair-map/transforms/in the w3idfair-mapconfig. -
Register it in
registry.ymlby that PURL:mapping_set_references: - mapping_set_id: https://w3id.org/fair-map/transforms/myformat-to-fair mapping_set_group: fair-mappings-transforms local_name: myformat-to-fair.transformation.yaml
-
Update
scripts/cli.pyto handle the new format if it requires different fetching/parsing logic.
# Prerequisites: uv, just
just all # Full ETL
just serve # Local server at http://localhost:8080Open an issue.