Equipment and captures

An acquisition context describes how instrument data was captured. It holds the equipment, configuration revisions, deployment, calibration declarations, recording sessions and output files. The observation holds the measured values; bindings connect those values to their captures.

This guide starts with a populated synthetic capture from the complete measurement example. You will validate it, follow its identifiers and diagnose a broken product-to-capture link. The fixture represents a one-minute background recording from a fictional station. It is not partner data or a demonstrated sensor calibration.

Requirements: Node.js 22. Create a project and install the published instruments beta:

mkdir equipment-example
cd equipment-example
npm init -y
npm install --save-exact @disclosureos/instruments@2.0.0-beta.4

This walkthrough uses acquisition context 0.1.0. Its schema version is separate from the npm package version. Sensor profiles add checks for specific recording formats; this walkthrough starts with the shared capture document.

1. Start with a populated capture

Download the capture document and save it as context.json in your project. Keep its identifiers and source declarations unchanged for the walkthrough. The example README identifies the original source revision and license.

The document contains one item in each of six inventories:

An instrument is not a recording. A configuration can be reused across deployments and captures; each capture has its own timing and output products. A channel belongs to a configuration revision, rather than being a globally unique sensor ID.

2. Validate and save

Save this script as capture.mjs beside context.json. It reads the document, checks its structure and local relationships, and saves the parsed result only when the check succeeds.

import { readFileSync, writeFileSync } from "node:fs";
import { parseAcquisitionContext } from "@disclosureos/instruments/experimental/v2";

const context = JSON.parse(readFileSync("context.json", "utf8"));
if (process.argv.includes("--break-capture-link")) {
  context.products[0].acquisitionRef = "acquisition:missing-capture";
}

const result = parseAcquisitionContext(context);
console.log(
  JSON.stringify(
    {
      success: result.success,
      checks: result.checks,
      uncheckedArtifactPointers: result.uncheckedArtifactPointers,
    },
    null,
    2,
  ),
);
if (!result.success) {
  console.error(JSON.stringify(result.issues, null, 2));
  process.exitCode = 1;
} else {
  writeFileSync("checked-context.json", JSON.stringify(result.data, null, 2) + "\n");
  console.log("Saved checked-context.json");
}

Run it from your project directory:

node capture.mjs

You should see this result, followed by Saved checked-context.json:

{
  "success": true,
  "checks": {
    "structural": "passed",
    "semantic": "passed",
    "profile": "not_checked",
    "external": "not_checked"
  },
  "uncheckedArtifactPointers": [
    "/manifests/0/artifact",
    "/calibrations/0/report/artifact",
    "/products/0/artifact"
  ]
}

The parser has checked the document shape and local relationships. It has not opened the configuration file, calibration report or raw recording. uncheckedArtifactPointers identifies those declarations by their location in the JSON. It is not a list of downloaded files.

success: true means this parse succeeded. The unchecked profile and external stages remain explicit. It does not mean the equipment was authenticated, the calibration approved or the recorded values independently verified.

3. Try a broken capture link

Run the same script with its failure flag:

node capture.mjs --break-capture-link

The script changes the product's capture reference in memory to acquisition:missing-capture. It leaves the downloaded file untouched. The shape still passes, but success becomes false, semantic becomes failed, and the script exits with status 1. It prints this issue:

[
  {
    "code": "REF.LOCAL_RESOLUTION",
    "stage": "semantic",
    "severity": "error",
    "pointer": "/products/0/acquisitionRef",
    "message": "Undeclared pinned reference: acquisition:missing-capture"
  }
]

The pointer leads to the broken link: the first product names a capture that does not exist in acquisitions. An existing checked-context.json is not overwritten on failure, so its presence alone does not prove the latest run passed. Run without the flag to validate the original document again.

Follow the configuration and channel

The raw product points to acquisition:a1. Capture a1 points to instrument:station, pins manifest:r1 and deployment:d1, and activates the radar channel with calibration:c1.

These are local references, not URLs. IDs must resolve to the appropriate inventory; a matching display name is insufficient. The parser also checks relationships such as whether an active channel is in its pinned manifest and whether its calibration covers that channel.

A manifest's version describes the configuration revision. When hardware, firmware or channels change, preserve the earlier manifest and create a new revision. Keep older captures linked to the revision used at the time.

Map your own capture

Begin with one representative recording and the metadata supplied with it. Use the example's structure, then replace its fictional declarations with your own. Do not retain its sample clock precision, calibration or timestamps as defaults.

• Identify the equipment and the configuration used. identity and the hardware and firmware declarations have explicit unknown alternatives when that information is missing.
• Declare each channel's quantity, unit and sampling information. Do not infer a sample rate from the viewer's playback speed.
• Record the deployment and capture period separately. A deployment can span several captures. The observation's event time is a third, distinct declaration.
• Attach the active channel and its calibration state. A missing calibration is not the same as an unreviewed calibration report.
• Identify each retained raw product. Compute its byte length and digest from the actual file, not a filename or an expected value. Reformatting a file changes its bytes and can change its digest.

The six inventory arrays are required, but the parser permits empty inventories. An empty document can pass a structural check without describing any usable recording. Populate the relationships your integration needs and keep missing declarations explicit using the alternatives in the field reference.

Keep timing and calibration qualified

Capture time, clock source, synchronization, resolution and uncertainty are separate declarations. Preserve the provider's time scale and known or unknown state. Do not invent an instant from a filename or assume that two channels share a clock because a viewer displays them together.

The synthetic fixture deliberately declares zero clock uncertainty. That is an authored test value, not a general claim of perfect timing. The parser checks the declaration; it does not estimate clock error or establish cross-sensor synchronization.

Calibration records retain the method and version, validity period, report metadata, stated uncertainty and review state. A pinned calibration means the capture names that record. It does not establish that the procedure was executed correctly or that a reviewer accepted it. Matching a report's digest establishes a byte match, not the quality of its calibration.

Connect the capture to a measured value

Acquisition context is a separate document from the observation. Acquisition bindings link an observation's instrument source and raw product to this context. Measurement bindings identify the captured channel and explicit measurement time supporting a measured value.

The shared field reference has three document choices: Equipment & captures, Source & product links, and Measurement links. Each has scoped search, nested constraints and direct field links. Use Connect measurements for the mapping rules and evaluator limits.

To check the related source files as well, continue with the complete measurement example. Its download includes the original context used here, the other three documents and the exact artifact bytes. It specifies its own package version. The evaluator checks the required bytes you supply; it does not fetch remote URLs, decode arbitrary telemetry or prove the scientific meaning of a measurement.

Continue exploring

• Instruments overview: choose among the shared acquisition model, binding workflow and optional sensor profiles.
• Instruments standard page: inspect the recording examples and see how a viewer can present these relationships.
• Field recordings in the research desk: see the full fictional case's connected recordings. Its captures are distinct from this small validation fixture.

For a partner integration, request one native recording with its configuration, channel definitions and clock and calibration declarations before scaling to the archive. The ELDÆON preview includes supplied native files and an explicit source inventory. Reproduce one electric-field reading to follow a source row into the standard. Clock alignment, calibration and several channel definitions remain unresolved; an intake receipt is not a complete acquisition mapping.

The acquisition JSON Schema export is @disclosureos/instruments/experimental/v2/acquisition/schema. Its identifier, urn:disclosureos:experimental:acquisition-context:0.1.0, names the contract rather than a downloadable HTTP endpoint.