Quick Start
Getting started with DisclosureOS — the open standard for UAP evidence
Introduction
DisclosureOS is an open-source standard for structuring UAP evidence. It gives every tool and institution the same vocabulary for describing an observation, the same criteria for what makes it anomalous, the same taxonomy for what might explain it, and the same measures for how complete and compelling the case is.
The standard has five parts, each answering one question about an observation:
Records
What was observed? The shared data dictionary — time, place, object, witnesses, and sensor evidence.
Observables
What anomalous characteristics did it show? Detection criteria across the Technology and Biologics frameworks.
Origins
What might explain it? The Origin Classification System — a taxonomy of competing hypotheses.
Claims
Who assessed it, and on what evidence? Attributed claims, with evaluator disagreement preserved.
Scoring
How complete and compelling is the case? Multiple measures, not one reductive number.
Four of these ship as their own npm package; Claims is the attribution model that lives inside @disclosureos/records and threads through Observables and Origins. Two supporting packages complete the foundation:
Schema
The portable contract that binds the package-backed parts into one enriched, validated Observation — TypeScript and JSON Schema.
CLI
Scaffold, validate, and inspect observations from the command line.
Want the full picture first?
Read What is DisclosureOS? for the model, the architecture, and why an open standard matters.
Two starting paths
Author a new record
Start from scratch. The golden-path example below walks you through creating one observation, step by step.
Migrate existing data
Have a CSV, JSON export, or database rows? The onboarding workspace helps you map fields, validate output, and see what is missing.
Installation
npm install @disclosureos/records @disclosureos/observables @disclosureos/origins @disclosureos/scoring @disclosureos/schemaAll packages are ESM-only and require Node 20+. See the Installation guide for subpath imports and TypeScript configuration.
The golden path
One observation through every part of the standard — the USS Nimitz "Tic Tac" encounter (2004). This is the core workflow of the entire framework.
1. Records — describe what was observed
import { createObservation, createSensorReading } from '@disclosureos/records/factories';
import { evidenceRef } from '@disclosureos/records/shared';
// A sensor reading the claims below will cite as evidence.
const radar = createSensorReading('shipborne_radar', 'radar_phased_array', {
id: 'princeton-spy1-radar',
platform: 'USS Princeton (CG-59), AN/SPY-1 phased array',
operator: 'US Navy',
});
const RADAR = evidenceRef('sensor', radar.id);
const base = createObservation(
{
temporal: { date: '2004-11-14', dateCertainty: 'exact', durationSeconds: 300 },
location: { name: 'Pacific Ocean, ~100mi SW of San Diego', country: 'United States', latitude: 31.5, longitude: -117.5, siteType: 'ocean' },
summary: 'Tic-Tac-shaped craft tracked on radar and intercepted by F/A-18 pilots.',
objectCharacteristics: { shape: 'tic_tac', sizeMeters: 12, color: 'white', numberObserved: 1 },
witnesses: { count: 4, categories: ['military_pilot', 'radar_operator'], militaryWitnesses: true, multipleIndependent: true },
sensorEvidence: { sensors: [radar] },
},
{ id: 'nimitz-tic-tac-2004', status: 'published' },
);2. Observables — claim what was anomalous
Anomalies are recorded as claims: attributed, evidence-backed assertions. Multiple evaluators can claim the same observable — disagreement is first-class data.
import { createObservableClaim } from '@disclosureos/observables';
const observableAssessments = {
technology: {
instantaneous_acceleration: [
createObservableClaim('confirmed', {
confidence: 0.85,
rationale: 'Radar tracked descent from ~80,000 ft to sea level in seconds.',
evidenceRefs: [RADAR],
}),
],
},
};3. Origins — claim what might explain it
Origin hypotheses come from the Origin Classification System, a descriptive taxonomy of competing explanations. A claim can carry alternative hypotheses with their own confidence.
import { createOriginClaim } from '@disclosureos/origins';
const origin = [
createOriginClaim('1.1.3', 0.4, {
rationale: 'Performance exceeds known aerospace capability.',
alternativeHypotheses: [{ nodeId: '1.1.1.2.1', confidence: 0.25, label: 'Classified U.S. program' }],
evidenceRefs: [RADAR],
}),
];4. Claims — preserve who said what
The Observables and Origins examples above both produced claims. Claims are not a separate package; they are the shared attribution structure that records who made an assessment, why, and which evidence inside the record supports it. This is what lets two evaluators disagree without overwriting each other.
5. Schema — validate the enriched whole
parseEnrichedObservation validates the core record and every package-owned slot in one call, without stripping anything.
import { parseEnrichedObservation } from '@disclosureos/schema';
const observation = { ...base, observableAssessments, origin };
const parsed = parseEnrichedObservation(observation);
if (!parsed.success) {
console.error(parsed.issues); // [{ path, message }, ...]
}The strip hazard
Never validate an enriched record with ObservationSchema.parse() — Zod will silently drop the observableAssessments and origin slots. Always use parseEnrichedObservation. Read more in Type Safety & Validation.
6. Scoring — measure the case
import { getCompleteness, score } from '@disclosureos/scoring';
const completeness = getCompleteness(observation); // field coverage of the record
const compellingness = score(observation); // signal from claims + evidence
console.log(completeness.percentage); // e.g. 38
console.log(compellingness.score); // e.g. 0.71
console.log(compellingness.contested); // do evaluators disagree?Run the complete example from the monorepo:
pnpm --filter @disclosureos/examples golden-pathValidate from the command line
The CLI wraps the same validation pipeline:
npx @disclosureos/cli validate observation.jsonIt checks the core record, every package-owned slot, and warns on evidence references that don't resolve. See the CLI docs for scaffold, registry, and info.
FAQ
Learn more
Understanding the model
What is DisclosureOS?
The five parts, the package architecture, and why an open standard.
Tour of the API
The mental model: Observation, slots, claims, and validation.
The Companion Pattern
How constants, guards, factories, formatters, and labels work.
API Reference
Browse all types, properties, guards, and formatters interactively. This is the API reference, separate from the public Standard Explorer.