Review possible origins

Origins supplies a vocabulary for possible explanations. A catalog entry names a hypothesis. A claim records what a reviewer concluded about it, for a stated subject and set of inputs. Selecting an entry does not identify the cause of an observation.

Keep definition, review and outcome separate

Observables names characteristics; Origins names possible explanations. A reported characteristic does not establish an origin. Both use the same vocabulary fields to connect a definition to a claim. No second origin-specific binding format is needed.

The example below asks whether viewing conditions or an optical effect explain a reported light. It selects Optical Artifact / Illusion as the review's criterion. Its retained outcome is inconclusive, not a confirmation or exclusion of that explanation.

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

Keep the terminal in this project. The package version, catalog revision and document schema version identify different things.

1. Load the example documents

These documents come from the fictional DisclosureOS example case. Its retained filenames use Meridian. The checker selects the existing optical-explanation connection; it does not create or change a review.

mkdir -p examples/origins-guide
for file in vocabulary-bindings.json origin-catalog.json history.json entities.json observation.json; do
  curl --fail --location \
    "https://os.disclosure.org/examples/meridian/vocabulary-v1/$file" \
    --output "examples/origins-guide/$file"
done
curl --fail --location \
  https://os.disclosure.org/examples/v2/origins/check-origins.mjs \
  --output check-origins.mjs

The packet uses archival claim history 0.4.0 because its inputs include edition references. The introductory Claims guide uses base history 0.1.0. Supply the contract required by your subjects and inputs; changing a version label does not convert a document.

The checker supplies only one origin binding. The observable catalog is unnecessary for this selection. A passing subset does not validate the packet's other connections.

2. Resolve the selected explanation

node check-origins.mjs examples/origins-guide

The downloadable checker imports evaluateVocabularyBindings from @disclosureos/schema/experimental/v2. It maps each local document's SHA-256 to its original bytes, then calls:

const result = await evaluateVocabularyBindings(bindings, { documents });

The evaluator does not fetch catalog URLs or artifact locations. Preserve original bytes rather than serializing parsed JSON again; equivalent JSON can have a different digest.

