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 — a .odio document (JSON) — published by a manufacturer alongside a product's support documents lets design software import accurate device data instead of re-keying it from PDFs, and renders a standardized I/O table you can drop onto a spec sheet, embed on a product page, or view in the browser.

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.

Documents use the .odio file extension (the legacy .odio.json is still accepted) and the media type application/vnd.odio+json — the content is plain JSON, so every JSON tool still applies. The shape also allows optional network (a device's OSI layer / managed class for switches and routers) and, for modular chassis, frame slots and a card's card block (see Bundles, below).

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.

The same machinery models modular chassis: a frame is a device that declares its card slots, each card is a device with a card block stating which slot it fits, and a populated chassis is a bundle whose card components carry a slot assignment. validateChassis() checks that cards fit their slots (type, occupancy, power budget); the I/O table aggregates the frame's ports plus every populated card's, labeled by slot.

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. Status & roadmap

Shipped:

• Schema, SDK & adapters. The device, bundle, and cable schemas (plus modular-chassis slots/card and a device network OSI-layer class); @opendeviceio/sdk and @opendeviceio/adapters published on npm (generated types, an Ajv validator, bundle/chassis flattening + validation, and renderers).
• Registry & API. A free, searchable, downloadable library of thousands of device, bundle, and cable files, with a public REST API that also returns render-ready projections (the I/O table as JSON or SVG, and a host-agnostic draw program).
• The standardized I/O table. A deterministic projection of any file into a consistent table — rendered on registry pages, in the in-browser viewer, exportable as SVG/HTML for spec sheets.
• Tools & integrations. An in-browser authoring form (with gated publish for approved manufacturers), and AutoCAD / Visio import add-ins that draw a device's block straight into a drawing from the API.

Next:

• Manufacturer-published catalogs. Brands publish and verify their own devices (and each new product) via the authoring form, upload, or API — the Genie importer bootstraps a few large catalogs to seed adoption, not as an ongoing ingestion engine.
• AI-assisted design. The validated corpus + the generate→validate→repair loop (the SDK can check a proposed connection) make ODIO the ground truth for design assistants — starting with an MCP server over the registry.
• More layout integrations. An InDesign plugin to place the I/O table onto spec sheets, and a hosted convenience importer. The spec, SDK, and CLI stay open — only hosted convenience is ever monetized.