# DisclosureOS

> DisclosureOS is the open-source data standard for Unidentified Anomalous Phenomena
> (UAP) — "the Stripe of UAP data." One enriched `Observation` means the same thing in
> TypeScript, JSON Schema, and any other language. It is a five-part standard built on a
> shared `records` vocabulary, published as a small set of `@disclosureos/*` npm packages
> (ESM-only, Zod 4, Standard Schema v1, JSON Schema draft 2020-12).

The standard answers five questions about an observation:

- **Records** — *what was observed?* (the core unit every layer builds on)
- **Observables** — *what anomalous characteristics did it show?*
- **Origins** — *what might explain it?*
- **Claims** — *who assessed it, why, and on what evidence?* (shared attribution model inside `records`)
- **Scoring** — *how complete / compelling is the case?*

Observables and Origins augment the `Observation` type with package-owned slots;
Claims provide the shared attribution structure inside those slots; `@disclosureos/schema`
composes the full shape into one portable contract (TS type + JSON Schema + non-stripping parse).

## Packages

- [@disclosureos/records](packages/disclosureos-records/README.md): The data dictionary — the `Observation` core and shared primitives (confidence, attribution, claims, validation, JSON-Schema helpers).
- [@disclosureos/observables](packages/disclosureos-observables/README.md): Anomaly-detection criteria (Technology + Biologics); adds the `observableAssessments` slot.
- [@disclosureos/origins](packages/disclosureos-origins/README.md): The Origin Classification System (OCS) taxonomy; adds the `origin` slot.
- [@disclosureos/scoring](packages/disclosureos-scoring/README.md): Reference completeness and compellingness scoring; consumes the foundation, adds no slot.
- [@disclosureos/schema](packages/disclosureos-schema/README.md): The portable contract — `composeObservationSchema()`, `ExtensionRegistry`, and the non-stripping `parseEnrichedObservation` + `EnrichedObservation` type.
- [@disclosureos/cli](packages/disclosureos-cli/README.md): Dev tooling — scaffold, validate, and inspect observations from the command line (`validate` uses `@disclosureos/schema`).
- [@disclosureos/examples](examples/README.md): Private, not published — the runnable, type-checked golden path that exercises every layer.

## Schemas

Committed, versioned JSON Schema (draft 2020-12), `$id`-hosted at `os.disclosure.org`:

- [Observation (records)](https://os.disclosure.org/schema/records/1.0.0/observation.json): The open core record.
- [Observable assessments (observables)](https://os.disclosure.org/schema/observables/2.0.0/observable-assessments.json): The `observableAssessments` slot.
- [Origin classification (origins)](https://os.disclosure.org/schema/origins/2.0.0/origin-classification.json): The `origin` slot.
- [Scoring](https://os.disclosure.org/schema/scoring/2.0.0/scoring.json): Score and completeness results.
- [Enriched observation (composed)](https://os.disclosure.org/schema/schema/1.0.0/enriched-observation.json): Records core + every registered slot, root tightened to reject unknown top-level keys.

## Concepts

- [Glossary](docs/disclosureos-glossary.md): Precise definitions for the terms newcomers conflate — Attribution vs Claim vs Assessment; `confidence` (0–1, per claim) vs `ConfidenceLevel` (enum, records fields) vs `SourceCredibility` (the source); `alternativeHypotheses` (intra-claim) vs `contested` (inter-claim).

> **Strip hazard (read this first).** A raw `ObservationSchema.parse(record)` silently drops the satellite slots (`observableAssessments`, `origin`). To validate an enriched record without losing slots, use `parseEnrichedObservation` from `@disclosureos/schema` (or `validateObservation` for core-only checks). Never use a raw `.parse()` round-trip to "clean" an enriched record.

## Getting started

- [Golden path example](examples/golden-path.ts): One observation through every part — records → observables → origins → claims → scoring, validated as a whole by `@disclosureos/schema` — in a single type-checked file. Run with `pnpm --filter @disclosureos/examples golden-path`.
- [Migration path example](examples/migration-path.ts): Convert source JSON rows to validated Observations — date precision, guarded enums, quarantine, validation, and completeness scoring. Run with `pnpm --filter @disclosureos/examples migration-path`.
- [CSV migration example](examples/migration-csv-path.ts): Same workflow but starting from a real CSV file parsed with `csv-parse`. Run with `pnpm --filter @disclosureos/examples migration-csv-path`.

## Bringing your own dataset

The [onboarding workspace](https://os.disclosure.org/onboard) is the guided entry point for dataset owners. It covers the full migration loop: audit source data, map fields, validate output, check completeness, and iterate.

Key resources:
- [Data Migration guide](https://os.disclosure.org/docs/platform/guides/data-migration): Step-by-step migration workflow.
- [Field Mapping Reference](https://os.disclosure.org/docs/platform/guides/field-mapping-reference): Common source columns and their Observation targets.
- CLI `validate`: `npx @disclosureos/cli validate ./out --recursive --json`
- CLI `completeness`: `npx @disclosureos/cli completeness ./out --recursive --json`