sstim

# SSTIM

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21286974.svg)](https://doi.org/10.5281/zenodo.21286974)

**SSTIM** is an open, evolving reference for stimuli and sensory stimulation,
designed to connect human knowledge, AI systems, scientific research, and
technology through precise concepts, evidence-aware descriptions, and
persistent, citable references. Its purpose is to make this knowledge easier to
understand, compare, challenge, validate, exchange, and improve.

Its **current formal implementation** is a modular knowledge standard covering
sensory-stimulation techniques, modalities, stimulus parameters, exposure
boundaries, evidence claims, protocols, presets, and sessions. It comprises RDF
vocabularies, ontology modules, semantic infrastructure, validation profiles,
interoperability work, documentation, and shared identifiers. The long-term
vision is broader than any one representation technology.

The [living-reference vision](docs/concept/REFERENCE_VISION.md) describes that
direction and its boundaries. It is a project-level vision, not a ratified
Community Group charter or a claim to exclusive scientific authority.

**Contribute to the living reference:** [AI agents and humans are invited](https://w3c-cg.github.io/sstim/agents/)
to report inaccurate definitions, missing concepts, evidence conflicts,
implementation flaws and unmet research or technology needs. Reports should
identify sources, affected versions and reproducible observations. The
[feedback form](https://w3c-cg.github.io/sstim/contribute/) prepares a public
GitHub issue draft for review; no machine contribution changes canonical
SSTIM automatically.

The **SSTIM ecosystem** is broader than the standard itself. It includes SSTIM,
its reference tooling and community, and the wider field of sensory-stimulation
applications and initiatives whether they adopt SSTIM, contribute to it, support
it, or are related through documented domain relevance. This repository also
contains **SSTIM Workbench**, SSTIM's non-normative executable reference
environment; **Graph Navigator** and **Patch Studio** are Workbench components.

SSTIM is developed through the W3C Sensory Stimulation Vocabulary Community
Group. Historical development provenance is preserved in the repository
history. Community Group work is not a W3C Recommendation or W3C-endorsed
technology.

The work is non-clinical. It does not prescribe treatment, certify efficacy, or
claim that a protocol treats, prevents, cures, or diagnoses a condition. Start
with [Scope](docs/concept/SCOPE.md), [Non-Scope](docs/concept/NON_SCOPE.md), and
the [Evidence Framework](docs/concept/EVIDENCE_FRAMEWORK.md).

## Project Status

Version numbers, DOIs, module and term counts are **derived, not restated
here** — `make truth-audit` fails when prose disagrees with the sources:

| Fact | Source |
|---|---|
| Latest citable release, its version DOI, graph counts | [`void.ttl`](static/ontology/void.ttl) |
| Live development version, modules, profile closures | [`manifest.json`](static/ontology/manifest.json) |
| How to cite | [`CITATION.cff`](CITATION.cff) |
| What changed in each release | [`CHANGELOG.md`](CHANGELOG.md) |

- **Persistent namespace:** `https://w3id.org/sstim` is registered and live.
  All-version concept DOI:
  [10.5281/zenodo.21286974](https://doi.org/10.5281/zenodo.21286974).
- **Ontology shape:** manifest-owned Turtle modules behind four profile entry
  points — Kernel, Core, Core Plus, Full — plus VoID/DCAT and a JSON-LD context.
  Kernel is a shapeless discovery profile; Core, Core Plus, and Full are the
  conformance targets. The development line is mutable and not an immutable
  release; use the manifest and explicit profile entry points rather than
  treating `sstim-core.ttl` as the whole suite.
- **Public example data:** the BSC framework, nine framework techniques (three
  originated by BSC, six vendor-neutral ones it incorporates — ADR 0033), two
  implementations, protocols, reference presets, evidence assessments,
  knowledge-status assertions, exposure hypotheses and profiles, DOI-identified
  references, one explicitly synthetic session with pre/post reports, and one
  synthetic ecosystem contract graph. No real ecosystem-agent record ships here.
- **Validation:** SHACL Core and SHACL-SPARQL, HermiT via ROBOT, repository-wide
  semantic integrity checks, and executable SPARQL competency queries run under
  the pinned Nix toolchain.
- **External review:** the 2026-07-10
  [automated OOPS/FOOPS review](docs/ontology/reviews/2026-07-10-external-automated-review.md)
  is resolved, and the maintainer guided and accepted the ontology changes.
  Releases are accepted once the automated OWL, SHACL, quality, round-trip,
  runtime, and build gates pass; **independent human ontology review is not
  claimed.** The deployed canonical FOOPS score is 87.5%, with the remaining
  failures registry-dependent.
- **Registry discoverability:** the `sstim` prefix resolves at prefix.cc and the
  ontology is parsed and browsable in
  [BioPortal](https://bioportal.bioontology.org/ontologies/SSTIM), and it is
  catalogued in [BARTOC](https://bartoc.org/en/node/21154) (node 21154, entered
  by a BARTOC editor on 2026-07-27) and in
  [FAIRsharing](https://fairsharing.org/8494) (record 8494, curated 2026-08-06,
  DOI pending) and in
  [DBpedia Archivo](https://archivo.dbpedia.org/info?o=https://w3id.org/sstim),
  and listed in [LOV](https://lov.linkeddata.es/dataset/vocabs/sstim) since
  2026-09-28. Archivo's
  rating is frozen at the state of first submission — its updater has not run
  since February 2026, which is
  [reported upstream](https://github.com/dbpedia/archivo/issues/58) — so treat
  its star count as stale rather than current. Tracked in
  [registry submissions](docs/ontology/REGISTRY_SUBMISSIONS.md).
- **Web app:** ontology graph, SPARQL workbench, preset browser, Patch Studio
  with built-in Sensory Field starters, logbook, profile and settings are
  implemented as a static SvelteKit application, usable with no account;
  Firebase-backed sync is optional.

Browsers at the ontology IRI get the interactive application; reference
documentation is regenerated on every deploy (ADRs 0023 and 0043) —
[WIDOCO](https://w3c-cg.github.io/sstim/ontology/docs/) for the Full OWL profile and
[pyLODE](https://w3c-cg.github.io/sstim/ontology/docs/vocab/) for the SKOS
vocabulary. Real participant session data, the private BioSynCare catalog,
clinical protocols, and clinical claims are not published here.

## SSTIM Modules And Profiles

The live source set is manifest-driven. The
[`manifest.json`](static/ontology/manifest.json) file is the authoritative list
of modules, direct dependencies, runtime named graphs, checksums, and profile
closures. The main adoption choices are:

| Profile | Semantic closure | Validation |
|---|---|---|
| [Kernel](static/ontology/sstim-kernel-profile.ttl) | [`sstim-core.ttl`](static/ontology/sstim-core.ttl): the two process anchors | No published Kernel shapes |
| [Core](static/ontology/sstim-core-profile.ttl) | Kernel + engine-independent stimulus description | [`sstim-core-shapes.ttl`](static/ontology/sstim-core-shapes.ttl) |
| [Core Plus](static/ontology/sstim-core-plus-profile.ttl) | Core + reusable common descriptors and calibrated quantities | Core shapes; Common-specific shapes are deferred |
| [Full](static/ontology/sstim-full-profile.ttl) | All semantic, bridge, vocabulary, alignment, ecosystem, and Patch Studio modules | [`sstim-shapes.ttl`](static/ontology/sstim-shapes.ttl) |

**New here?** [Adopting SSTIM](docs/ADOPTING_SSTIM.md) walks the whole path in
about half an hour, without a checkout: pick a profile, fetch it pinned to a
release, copy a file from [`examples/`](examples/), change the namespace,
validate. It also states plainly what SSTIM does not do yet.

There are two clients with one API. Both resolve a profile closure from the
manifest, checksum-verify what they fetch, and check a file three ways:
conformance, containment, and namespace discipline.

- [`packages/sstim`](packages/sstim/), Python, on PyPI as
  [`sstim`](https://pypi.org/project/sstim/):
  `pip install sstim && sstim validate my.ttl --profile core`
- [`packages/sstim-js`](packages/sstim-js/), JavaScript, on npm as
  [`@sstim/core`](https://www.npmjs.com/package/@sstim/core):
  `npm install @sstim/core`. `rdf-validate-shacl` cannot evaluate `sh:sparql`,
  so Full-profile results are marked `PARTIAL` with the count skipped; Kernel,
  Core and Core Plus carry none.

Consumers that previously merged the eight pre-modular sources should select
the Full profile. New reusable integrations should start with Core or Core Plus and
add concern modules through their manifest-resolved dependency closure. Shapes
are selected separately from OWL imports. Core validation deliberately leaves
channels and targets optional, but hardens either link when it is present: a
channel object must be typed `sstim-ex:StimulusChannel`, and a stimulation
target must be an IRI or blank node rather than a literal.

Each entry point is also a W3C Profiles Vocabulary (`prof:Profile`) resource
with discoverable specification, constraints (where available), and manifest
artifacts. The manifest declares its schema by the persistent identifier
`https://w3id.org/sstim/manifest-schema/1` while it is mutable. A released
manifest points `$schema` at its frozen versioned sibling instead.

For the modular publication contract, machine-readable requests to
`https://w3id.org/sstim` return a generated catalog of the Full semantic
namespace, while `https://w3id.org/sstim/kernel` is the exact two-class Kernel
endpoint. `https://w3id.org/sstim/exposure` returns a generated Stimulus +
Exposure namespace catalog because the exposure namespace contains terms owned
by both modules. The exact Exposure semantic module and its mutable
distribution/import endpoint are instead
`https://w3id.org/sstim/module/exposure`; the live Full profile's `o