fetch_salmon_ontology

fetch_salmon_ontology(
    url=_DEFAULT_URL,
    accept='text/turtle, application/rdf+xml;q=0.8',
    cache_dir=None,
    fallback_urls=None,
    timeout_seconds=30,
    release=None,
    snapshot_dir=None,
)

Fetch the Salmon Domain Ontology with HTTP caching.

Downloads an ontology, by default the Salmon Domain Ontology (smn), using HTTP content negotiation, and caches each response with its ETag/Last-Modified validators when the server sends them. Supports fallback URLs if the primary URL fails.

Each copy is cached under the URL that returned it and the accept it was fetched under: its file name is the first 16 hexadecimal digits of the SHA-256 of the URL, a newline and accept (as UTF-8), with the extension .ttl whatever the representation, and its validators sit beside it with the extensions .etag and .last_modified. Fetches of different URLs or representations into one cache_dir therefore never overwrite each other, a conditional request carries only the validators that the URL it is sent to returned under the same accept, and a 304 answer returns that URL’s own copy. metasalmon names its cache files the same way.

With release or snapshot_dir, it reads a pinned release of smn or gcdfo instead: one file of that release’s snapshot, the directory each ontology publishes as docs/releases/<version>/, and nothing newer. The file is the representation accept prefers among the three a snapshot carries (text/turtle for .ttl, application/rdf+xml for .owl, application/ld+json for .jsonld). When the snapshot carries a MANIFEST.sha256, the file must be listed in it with the SHA-256 of its bytes, or the call raises OntologyReleaseError.

Parameters

Name Type Description Default
url str Primary ontology URL: the canonical SMN namespace root, as in metasalmon. "https://w3id.org/smn/"
accept str Accept header for content negotiation "text/turtle, application/rdf+xml;q=0.8"
cache_dir str Directory to store cached ontology and headers. Defaults to a persistent per-user cache, in the locations R’s tools::R_user_dir() uses for metasalmon’s: $XDG_CACHE_HOME/metasalmonpy/ontology when XDG_CACHE_HOME is set, and otherwise ~/Library/Caches/metasalmonpy/ontology on macOS, %LOCALAPPDATA%\metasalmonpy\ontology on Windows and ~/.cache/metasalmonpy/ontology elsewhere. None
fallback_urls List[str] URLs tried in order if the primary URL fails. None (the default) tries ["https://w3id.org/smn"] when url is the default and none otherwise: that fallback serves smn, so a call for any other ontology must not be answered by it. [] tries none. None
timeout_seconds float Timeout in seconds for each HTTP request, as metasalmon’s timeout_seconds. It bounds the connection, each wait for the server’s bytes, and the whole transfer: a server that keeps sending, slowly, is cut off timeout_seconds after the request began, as curl cuts it off under metasalmon. 30
release str A release version of the ontology url names, such as "0.0.3"; url must then be the smn or gcdfo ontology IRI. The release is downloaded from its version IRI (https://w3id.org/smn/0.0.3), or from the snapshot directory on GitHub Pages when that fails, into <cache_dir>/releases/<ontology>/<version>/ together with its MANIFEST.sha256, once: a release does not change, so later calls read that copy. A release that served no manifest when it was downloaded stays unverified in that cache; delete its directory to download it again. fallback_urls is not used. None
snapshot_dir str or os.PathLike A local directory holding a release snapshot of the ontology url names, such as a checkout’s docs/releases/0.0.3/. The file is read from it and nothing is downloaded. Give release or snapshot_dir, not both: this call does not parse the file, so it could not check that the directory holds that release. find_terms() takes both and checks the snapshot’s owl:versionIRI. None

Returns

Name Type Description
str Path to the cached copy that the answering URL returned, holding exactly the bytes that URL sent: nothing is decoded or re-encoded. When every URL fails, the path of the eligible copy a URL this call tried returned under accept, with a UserWarning (see Notes). With release or snapshot_dir, the path to the release file read. It never falls back to the latest ontology: a release that cannot be read or does not match its manifest raises. Compute the file’s SHA-256 to record exactly what was read; find_terms() records it for you.

Raises

Name Type Description
RuntimeError If every URL fails and no eligible copy is cached for a URL this call tried under accept, naming the URLs and the last failure. A copy of another ontology, a copy fetched under another accept, a copy in the layout before each URL and representation had its own, and a copy known to be stale are never returned; they are left on disk.
OntologyReleaseError With release or snapshot_dir, when the release cannot be read as asked. It is a RuntimeError.

Notes

When every URL fails and a copy this call may use is cached, a UserWarning names the copy and the last failure, and the copy is returned. A copy may be used when a URL this call tried returned it under this call’s accept, and it is still eligible. A copy stays eligible until a replacement for it arrives, which marks it superseded in a <copy>.invalid file before the replacement is written (the marker goes once the replacement and its validators are complete), or a 304 for it carries an ETag contradicting the one it was sent. A failed refresh alone never makes a copy ineligible, and neither does its age (Brett, Q71, 2026-10-03: “if the cache matches the requested ontology and refresh fails, continue with a warning. Do not use unrelated, mismatching or otherwise known-stale caches”; metasalmon’s B-422).

Examples

>>> from metasalmonpy import fetch_salmon_ontology
>>> ttl_path = fetch_salmon_ontology()
>>> print(f"Ontology cached at: {ttl_path}")
>>> # Read the ontology with rdflib or similar
>>> with open(ttl_path, 'r') as f:
...     ontology_content = f.read()
Back to top