Whitepaper · v0.1.0

OpenDeviceIO: a portable contract for hardware device I/O

OpenDeviceIO (ODIO) is an open, machine-readable format for describing the input/output, power, physical, and compliance characteristics of a hardware device. One file, published by a manufacturer alongside a product's support documents, lets design software import accurate device data instead of re-keying it from PDFs.

1. Motivation

AV and control-systems designers — and the CAD tools they use (AVCAD, D-Tools SI, XTEN-AV, Stardraw, and others) — have no universal, machine-readable source of truth for a device's connectors, signals, power, and control. That data lives in PDF spec sheets and is re-keyed by hand into every tool's product database, with errors, duplication, and drift.

ODIO's goal is one file = one device, accurate enough to draw with: a design tool should be able to render the back panel, count and label connectors, route signals, and total power and heat load directly from the file. It is designed to be easy for manufacturers to produce (ideally auto-drafted from existing spec sheets, then human-reviewed) and easy for software vendors to consume (a stable core schema, strong validation, a typed SDK).

Explicit non-goals for v1: modeling internal DSP/signal routing, being a pricing/availability catalog (ODIO links out instead), carrying real-time state, or replacing control protocols such as Dante, NDI, or Q-SYS — ODIO references them.

2. The data model

An ODIO document is a single JSON object with this top-level shape:

device document
{
  "$schema": "https://opendeviceio.org/schema/v0.1/device.schema.json",
  "odioVersion": "0.1.0",        // format version (semver)
  "id": "extron/dtp2-t-211@a",   // stable, lowercase, URL-safe identifier
  "device":     { /* identity & classification */ },
  "ports":      [ /* the core: I/O ports */ ],
  "power":      { /* power inputs, consumption, heat */ },
  "physical":   { /* dimensions, weight, rack units, mounting */ },
  "standards":  [ /* compliance & interop standards */ ],
  "parameters": { /* free-form parametric data */ },
  "provenance": { /* where this data came from, validation status */ }
  // x-* keys permitted at any object level for vendor extensions
}

manufacturer and model are required. The id is derived as slug(manufacturer)/slug(model)[@slug(revision)] and is the join key tools and the registry use. The JSON Schema is the single source of truth: the TypeScript SDK types are generated from it, and the normative prose is written to match it.

3. The three-layer port model

A port is one externally accessible connector (or a group of identical ones). The model cleanly separates three concerns so that one physical connector can carry multiple concurrent logical flows:

• Connector — the physical jack only (rj45, xlr-3-f, hdmi-type-a, phoenix). The physical poleCount lives here.
• Link — the physical pipe the connector provides: the type (ethernet, usb, hdmi, fiber…), its standard/speed/bandwidthGbps, and link-level facts such as a PoE budget or USB Power Delivery wattage — stated once per port.
• Signals — one or more concurrent flows, each in a domain (video, audio, control, network, data, power) with a transport and domain-specific attributes.

This is why one RJ45 can carry Dante + AES67 + general LAN at once, and why the physical pole count (poleCount) stays independent of the number of logical signal circuits (signal.channels) — the difference between a 3-pole Phoenix RS-232 port and an 8-pole Phoenix GPIO header.

4. Bundles & cables

Many products are kits: one orderable part number that contains several devices, often with factory-terminated cables and mounting hardware. ODIO models these with two additional document kinds, discriminated by a top-level kind field (device documents have no kind):

• Bundle (kind: "bundle") — a kit identity plus a components[] list. Each component is a device, a nested sub-assembly (another bundle), a cable, or a non-I/O accessory, inline or referenced by id. A design tool expands the kit into separate device blocks while billing them under one part number.
• Cable (kind: "cable") — a first-class object with typed ends (each an ODIO connector + optional gender), the signals it carries(reusing the device signal model), lengthMeters, and a factoryTerminated flag. Cables are both BOM line items and the edges between devices on a schematic.

The SDK's flattenBundle() expands a bundle's tree into leaf devices, cables, and accessories with effective quantities, and bundleBillOfMaterials() produces a flat BOM — exactly what the registry detail page renders for a kit.

5. Provenance & trust

Provenance is what makes the format trustworthy. Every document records how it was produced (generator, method), the source documents it was derived from, and a validation status:

• draft — produced (often by the Genie importer) but not yet reviewed.
• reviewed — checked by a human against the source documents.
• manufacturer-verified — confirmed by the manufacturer; the highest-trust tier.

Genie drafts also carry a confidence block listing low-confidence fields so a reviewer knows exactly what to check. A consumer can always tell a hand-keyed draft from a manufacturer-verified file.

6. Extensibility & versioning

ODIO is a closed core with an open edge. The core schema forbids unknown non-extension keys (additionalProperties: false) so drift is caught rather than silently accepted — but any object may carry keys matching ^x- (e.g. x-dtools, x-avcad), which validators MUST ignore. Vendor-specific needs live under x- namespaces, never in the core.

odioVersion is semver: MINOR releases add optional fields and grow the connector/standard/category vocabularies; MAJOR releases may change required fields or semantics. The $schema URL is versioned (/schema/v0.1/…), and an other + free-text escape hatch means a missing vocabulary term never blocks a valid file.

7. Governance & licensing

ODIO is an open standard governed in the open. Changes are proposed as short RFCs in pull requests, with semver discipline and a documented vocabulary-addition process. The format favors no single design tool; neutrality is a design constraint.

• Code & JSON Schema: Apache-2.0, with an explicit patent grant — important for a standard that vendors build commercial products on.
• Specification & documentation: Creative Commons Attribution 4.0 (CC BY 4.0) — vendors may quote and embed it.

A file is conformant to ODIO 0.1 if and only if it validates, under JSON Schema draft 2020-12, against the schema for its kind. There are no conformance requirements beyond schema validation; the schema is authoritative.

8. Roadmap

• Canonical schema & SDK (done). The device, bundle, and cable schemas; the @opendeviceio/sdk(generated types, an Ajv validator, and accessors); and adapters that expand ODIO into design-tool formats.
• This website & registry (now). Canonical schema hosting at the versioned URLs, the whitepaper and authoring guide, and a free, searchable, downloadable registry of device, bundle, and cable files — which also resolves bundle references and settles the id-authority question.
• Corpus growth. Ingesting full manufacturer catalogs via the Genie pipeline with human review, prioritizing manufacturer-verified entries (highest trust and best training data).
• Hosted Genie (later, paid). A convenience import service (spec sheet → draft .odio.json). The spec, SDK, and CLI stay open; only the hosted convenience is monetized — never the standard.