Simple Standard for Sharing Ontology Mappings (SSOM) JavaScript library
This Node package provides methods and a command line client to process mappings in SSSOM format.
It implements parsing variants of SSSOM (TSV, CSV and JSON) with validation and transformation to multiple formats, including JSKOS and RDF.
Requires Node.js >= 20.19.
npm install sssom-js
For RDF export in the command line client also install jsonld2rdf.
npm install jsonld2rdf
The web interface can be deployed on any web server by copying static files from directory docs of the source code repository.
The package includes a command line client to parse and convert SSSOM. Usage and options:
sssom [options] [<mappings-file> [<metadata-file>]]
| short | long | argument | description |
|---|---|---|---|
-f | --from | format | input format (csv, tsv, json) |
-t | --to | format | output format (json, ndjson, jskos, ndjskos, nq, nt, ttl) |
-o | --output | file | output filename or default - for stdout |
-p | --propagate | add propagatable slots to mappings | |
-b | --liberal | parse less strict than the specification | |
-c | --curie | file | additional CURIE map (JSON or YAML file) |
-s | --schemes | file | JSKOS concept schemes to detect |
-m | --mappings | emit mappings only | |
-v | --verbose | emit error verbosely | |
-j | --json-errors | emit errors in JSON (Data Validation Error Format) | |
-h | --help | emit usage information | |
-V | --version | emit the version number |
A web interface to validate and transform SSSOM/TSV is made available at https://gbv.github.io/sssom-js/. The application is not included in the package release at npm.
import { parseSSSOM, TSVReader, toJskosRegistry, toJskosMapping } from "sssom-js"
This asynchronous function parses SSSOM in an input format from a stream or file and returns a mapping set on success. The result should directly be serializable as SSSOM/JSON (or as JSKOS with option to set to jskos).
import { parseSSSOM } from "sssom-js"
const { mappings, ...metadata } = await parseSSSOM(process.stdin)
An untruthy input value will skip processing of mappings so only the mapping set is returned:
const metadata = await parseSSSOM(false, { metadata: "metadata.sssom.yaml" })
See below for a description of common options. Additional options are:
This is a utility function to parse SSSOM from a string. Equivalent implementation in NodeJS:
parseSSSOMString = (input, options={}) => parseSSSOM(Readable.from(input), options)
This event emitter parses SSSOM/TSV from a stream and emits metadata and mapping events:
import fs from "fs"
import { TSVReader } from "sssom-js"
const input = fs.createReadStream("test/valid/minimal.sssom.tsv")
new TSVReader(input)
.on("metadata", console.log)
.on("mapping", console.log)
.on("error", console.error)
.on("end", console.log)
new TSVReader(input, { delimiter: "," }) // parse SSSOM/CSV
A second optional argument can be used to pass options propagate (boolean), liberal (boolean), delimiter (string), curie (object), metadata (object), and storeMappings (boolean). The latter makes mappings to be collected and returned with the result at the end of parsing.
Convert a parsed MappingSet to a JSKOS Registry object.
Convert a parsed Mapping to a JSKOS Concept Mapping object.
The following options are supported by both the command line client, and the API:
Enables propagation of mapping set slots. False by default.
Enabling liberal parsing will
mapping_set_id nor license) so the metadata block can be emptymapping_justificationIf you want to allow all CURIE prefixes from Bioregistry without explicitly defining them in curie_map you can download and convert the current list for instance with command line tools curl and jq this way (requires local copy of file bioregistry.jq) and then reference result file bioregistry.json with option --curie:
curl -sL https://w3id.org/biopragmatics/bioregistry.epm.json | \
jq -Sf bioregistry.jq > bioregistry.json
JSKOS Concept Schemes to detect when transforming to JSKOS
Emit mappings only. Metadata is parsed and validated nevertheless.
Mapping set metadata file in JSON or YAML format for external metadata mode. Is passed as second argument in the command line client or as named option in the API. The API also accepts a parsed object.
Validation errors follow the Data Validation Error Format in condense form. Each error is an object with three fields:
message an error messagevalue an optional value that caused the errorposition an optional object mapping locator types to error locations. The following locator types are used:
line: a line number given as string, starting with 1 for the first linelinecol: line a column number (both starting with 1), separated by :rfc5147: line span conforming to RFC 5147, for instance line=2,4 for line 3 (!) to 4jsonpointer: JSON Pointer to the malformed YAML or JSON element (for instance /creator_id)Input format and output format can be specified via command line options from and to, and in the web interface.
of the mappings, given as string. The following formats are supported so far:
| format | description | from | to | API |
|---|---|---|---|---|
tsv | SSSOM/TSV | yes | - | yes |
csv | SSSOM/CSV | yes | - | yes |
json | SSSOM/JSON/JSON-LD | yes | yes | yes |
ndjson | metadata and mappings on individual lines (SSSOM/JSON) | no | yes | - |
jskos | JSKOS | - | to | yes |
ndjskos | metadata and mappings on individual lines (JSKOS) | no | yes | - |
nq | NQuads (RDF) of raw mappings | - | no | yes |
nt | NTriples (RDF) | - | requires jsonld2rdf | - |
ttl | RDF/Turtle (RDF) | - | requires jsonld2rdf | - |
If not specified, formats are guessed from file name with fallback to tsv (from) and ndjson (to).
Formats json, jskos, nt, and ttl require to fully load the input into memory for processing, the other formats support streaming processing.
NQuads format (nq) is limited to the raw mapping statements without metadata and additional slots except subject_id, predicate_id, object_id, and optional mapping_set_id. Combine with option -m, --mappings to omit the latter, resulting in NTriples format of raw mappings.
RDF serialisation of SSSOM has not fully been specified yet. This package uses a JSON-LD context to transform SSSOM/JSON to SSSOM/RDF, except for NQuad (nq) output format that only consists of one triple per mapping.
The following slots are not included because semantics are not clear (yet) or because their content better belongs to another place:
The following slots will likely be included once a good existing predicate URI has been found:
The JSKOS data format is used in terminology applications for controlled vocabularies and their mappings.
The following correspondence between SSSOM and JSKOS has not fully been implemented yet. Some JSKOS fields will only be available since version 0.7.0 of JSKOS specification.
| SSSOM slot | JSKOS field |
|---|---|
| comment | note.und[] |
| creator_id | contributor[].uri |
| creator_label | contributor[].prefLabel.und |
| publication_date | published |
| see_also | ? |
| other | - |
| SSSOM slot | JSKOS field |
|---|---|
| mapping_date | created |
| mapping_provider | publisher[].url |
| mapping_tool | tool[].url* (0.7.0) |
| mapping_tool_id | tool[].uri* (0.7.0) |
| mapping_tool_version | tool[].version* (0.7.0) |
| object_source | to.memberSet[].inScheme[].uri |
| object_source_version | to.memberSet[].inScheme[].version (0.7.0) |
| object_type | from.memberSet[].type (URI, limited list) |
| subject_source | from.memberSet[].inScheme |
| subject_source_version | from.memberSet[].inScheme[].version (0.7.0) |
| subject_type | from.memberSet[].type (URI, limited list) |
| predicate_type | - |
| object_match_field | - (see this discussion) |
| object_preprocessing | - (dito) |
| subject_match_field | - (dito) |
| subject_preprocessing | - (dito) |
| similarity_measure | - (dito) |
* The correspondence of slots mapping_tool , mapping_tool_id, and mapping_tool_version is slightly more complicated.
| SSSOM slot | JSKOS field |
|---|---|
| curie_map | - |
| license | license.uri |
| mappings | mappings (of a registry or concordance) |
| mapping_set_id | uri |
| mapping_set_version | version (0.7.0) |
| mapping_set_source | source |
| mapping_set_title | prefLabel.und |
| mapping_set_description | definition |
| issue_tracker | issueTracker (0.7.0) |
| predicate_label | - |
| extension_definitions | - |
| SSSOM slot | JSKOS field |
|---|---|
| mapping_id | uri |
| subject_id | from.memberSet[].uri |
| subject_label | from.memberSet[].prefLabel |
| subject_category | - |
| predicate_id | type |
| predicate_label | - (implied by type) |
| object_id | to.memberSet[].uri |
| object_label | to.memberSet[].prefLabel |
| object_category | - |
| mapping_justification | justification (0.7.0) |
| author_id | creator[].uri |
| author_label | creator[].prefLabel |
| reviewer_id | annotations[].creator.id |
| reviewer_label | annotations[].creator.name |
| mapping_source | source |
| confidence | mappingRelevance |
| curation_rule | guidelines (0.7.0) |
| curation_rule_text | guidelines[].prefLabel (0.7.0) |
| issue_tracker_item | issue (0.7.0) |
| license | - (only for mapping sets) |
| predicate_modifier | - |
| mapping_cardinality | - |
| match_string | - (see this discussion) |
| similarity_score | - (dito) |
This library follows the SSSOM specification as close as possible, but it does not aim to be a fully compliant implementation. The latter would require to also comply to LinkML, a specification much more complex then needed for SSSOM and not fully been implemented in JavaScript yet. In particular:
extension_definition is ignoredother is read and validated but not usedmapping_id is not checked.Directory survey contains a survey of published SSSOM data with validation results. See dev branch for most recent update.
Contributions are welcome! Best use the issue tracker for questions, bug reports, and/or feature requests!
MIT license
FAQs
Simple Standard for Sharing Ontology Mappings (SSOM) JavaScript library
The npm package sssom-js receives a total of 111 weekly downloads. As such, sssom-js popularity was classified as not popular.
We found that sssom-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.