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 other SSSOM serializations and to JSKOS format.

• Install
• Usage
  • Command line
  • API
  • Validation errors
  • Web application
• Limitations
• Transformation to JSKOS
• Maintainers
• Contribute
• License

npm install sssom-js

Requires Node.js >= 20.19.

The package includes the command line client sssom:

Usage: sssom [options] [<mappings-file> [<metadata-file>]] 

Parse and convert SSSOM

Options:
  -f, --from FORMAT  input format (tsv, csv, json)
  -t, --to FORMAT    output format (json, ndjson, jskos, ndjskos)
  -o, --output       output file (default: - for stdout)
  -p, --propagate    add propagatable slots to mappings
  -c, --curie FILE   additional CURIE map (JSON or YAML file)
  -l, --liberal      parse less strict than the specification
  -m, --mappings     write mappings only
  -v, --verbose      emit error verbosely
  -j, --json-errors  emit errors detailled in JSON
  -h, --help         output usage information
  -V, --version      output the version number

The following formats are supported:

If not specified, formats are guessed from file name with fallback to tsv (from) and ndjson (to).

Formats json and jskos require to fully load the input into memory for processing, the other formats support streaming processing.

Liberal processing allows:

• empty/missing mappings block

If 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

import { parseSSSOM, TSVReader, toJskosRegistry, toJskosMapping } from "sssom-js"

This asynchronous function parses SSSOM in format options.from (json, or tsv as default) from a stream or file and returns a mapping set on success. The result should directly be serializable as SSSOM/JSON (or to 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" })

• from (string, tsv by default): input format
• to (string): response format (sssom by default or jskos)
• metadata (string or object): mapping set metadata (external metadata mode) or file to read from
• curie (string or object) additional CURIE map or file to read from
• propagation (boolean, false by default): enables propagation of mapping set slots
• liberal (boolean, false by default):
  • allow empty mappings block in SSSOM/TSV (but still read and validate the metadata block)
  • do not require mapping set slots (neither mapping_set_id nor license)
• metadataHandler (function) called for parsed metadata
• mappingHandler (function) called for each parsed mapping

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)

Options can be given with a second optional argument object:

new TSVReader(input, { delimiter: "," }) // SSSOM/CSV

Convert a parsed MappingSet to a JSKOS Registry object.

Convert a parsed Mapping to a JSKOS Concept Mapping object.

Validation error objects (emitted as JSON objects with command line option -x, --errors) have three fields:

• message an error message
• value an optional value that caused the error
• position an optional object mapping locator types to error locations. The following locator types are used:
  • line: a line number (given as string)
  • jsonpointer: a JSON Pointer to the malformed YAML or JSON element

A web form to validate and transform SSSOM/TSV is made available at https://gbv.github.io/sssom-js/. This application is not included in the package release at npm.

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:

• All slots of type Uri must be absolute URIs as defined in RFC 3986
• Literal Mappings are not supported
• Non-standard slots are not supported (mapping set slot extension_definition is ignored)
• SSSOM/JSON, the JSON serialization of SSSOM has not been specified yet, so it may differ from the JSON format used in this library

The transformation of SSSOM to JSKOS does not support the following mapping slots (yet):

• subject_category and object_category
• predicate_type, predicate_label and predicate_modifier
• reviewer_id and reviewer_label
• license as individual JSKOS mappings (in contrast to sets of mappings) have no license
• see_also and other having no clear semantics
• slots that carry information about automatic mapping algorithms (see this issue)

Slot creator_id/creator_label and author_id/author_label are merged into JSKOS field creator

Directory survey contains a survey of published SSSOM data with validation results. See dev branch for most recent update.

• @nichtich (Jakob Voß)

Contributions are welcome! Best use the issue tracker for questions, bug reports, and/or feature requests!

MIT license