Create your first record

An observation can start as an incomplete record. You do not need to invent a time, position or measurement to make it valid. This tutorial creates a fictional draft with those gaps recorded explicitly.

You need: Node.js 22 and npm. The example uses JavaScript, runs locally and requires no account. It uses the published @disclosureos/records package at 2.0.0-beta.4.

Try it before installing: open the document inspector and choose Check document. A fictional source-backed example is already loaded. Nothing is uploaded or published.

1. Install one package

In a new directory, run:

mkdir disclosureos-first-record
cd disclosureos-first-record
npm init -y
npm install --save-exact @disclosureos/records@2.0.0-beta.4

Use the exact version here. The packages are ESM; the .mjs extension in the next step lets Node run the file without additional configuration. Other packages can be added when you need them.

2. Create an observation

Save this as first-record.mjs:

import { parseExperimentalObservation } from "@disclosureos/records/experimental/v2";

const observation = {
  kind: "observation",
  schemaVersion: "0.1.0",
  id: "first-observation",
  status: "draft",
  createdAt: "2026-10-16T00:00:00Z",
  updatedAt: "2026-10-16T00:00:00Z",
  eventTime: { state: "unknown", reason: "not_recorded" },
  position: { state: "unknown", reason: "not_collected" },
  sources: [],
  products: [],
  methods: [],
  frames: [],
  assertions: [],
  measurements: [],
  processing: [],
};

const result = parseExperimentalObservation(observation);
console.log(
  JSON.stringify({ success: result.success, checks: result.checks }, null, 2),
);

createdAt and updatedAt describe the record, not when the event occurred. The event time and position remain unknown. The empty lists make this a starting draft with no sources or measurements yet.

The document's schemaVersion is 0.1.0. It is separate from the 2.0.0-beta.4 package version. The /experimental/v2 import path is intentional for this beta.

3. Run the check

node first-record.mjs

You should see:

{
  "success": true,
  "checks": {
    "structural": "passed",
    "semantic": "passed",
    "profile": "not_checked",
    "external": "not_checked"
  }
}

What passed: the document has a valid structure and its local relationships satisfy the parser's rules. The empty lists are allowed. This result does not mean the record is complete, accurate or ready for scientific analysis. Profile-specific and external checks have not run.

4. Inspect an error

Change status: "draft" to status: "finished" and run the file again. finished is not an allowed status. You should get success: false, a failed structural check and dependent checks left not_checked.

To inspect the explanation, add this after the existing console.log:

console.log(result.issues);

The diagnostic identifies the invalid field. Restore status: "draft" to return to the passing draft. In your application, inspect diagnostics and check states before using a parsed document.

Add a source next

You have now run the parser on both a valid draft and an invalid document. The next useful step is a record with an actual source relationship.

• Add a source to your record: use the example case's station log, save an observation and diagnose a broken reference.
• Follow a complete synthetic measurement: continue into instrument context, measured values and binding checks.
• Look up a field: inspect the full nested structure and allowed values.

To build a viewer, run the showcase. It includes a working interface and fictional source files. The supporting guides use the same Beta 4 release for the more detailed record and sensor examples.