Dataset onboarding

Inspect your record

Start with one JSON record. Check its format locally, explore the available fields, and keep a copy of the results. For CSV, database exports, or large sensor archives, use the migration guide and local command-line tools.

30 legacy fields|226 legacy coverage paths|Migration guide

Audit your source data

Understand which fields are always present, how dates are encoded, whether coordinates are real GPS fixes, and what the source's own id scheme is.

Migration guide

Write a row mapper

One function from your source row to an Observation. Guard every enum boundary, use stable source-prefixed ids, and carry the raw row in extensions.

Mapper pattern

Validate your output

Run validation on the generated JSON files. Use --json for scripted workflows and CI.

npx @disclosureos/cli validate ./out --recursive

Inspect field coverage

Inspect field presence. Not every field applies to every record, and presence alone does not establish research readiness.

npx @disclosureos/cli completeness ./out --recursive

Fix and iterate

Update your mapper, re-export, re-validate. Quarantine failures instead of dropping them. Do not fabricate observable or origin claims from keywords.

Fix loop

Runnable examples

Three complete, type-checked examples you can run locally:

pnpm --filter @disclosureos/examples golden-path

Explore the legacy authoring APIs. Illustrative claims are not a verified research case.

pnpm --filter @disclosureos/examples migration-path

Convert three source rows, quarantine failures, validate, and score completeness.

pnpm --filter @disclosureos/examples migration-csv-path

Parse CSV rows, guard empty strings, map fields, and run the same validation loop.

Document format

Legacy recordExperimental observationExperimental claim history

Choose the format your document uses. Changing this selection preserves your input and clears the previous result; it does not convert the document.

Your record stays in this browser

Check one JSON record locally, up to 256 KB. Choose the document format above. Legacy checks include field coverage; experimental checks include structure and internal consistency. Supporting references, scientific validity, source authenticity, and readiness for publication are not verified.

Open JSON file

Paste one JSON document

The example is fictional. Do not substitute its date or coordinates for unknown values in your own data.

Search by field name, description, type, enum value, or “required” to find where your source columns map.

Identity & Anchors

The required spine of every record: what it is, when and where it happened, and its lifecycle.

idstringrequired
Stable unique identifier for this observation.
When an observation occurred — a sortable anchor date plus optional fuzzy/range/relative nuance.
Where an observation occurred — identity, coordinates, site classification, and proximity context.
Lifecycle/publication state of an observation record.
createdAtstringrequired
ISO timestamp when the record was created.
updatedAtstringrequired
ISO timestamp when the record was last updated.

Descriptive

What was reported, in plain terms — the narrative, the object, the source, and any investigation.

summarystring
One-or-two sentence summary of the observation.
descriptionstring
Full narrative account of the observation.
Physical description of the observed object(s).
eventTypestring
Local event-type tag (e.g. "multi-sensor military encounter"). The word "classification" is reserved for the origin taxonomy in @disclosureos/origins; this is just a free-text descriptor.
Where the observation data came from. Forensic custody/authenticity now lives in the optional `Observation.provenance` slot (@disclosureos/records/extensions/provenance).
Official/independent investigation of the observation.

Detailed Domains

Structured depth for cases that have it: flight behavior, witnesses, sensors, effects, and context.

How the object moved — kinematics and notable maneuvers.
Aggregate summary of who witnessed the observation.
Instrument-recorded evidence for an observation (radar, FLIR, EO, etc.).
Official, media, and public response to the observation.
Environmental and weather conditions at the time of observation.
Typed links to related observations, plus flap/wave/cluster groupings.
Aviation context when the observation involved aircraft.

Media

Attached photos, videos, audio, and documents — the record’s exhibit list.

A media file associated with an observation (image, video, document, or audio).
A media file associated with an observation (image, video, document, or audio).

Forensic Extensions

Deeper ground for the hardest questions: chain of custody, sworn testimony, physical evidence, and cross-references.

Forensic provenance for an observation: custody status/chain and digital authenticity.
External identifiers cross-referencing this observation, with an optional primary.
A single witness statement, its context, and supporting documentation.
A physical artifact associated with an observation and its handling record.
Provenance metadata for a source document (classification, agency, redaction).

Metadata & Extensions

Versioning, data-source bookkeeping, and the extensions area where third parties attach their own data.

dataSourceIdstring
Identifier of the dataset or pipeline this record came from.
schemaVersionstring
Version of the records schema this record was authored against.
extensionsmap
Third-party extension bag for slots not owned by a first-party package.
internalNotesstring
Private working notes for maintainers — not part of the public record.