SSTIM

SSTIM is the open formalized knowledge standard for describing sensory-stimulation techniques, modalities, stimulus parameters, exposure boundaries, evidence claims, protocols, presets, and sessions. It comprises the specification, RDF vocabulary, semantic infrastructure, documentation, interoperability work, and shared identifiers.

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, Non-Scope, and the Evidence Framework.

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

• Persistent namespace: https://w3id.org/sstim is registered and live. All-version concept DOI: 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 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, and it is catalogued in BARTOC (node 21154, entered by a BARTOC editor on 2026-07-27) and in FAIRsharing (record 8494, curated 2026-08-06, DOI pending) and in DBpedia Archivo. A LOV submission is outstanding and its queue is slow but moving. Archivo's rating is frozen at the state of first submission — its updater has not run since February 2026, which is reported upstream — so treat its star count as stale rather than current. Tracked in registry submissions.
• 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 for the Full OWL profile and pyLODE for the SKOS vocabulary. Real participant session data, the private BioSynCare catalog, clinical protocols, and clinical claims are not published here.

The live source set is manifest-driven. The manifest.json file is the authoritative list of modules, direct dependencies, runtime named graphs, checksums, and profile closures. The main adoption choices are:

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 owl:imports uses that endpoint, never the namespace catalog. Its dct:requires may still identify the logical Exposure ontology as https://w3id.org/sstim/exposure. Release preparation replaces the mutable import endpoint with the exact immutable versioned sibling file. A development line's artifacts and routes stay staged until the Pages deployment and corresponding perma-id update; they are never citable release endpoints.

Every module is an owl:Ontology with creator, publisher, dates, license, description, version metadata, and explicit ownership. Controlled values remain dual-typed OWL individuals and SKOS concepts. See the module architecture, ontology source guide, and ADR index.

The first screen is the working application, not a marketing site. Its main surfaces are:

