DisclosureOS documentation · v2 Beta
Use observable terms
Name a reported or measured characteristic, retain its definition, and connect it to an attributed review.
Observables provide shared terms for characteristics that a report describes or an investigation examines. They do not replace the report, its measurements or a reviewer's assessment. An account can prompt a question even when no instrument data is available.
Choose a term before making a connection
Read the full definition and its qualifications. Then decide whether you are indexing a related question or declaring the exact characteristic that a reviewer assessed. Those are different relationships.
Six technology terms and six biologics terms. These groups organize research questions; they do not establish an origin.
Keep the three roles separate
Original accounts, source files, measured quantities and the conditions of capture.
A shared definition, identified by its catalog, immutable revision and exact term ID.
A stated question, subject, supporting inputs, method, outcome and attribution.
The example below connects a review of physical acceleration to Abrupt Motion. That term also covers apparent changes in motion. Recorded angles and a report of a rapid rise can make the term relevant without establishing physical acceleration. The retained review is inconclusive; the term itself has no outcome.
Start with an observation record and the claim history it supports. Add equipment and measurement links when instruments are involved. The vocabulary connection is a separate companion document, so its term does not become the claim's subject or supporting source.
Before you run
These APIs are published in Beta 4. You need Node.js 22 and npm. Create a project, or reuse the one from the other vocabulary guide:
mkdir disclosureos-vocabulary
cd disclosureos-vocabulary
npm init -y
npm install --save-exact @disclosureos/schema@2.0.0-beta.4 @disclosureos/observables@2.0.0-beta.4 @disclosureos/origins@2.0.0-beta.4Keep the terminal in this project. The package version, catalog revision and document schema version identify different things.
1. Load the example documents
Download the checker and five documents from the fictional DisclosureOS example case. Its source files use the name Meridian. The checker selects the existing angular-motion connection; it does not author a new assessment or change the retained files.
mkdir -p examples/observables-guide
for file in vocabulary-bindings.json observable-catalog.json history.json entities.json observation.json; do
curl --fail --location \
"https://os.disclosure.org/examples/meridian/vocabulary-v1/$file" \
--output "examples/observables-guide/$file"
done
curl --fail --location \
https://os.disclosure.org/examples/v2/observables/check-observables.mjs \
--output check-observables.mjs| Document | Role |
|---|---|
observable-catalog.json | The twelve definitions and their exact revision. |
vocabulary-bindings.json | Attributed connections between catalog terms and claims. |
history.json | The review, its subject, outcome, method and source references. |
entities.json | Source editions and entities required by that history. |
observation.json | The observation snapshot required by the entity document. |
The complete packet includes other observable and origin connections. This walkthrough selects one about binding, so it does not need the origin catalog. A check of a selected subset says nothing about declarations outside that subset.
2. Resolve the connection
node check-observables.mjs examples/observables-guideThe downloadable checker imports evaluateVocabularyBindings from @disclosureos/schema/experimental/v2, reads local files and maps each document's SHA-256 to its original bytes. It calls:
const result = await evaluateVocabularyBindings(bindings, { documents });Catalog identifiers and artifact URLs are not fetched. Supply the exact history dependencies as well as the catalog and history. Parse and inspect documents as needed, but retain their original bytes: reserializing equivalent JSON can change its digest.
The first report is:
{
"success": true,
"checks": {
"structural": "passed",
"semantic": "passed",
"profile": "passed",
"external": "not_checked"
},
"scientificValidity": "not_checked",
"authenticity": "not_checked",
"unresolvedReferences": [],
"issues": []
}Only after success does the runner display the resolved term:
{
"relation": "about",
"termId": "abrupt_motion",
"label": "Abrupt Motion"
}Inspect this question and its sources in the showcase.
Interpret the result
| Check | What it establishes |
|---|---|
structural | The supplied binding documents have the required shape. |
semantic | Local rules, such as valid times and unique connection IDs, pass. |
profile | Required snapshots, term membership, attribution and relationships resolve consistently. |
external | Remains not_checked. The evaluator does not fetch or authenticate outside sources. |
Read success, checks.profile, issues and unresolvedReferences together. Missing bytes leave the profile unchecked; supplied contradictory bytes or identities fail it. A known failure takes precedence over other unresolved inputs. Success requires all three applicable checks to pass.
A passing connection does not validate the catalog's science, reproduce a sensor analysis, authenticate a publisher or establish that a characteristic occurred. scientificValidity and authenticity remain not_checked; domain-profile checks also remain unchecked. JSON Schema validates structure, the vocabulary parsers add local rules, and the evaluator resolves documents and relationships.
Connecting a term to a claim
Use the binding's term to identify the definition and its claim to identify the review. The field reference exposes all three objects: catalog snapshot, term reference and claim connections.
Exact connection used by this example
{
"id": "angular-motion",
"recordedAt": "2026-10-13T12:00:00Z",
"assignedBy": "Meridian vocabulary review team (fictional)",
"rationale": "Index this specific research question under the relevant characteristic. This association is not an assessment that every aspect of the broader term is present or absent.",
"claim": {
"document": {
"documentId": "meridian-vocabulary-history-v1",
"schemaId": "urn:disclosureos:experimental:claim-history:0.4.0",
"sha256": "e940582da8325dd6f3d684f66afa6e32bba64efdf177712805849e395ff1a3e3"
},
"claimId": "angular-motion"
},
"relation": "about",
"term": {
"catalogId": "https://os.disclosure.org/vocabularies/observable-characteristics",
"revision": "2026-10-13.1",
"document": {
"documentId": "disclosureos-observables-v2",
"schemaId": "urn:disclosureos:experimental:vocabulary-catalog:0.1.0",
"sha256": "d3ee1987e75cacbc213ec3e3c64393a40169c7cb179b1fe87d5a903f2fc53182"
},
"termId": "abrupt_motion"
}
}| Reference field | What to retain |
|---|---|
catalogId | The authority-qualified vocabulary identity, as an exact string. |
revision | An immutable publication identifier. latest is rejected. |
document.documentId | ID inside the retained catalog document. |
document.schemaId | Its exact schema identifier, including the version. |
document.sha256 | SHA-256 of the retained document bytes. |
termId | Exact term ID, such as abrupt_motion, rather than its label or code. |
The binding also retains assignedBy, recordedAt and rationale. Its recorded time cannot precede the target claim's recorded time. A history's free-text topic does not establish catalog membership.
Choose the relationship
| Relationship | Use it when | Required boundary |
|---|---|---|
about | A statement or review concerns a term. | This is an attributed indexing choice. It does not declare occurrence or imply that the original source used the term. |
assessment_criterion | The reviewer assesses the exact defined characteristic. | The target must be an assessed claim, and assignedBy must exactly match its evaluatedBy. |
This example uses about because its acceleration question is narrower than the complete Abrupt Motion definition. Do not convert it to assessment_criterion just to make the connection look stronger.
One claim can have several about associations, but only one distinct assessment criterion across supplied companion documents. Independent assessments of different characteristics need separate claims. When an assessed claim supersedes another, criterion continuity requires the same complete term reference along the affected chain. A new question needs a separate assessment.
Pass other selected companion documents through additionalBindings when checking them together. The evaluator cannot detect conflicting declarations withheld from the supplied set; your publisher must also preserve catalog revisions across submissions.
3. Diagnose an unresolved or failed connection
Use one flag at a time. These exercises change only in-memory inputs. A non-passing result exits with status 1 and stops before term output; unsupported arguments exit with status 2. Rerun without a flag to recover the original passing result.
Withhold the catalog
node check-observables.mjs examples/observables-guide \
--missing-catalogStructure and local semantics still pass, but profile becomes not_checked and the catalog reference appears in unresolvedReferences. The issue code is SNAPSHOT.UNAVAILABLE, with status not_checked: a missing input is not a demonstrated contradiction. Do not render a resolved term or silently substitute a newer catalog.
Change the retained bytes
node check-observables.mjs examples/observables-guide \
--changed-catalogThe checker appends one space to the in-memory catalog bytes without changing the reference digest. The JSON remains readable, but exact-byte verification fails. The issue code is SNAPSHOT.DIGEST. Matching parsed values cannot substitute for matching retained bytes.
Select a nonexistent term
node check-observables.mjs examples/observables-guide \
--unknown-termThe exact catalog resolves, but it does not contain not_in_this_catalog. The profile fails with VOCABULARY.TERM. A plausible label or a term in a different catalog revision cannot repair that reference.
Read the definitions
The term reference includes each definition, scientific context, qualifications, detection signals, suggested methods and references. These are catalog guidance, not tests reported as completed in a case.
For application code, ALL_OBSERVABLES in @disclosureos/observables exposes the current package definitions. createObservableCatalog creates a snapshot from them, with your declared document ID, revision, publisher and publication time. It does not publish or authenticate that snapshot. Retain its bytes and use a new revision for changed content.
The shared catalog envelope stores observable-specific metadata in namespaced extensions. Use readObservableTermDefinition to validate and read that metadata; it returns undefined when metadata is unavailable or malformed. Do not assume that an arbitrary custom catalog term is an observable definition. The shared evaluator preserves extensions without validating their domain meaning.
Definition boundaries
A report, measured quantity and interpretation remain separate even when they use the same term. Apparent hover does not identify propulsion. An isotope-ratio departure needs a stated comparison and does not determine origin. An unresolved sequence does not establish non-terrestrial biology.
Retain the qualifications with the definition in your interface. Show a review outcome only where a review exists. In this packet, two observable questions have inconclusive reviews; the other ten terms have no assessment. Later instrument demonstrations are separate captures and cannot fill those reviews' source gaps.
Observable levels and claim outcomes
Two APIs use different vocabularies. Do not convert between them automatically:
| API | Values describe |
|---|---|
ObservableClaim.level | Declared support for a characteristic: not_indicated, reported, documented, measured, confirmed. |
An assessed claim's outcome | The reviewer's result for a stated question: reported, confirmed, absent, inconclusive. |
Support levels
| Level | Declared meaning |
|---|---|
not_indicated | Nothing in the record indicates the characteristic is present. |
reported | Testimony or a claim without supporting documentation. |
documented | Written records, photographs or other contemporaneous documentation exist. |
measured | Quantitative instrument data captured the relevant signal. |
confirmed | Independent verification through peer review or replication. |
These are authored declarations, not levels assigned by a validator. A measured signal does not establish an anomalous capability. Optional confidence remains separate. An omitted assessment is not not_indicated, and an inconclusive review is not absent.
The example uses a claim history and makes no ObservableClaim.level declaration. The score function rejects nonempty descriptive observable assessments rather than treating these support levels as anomaly strength. See claim shapes before choosing an assessment representation.
Follow the example reviews
Run the showcase vocabulary packet to inspect all five observable and origin reviews, their methods, exact source citations and validation receipt. The two observable questions address physical acceleration and comparable cross-sensor detection. Neither has a confirmed outcome.
Full catalog
Search the complete term reference →
For implementation details at this source revision, read the canonical vocabulary guide and definition review. Continue to Claims to author the review itself.