SSTIM

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

Project Status

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, and listed in LOV 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 — 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.

SSTIM Modules And Profiles

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:

New here? Adopting SSTIM 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/, 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, Python, on PyPI as sstim: pip install sstim && sstim validate my.ttl --profile core
• packages/sstim-js, JavaScript, on npm as @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 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.

SSTIM MCP: installable reference for AI agents

Published: @sstim/mcp@0.3.0, official MCP Registry identity io.github.w3c-cg/sstim (canonical OIDC registration). The local stdio MCP adapter exposes four read-only knowledge tools: list released versions, search concepts, retrieve exact terms with definitions/ mappings/provenance, and prepare a human-reviewed feedback link. Since 0.3.0 it can also draft contribution proposals and read the public contribution issues; it opens a public GitHub issue only when its operator enables submission and approves the exact text. It consults the release-pinned Concept Reference API; it never mutates the ontology. No source checkout, login or API key is required to run the published package with Node.js 20+.

Quick installation, VS Code + Copilot Agent (.vscode/mcp.json):

{
  "servers": {
    "sstim": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@sstim/mcp@0.3.0"]
    }
  }
}

For Codex use [mcp_servers.sstim] with command = "npx" and args = ["--yes", "@sstim/mcp@0.3.0"]. Installation instructions for Codex, Claude Code, Gemini CLI, Cursor and Neovim include the appropriate client-specific configuration.

Try asking your agent: “Use SSTIM to find the canonical terminology for binaural beats, retrieve each relevant term's source and provenance, and propose a mapping for my session JSON without inventing any ontology IRIs.”

Stewardship: SSTIM W3C Community Group (primary author/project); with thanks to BioSynCare for support and contributions. Community Group publication is not a W3C Recommendation or formal endorsement. Distribution and public directories.

SSTIM Workbench

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.

Deployment And Portability

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.

Quick Start

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.

Verification

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.

Repository Map

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.

Identifiers And Data Boundaries

• 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.

Preserved BSC provenance and BioSynCare

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.

W3C Community Group

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

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's controlled vocabulary is published in English, Italian, Portuguese and Spanish: as of 2026-10-08 all 556 concepts carry all four, but 294 of those labels (282 measured on 2026-08-19, and twelve added since for ADR 0061) were written by the maintainers and have had no native review. Class and property labels are in English. 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.

Citation And License

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.