• Graph Navigator: Cytoscape graph navigation over named RDF graphs.
• SPARQL workbench: Comunica queries over ontology and public instance data.
• Presets: SSTIM Workbench reference presets, their preserved BSC Lab implementation identifiers, and their evidence links.
• Patch Studio: real-time audio/visual authoring with Web Audio, AudioWorklet/WASM options, modulation, photosensitivity safeguards, and first-class colour-field and stereoscopic scene tracks. Its built-in Sensory Field starters create ordinary Studio tracks for colour/audio, depth markers, trees, abstractions, and landscapes; the former /field/* URLs are history-replacing compatibility redirects, not another application screen. The SHACL-tested legacy exposure mapper remains a golden path while unified Studio exposure export is completed.
• Logbook, annotations, patches and profile: kept in your browser by default, with no account required. Signing in (when Firebase is configured) keeps them with your account instead so they follow you between devices.

Ecosystem architecture is maintained in the Workbench's /ecosystem/ page. Software architecture details are in src/README.md, Patch Studio, and the Session Model.

SSTIM Workbench builds as a static SvelteKit application. Graph Navigator, SPARQL workbench, Patch Studio, legacy Field redirects and reference data all operate client-side, so the core application is hostable on any static file server. Firebase is optional: configuration comes from build-time VITE_FIREBASE_* variables, and a build without them produces a working instance with no embedded credentials. Only sign-in becomes unavailable — annotations, saved patches, the logbook and the profile are kept on the device instead of an account.

The pinned Nix flake reproduces the development, build and validation toolchain, and CI runs inside it. nix build (or make package) additionally produces the static site as an immutable, bit-reproducible package at result/share/bsc-lab, a compatibility path retained from the imported baseline, servable by any static web server — nix build --rebuild yields an identical output, and nix flake check builds it.

That same package deploys three ways from one source: a NixOS module (nixosModules.default) that configures a hardened nginx with the required MIME types and headers, an OCI container image (nix build .#oci) running unprivileged, and any plain static host. All three are held to a single deployment-conformance contract, scripts/smoke-http.sh, exercised in CI against both a NixOS VM and the container.

Local user data is fully portable: a versioned instance export covers patches, annotations, logbook, profile and skin with SHA-256 integrity, and make migrate-test proves it across two genuinely separate origins — export from instance A, import into instance B, re-export, byte-identical.

The package is configured at deployment, not at build: a runtime-config.json beside the site names the instance and selects identity and storage providers, so one byte-identical artifact serves many operators. The NixOS module generates it from services.bsc-lab.settings; the container takes it as a read-only mount. Absence changes nothing, and invalid configuration degrades to local-only and says why in Settings.

Every build publishes build-info.json naming the commit it came from, and CI fetches it back from the deployed URL after publishing — so "the live site is the commit we built" is checked rather than assumed.

The identity and storage seams both exist, with conformance suites (ADR 0038). What remains open is a private cross-device sync service, and a second real identity provider to prove the seam is an interface rather than a swap (ADR 0039).

Every commit is also verified as a credential-free static deployment: make smoke-static rebuilds with no Firebase configuration, serves the result over plain HTTP, and asserts that all primary routes, the ontology Turtle and the PWA assets are served, that an unknown path 404s, and that no API key was inlined.

Existing portability foundations:

• versioned, checksum-verified ontology releases (ADR 0020);
• JSON-LD and RDF/XML ontology export via make export;
• RDF serialization of annotations with authentication identifiers excluded;
• the portable patch-studio-model-3 representation, with explicit import of genuine model-1 and model-2 documents;
• separation of public reference data, per-user annotation graphs and private records.

The next portability layer — reproducible institutional deployment, explicit service adapters, complete export/import packages and independently tested migration between instances — is specified with acceptance criteria in Portable Deployment and Migration.

The canonical environment is the pinned Nix flake:

nix develop
npm ci
make dev

The default development URL is http://127.0.0.1:4173. direnv allow can load the dev shell automatically. Without Nix, provide compatible Node 24, Python 3.12 with rdflib and pyshacl, ROBOT/HermiT, WABT, and GNU Make yourself.

Firebase is optional and the application is fully usable without it — annotating, saving patches, the logbook and the profile all work on-device. Copy .env.example to .env and provide the VITE_FIREBASE_* values only when testing sign-in or account-backed sync.

Run the same gates used by CI:

make validate   # SHACL + audit + HermiT + SPARQL + serialization round trips
make test       # Vitest unit tests
make check      # SvelteKit sync and svelte-check
make build      # Static production bundle in dist/
make export     # JSON-LD and RDF/XML serializations of manifest-owned sources

make validate checks more than RDF syntax:

1. SHACL validates the applicable profile and Full closures plus all public instances; Core uses its deliberately weaker profile shapes.
2. The manifest contract checks the module dependency DAG, profile closures, source metadata, runtime/publication mappings, and file checksums.
3. scripts/sstim-quality-audit.py checks JSON-LD context and loader completeness, SKOS integrity, local IRI resolution, evidence provenance, and competency thresholds.
4. ROBOT with HermiT checks OWL DL consistency across the module set, and the normalized Full-union parity gate checks the live redistribution against the frozen pre-modular baseline.
5. Comunica runs named-graph competency queries for delivery media, protocol chains, evidence trails, actionable cautions, and phase-qualified reports.
6. Generated JSON-LD and RDF/XML are parsed back and checked for graph isomorphism with each Turtle source module.
7. make truth-audit checks the prose: no superseded version, development line or DOI advertised as current, no shipped capability described as future work, and every relative link in every tracked document resolves.
8. make release-dryrun rehearses the next release against the current sources, so a gate that has been wrong for weeks surfaces before a release, not during.

Each frozen static/ontology/<version>/ snapshot is immutable and is not edited after publication. Future releases are cut only after validation, version metadata, snapshot generation, tag creation, and Zenodo archival agree. The release gate additionally requires every snapshotted artifact to advertise its immutable versioned URL, every profile to import the exact versioned sibling closure, every PROF descriptor to identify immutable entrypoint, constraint, and manifest artifacts. Every profile has a positive fixture and competency query; profiles with a nonempty SHACL closure additionally have nonempty out-of-scope and adversarial fixtures. The released manifest and schema are themselves frozen sibling artifacts. make release-dryrun rehearses all of this against the current sources on every make validate, so a gate that has been wrong for weeks surfaces before a release is attempted rather than during one.

CLAUDE.md                 Repository invariants and agent instructions
README.md                 Project status and entry point
ROADMAP.md / TODO.md      Strategic phases and tracked work
docs/
  concept/                Domain definition, scope, non-scope, evidence policy
  technical/              Preset, session, engine, safety, and UI specifications
  ontology/               Ontology review and publication planning
  decisions/              Architecture decision records
  ecosystem/              W3C proposal, governance, identifiers, and outreach
static/
  ontology/               Live modules, context, VoID, frozen releases, instances
  worklets/               AudioWorklet processors and oscillator WASM
  audio/                  Synthetic CC0 reference audio
src/
  rdf/                    N3 loader, named graphs, queries, and validation
  engines/                Audio implementation and planned engine boundaries
  ui/                     Knowledge browser, Patch Studio, field, safety, account UI
  routes/                 SvelteKit application routes
scripts/                  Export, snapshot, semantic audit, and competency tooling
.github/workflows/        RDF validation, app checks, and Pages deployment

The full documentation map is docs/README.md.

• https://w3id.org/sstim# - reusable suite terms owned across semantic modules.
• https://w3id.org/sstim/vocab# - controlled vocabulary concepts.
• https://w3id.org/sstim/exposure# - exposure identifiers owned across the Stimulus and Exposure modules.
• https://w3id.org/sstim/framework/bsc - the BSC framework.
• https://w3id.org/sstim/implementation/bsclab/ - public BSC Lab data.
• https://w3id.org/sstim/implementation/biosyncare/ - reserved public-safe BioSynCare implementation metadata, not its private catalog.
• https://w3id.org/sstim/ref/ - reusable public-safe references.

Ontology terms, public reference data, user annotations, and session records belong in separate named graphs. The repository includes only a clearly marked synthetic session fixture; real user records remain user-owned and are not committed.

The former BSC Lab public application is now presented as SSTIM Workbench. This branding change does not rename the real BSC framework, BSC Lab implementation records, protocols, provenance, persistent instance IRIs, storage formats, or historical releases represented in SSTIM.

BioSynCare remains a separate closed-source commercial application. It adopts and contributes to SSTIM, participates in the SSTIM ecosystem, and is the center of its own overlapping application ecosystem; this does not make it the identity or owner of SSTIM. Versioned exports and SSTIM mappings are the intended interoperability boundary; this repository does not contain BioSynCare's private data or application code.

This is a work repository of the W3C Sensory Stimulation Vocabulary Community Group. Its work covers shared terms, semantic models, JSON-LD contexts, SHACL profiles, safety metadata, evidence annotations, and implementation guidance. It does not define clinical practice or certify products, and Community Group work is not a W3C Standard.

• Charter — the live instrument
• Original proposal — the submitted text, kept as a record
• Ontology publication plan
• Contributing

The most useful thing an outside contributor can do right now needs a language and domain sense, not knowledge of this repository.

Review the translations. SSTIM publishes in English, Italian, Portuguese and Spanish, and as of 2026-08-19 all 551 concepts carry all four — but 282 of those labels were written by the maintainers and have had no native review. If you speak one of these languages and know the domain, reading a scheme and saying which terms a practitioner would not actually use is the most valuable thing you can do here. These are controlled-vocabulary labels, so the bar is idiomatic usage, not a defensible rendering. make language-coverage verifies coverage; it cannot verify that a translation is good.

Propose a term. If SSTIM is missing a concept you need, open a term proposal. Grep docs/ontology/TERM_INDEX.md first — it is generated from the 18 modules and CI-checked, and 18 modules is more than anyone searches reliably by hand. A proposal does not require a pull request; describing the gap and the evidence is the contribution.

Before a pull request, read CONTRIBUTING.md and CLAUDE.md — the latter carries the invariants that are expensive to violate, including that ontology files under static/ontology/ are not modified without explicit instruction. make validate is the gate CI runs.

To cite a specific release, use CITATION.cff — it names the current immutable version and version DOI, and GitHub renders it as Cite this repository. Use the concept DOI when referring to SSTIM across releases.

• Imported software: Apache License 2.0.
• Synthetic reference audio: CC0 1.0 Universal.
• Imported ontology, vocabulary, documentation, and public reference data: CC BY 4.0.
• W3C Community Group contribution terms: LICENSE.md. These artifact-specific terms do not retroactively relicense imported history.
• Complete path, artifact, and contribution scope: LICENSING.md.
• Maintainer: Renato Fabbri, ORCID 0000-0002-9699-629X.