{
  "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 checker display the resolved connection:

{
  "relation": "assessment_criterion",
  "termId": "1.1.1.1.1",
  "label": "Optical Artifact / Illusion",
  "claimId": "optical-explanation"
}

Read this review and its sources in the showcase.

Connect an explanation to a review

The term identifies a definition. The claim's subject identifies what is being reviewed, and its input references identify the supporting material. Keep all three roles separate.

{
  "id": "optical-explanation",
  "recordedAt": "2026-10-13T12:00:00Z",
  "assignedBy": "Meridian vocabulary review team (fictional)",
  "rationale": "Declare the exact origin hypothesis addressed by this assessment; inclusion does not establish the proposed explanation.",
  "claim": {
    "document": {
      "documentId": "meridian-vocabulary-history-v1",
      "schemaId": "urn:disclosureos:experimental:claim-history:0.4.0",
      "sha256": "e940582da8325dd6f3d684f66afa6e32bba64efdf177712805849e395ff1a3e3"
    },
    "claimId": "optical-explanation"
  },
  "relation": "assessment_criterion",
  "term": {
    "catalogId": "https://os.disclosure.org/vocabularies/origin-hypotheses",
    "revision": "2026-10-13.1",
    "document": {
      "documentId": "disclosureos-origins-v2",
      "schemaId": "urn:disclosureos:experimental:vocabulary-catalog:0.1.0",
      "sha256": "e44bd2b61dd5fdbc3b807b2fa2df613498c93e7be0d873dbb8b1ff63db38921a"
    },
    "termId": "1.1.1.1.1"
  }
}

Index a related question

Use about for an attributed association with a term. It helps readers find a related question without declaring that the original speaker used this terminology.

Declare the assessed explanation

Use assessment_criterion for the exact hypothesis assessed by a reviewer. The claim must be assessed, and the binding's assignedBy must exactly match its evaluatedBy.

This example uses assessment_criterion because the question assesses that specific explanation. The matching identity strings are declarations, not proof of who performed the review.

A claim can have several about associations but only one distinct assessment criterion across the supplied binding documents. Different hypotheses need separate claims. Competing reviewers can retain separate reviews of the same term without either becoming authoritative. If an assessed claim replaces another, criterion continuity requires the same complete term reference along the affected revision chain.

Use additionalBindings to check other companion documents together. The evaluator cannot detect declarations you withhold. Your publisher must also preserve catalog revisions across submissions; a valid digest does not prevent an authority from incorrectly reusing a revision elsewhere.

3. Diagnose missing or contradictory inputs

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 or combined flags exit with status 2. Running again without a flag restores the passing result without changing files.

Withhold the catalog

node check-origins.mjs examples/origins-guide \
  --missing-catalog

Structure and local semantics pass, but profile becomes not_checked. The catalog appears in unresolvedReferences, with SNAPSHOT.UNAVAILABLE. Missing bytes are not a contradiction, and a newer catalog is not a substitute.

Change the catalog bytes

node check-origins.mjs examples/origins-guide \
  --changed-catalog

The checker appends one space without changing the declared digest. JSON parsing still works; exact-byte verification fails with SNAPSHOT.DIGEST and profile: failed.

Change who assigned the criterion

node check-origins.mjs examples/origins-guide \
  --changed-evaluator

The assigned reviewer no longer matches the claim's evaluator. Structure and local semantics pass, but the profile fails with VOCABULARY.CRITERION_ATTRIBUTION. A third party can make an attributed about association; it cannot declare an assessment criterion on someone else's behalf. This exercise does not alter the existing claim or its outcome.

What validation establishes

Read success, the individual stages, issues and unresolvedReferences together. Known contradictions take precedence over missing inputs. A successful connection needs all three applicable stages to pass.

This check does not run the review's method, verify that a hypothesis fits the source material, validate the scientific meaning of a definition or authenticate the author. Scientific validity and authenticity remain not_checked. The complete showcase packet has separate source-byte and edition checks; this walkthrough does not reproduce all of those checks.

Read the catalog

The package exports OCS_TAXONOMY and OCS_PROVENANCE. Each node retains the fields below; the term reference lets you inspect every entry.

Use getNode, getAncestors, getChildren and getSiblings to navigate the package's definitions. Use explicit relationships rather than splitting a dotted identifier or inferring hierarchy from its label.

createOriginCatalog wraps the definitions in the shared vocabulary catalog with your document ID, immutable revision, publisher and publication time. It preserves OCS provenance in extensions.org.disclosureos.origins. It does not publish or authenticate the snapshot.

For a retained catalog, use readOriginTermDefinition to read a term's OCS metadata. It returns undefined when that metadata is missing or malformed. This shape check does not prove a custom catalog's full tree is reciprocal, complete or free of cycles. The shared vocabulary evaluator does not validate OCS extension semantics. The portal separately checks its retained snapshot against the complete canonical catalog.

The shared catalog, term-reference and binding fields apply to both Origins and Observables. There is one shared field reference, with the OCS-specific fields described here.

Hierarchy and scope

Physical, Psychosocial and Metaphysical are organizing families, not a decision tree for selecting a cause. A result for one entry is not inherited by its parent, children or siblings. An inconclusive optical review does not increase support for an extraterrestrial explanation.

Read each entry's own scientificallyTestable value. A true value is a framework designation, not an operational test, scientific consensus, proof of feasibility or a completed investigation. A false value is not a negative case finding. Broad groups can contain entries with different designations; do not infer a value from an ancestor.

The OCS adapts Col. Karl Nell's Proposed Taxonomy of UAP Origin Hypotheses, presented at the Sol Foundation Symposium, Stanford University, in November 2023. Retain this attribution and the definitions' limits. The public Origins page explains the framework for a general audience.

Follow the example reviews

The retained packet contains three origin assessments, all inconclusive:

These are summaries of the questions; the showcase retains their exact wording and reasoning. The private/commercial review does not assess every human-source branch or identify an operator. All three omit confidence. Their outcomes are not equal probabilities, a ranking or support for the 93 other catalog entries. Later instrument demonstrations are separate captures and cannot fill these reviews' measurement gaps.

Run the complete vocabulary packet to inspect those reviews, source citations and the retained validation receipt.

Confidence and other classification APIs

OriginClaim is a separate package API for an evaluator's primary hypothesis, required confidence and optional alternatives. It is not the claim-history format used in this guide and does not carry this immutable catalog reference. Do not assign a primary hypothesis or invent a confidence value to represent an unresolved review.

createOriginClaim checks node membership and confidence ranges. createConfidenceDistribution checks known nodes, rejects a total above one (allowing a small floating-point tolerance), and assigns the remainder to unresolved. These checks do not establish calibrated probabilities or make overlapping OCS categories mutually exclusive. Schema parsing alone does not perform the factory's sum check. Do not automatically convert review outcomes into numerical weights.

The example uses attributed claim histories and makes no OriginClaim or confidence-distribution declaration. Continue to Scoring & checks for the distinction between evaluations and recorded validation.

Full catalog

Search the complete term reference →

Read the pinned vocabulary implementation guide and origin package source for the full API.