datasheet-schema

A machine-readable JSON Schema for electronic-component datasheet specifications. Each value records the test conditions under which it holds and a reference to its source in the datasheet. Existing standards omit both.

Purpose

A datasheet is a PDF. A specified value has meaning only in the context of the table row and column that qualify it. Parametric databases and distributor APIs store a bare value such as "V_OUT = 3.3 V" and discard the conditions that qualify it, for example "at I_OUT = 1 mA, T_J = 25 C, V_IN = 4.3 V". Classification dictionaries such as IEC 61360 and eCl@ss standardize property names and units but provide no field for a test condition. Simulation formats such as IBIS and SPICE carry conditions but describe device behavior rather than the guaranteed datasheet table.

No open standard represents a datasheet value together with its test conditions and a reference to its source. This schema does.

Comparison

A parametric database stores:

{ "vout": 3.3, "dropout": 0.28, "iq": 0.0000315 }

This is not sufficient to design from. The load current at which dropout equals 0.28 V is unspecified, as is whether 3.3 V is a minimum, typical, or maximum, and no absolute-maximum input rating is present.

datasheet-schema stores:

{
  "key": "dropout_voltage",
  "measurements": [
    { "limitClass": "characterized",
      "value": { "typ": 0.135 }, "unit": "V",
      "conditions": [ { "param": "I_OUT", "value": 0.1, "unit": "A" },
                      { "param": "T_J",  "value": 25,  "unit": "degC" } ],
      "conditionsVerbatim": "IOUT = 100 mA, TJ = 25C",
      "sourcePage": 5, "sourceTable": "Electrical Characteristics" },
    { "limitClass": "characterized",
      "value": { "typ": 0.28, "max": 0.45 }, "unit": "V",
      "conditions": [ { "param": "I_OUT", "value": 0.2, "unit": "A" } ],
      "conditionsVerbatim": "IOUT = 200 mA", "sourcePage": 5 }
  ]
}

A consumer can now determine that dropout is 135 mV at 100 mA and up to 450 mV at 200 mA, that the value is a characterized specification rather than an absolute maximum, and can locate it on page 5 of the source document.

Model

The schema has three elements.

1. Measurement. Every value is an object of value (with min, typ, nom, max), unit, conditions, and provenance fields. The conditions field is a first-class, typed list of axes.
2. limitClass. One of absolute_max, recommended, or characterized. A single field replaces the separate datasheet tables and records whether a value is a stress limit, an operating range, or a guaranteed characteristic. A consumer must not treat an absolute-maximum value as an operating value.
3. Envelope and dictionaries. The parameter shape is family-agnostic. A family dictionary supplies the canonical keys, units, and vendor aliases, so that psrr, ripple rejection, and power supply ripple rejection map to one key. Twenty-one families are included, spanning the active devices — an LDO regulator, a switching (DC-DC) regulator, a discrete power MOSFET, a JFET, a bipolar junction transistor, a diode (rectifier / Schottky / Zener / TVS), a precision voltage reference, an operational amplifier, a comparator, an analog switch, an analog-to-digital converter, and a digital-to-analog converter — the passives an analog board is built from — a capacitor, a resistor, and an inductor — the timing references that clock it, a passive quartz crystal and the packaged active oscillator that contains one (XO, TCXO, VCXO, and OCXO, in quartz and MEMS) — and the optoelectronic devices, both the emitters (a light-emitting diode across visible, infrared, and ultraviolet; a laser diode across Fabry-Perot, DFB, VCSEL, and high-power) and the detector that receives their light (a photodiode across PIN, avalanche, silicon-photomultiplier, InGaAs, and position-sensing) — and the optocoupler that combines an emitter and a detector across a galvanic-isolation barrier (phototransistor, high-speed logic, gate-drive, linear, and photo-triac-driver outputs). All share one measurement envelope, condition model, and provenance record. A pin function is likewise an open uppercase vocabulary, so the same pinout structure carries a regulator's IN, OUT, GND, a field-effect transistor's G, D, S, a bipolar transistor's BASE, COLLECTOR, EMITTER, a diode's, LED's, or photodiode's ANODE, CATHODE, a laser diode's LD_ANODE, LD_CATHODE with its PD_ANODE, PD_CATHODE monitor, an op-amp's IN_P, IN_N, VS_POS, VS_NEG, a non-polar passive's T1, T2, and a crystal's XTAL1, XTAL2. Adding a family requires only a new dictionary, not a schema change.

The schema reuses established vocabulary, including IEC 61360 level roles, an Octopart-style identity envelope, and base-SI units. It adds the conditioned value and provenance that those sources omit.

Quickstart

Copy the schema. It is self-contained, with no external references.

schema/datasheet-1.0.schema.json

Validate a document with any JSON Schema 2020-12 validator.

npx ajv-cli validate -s schema/datasheet-1.0.schema.json -d my-part.datasheet.json --spec=draft2020

Install from npm to get the TypeScript types and the schema object from one import.

npm i datasheet-schema

import { datasheetSchema, ldoDictionary, mosfetDictionary, dictionaries } from 'datasheet-schema';
import type { Datasheet } from 'datasheet-schema';

The bindings are deliberately dumb: they re-export the schema and family dictionaries as data (and, for TypeScript, the generated types). They contain no validator — validate with any JSON Schema library plus the family checks in CONFORMANCE.md. A separate Python data binding in bindings/python exposes the same JSON:

from datasheet_schema import DATASHEET_SCHEMA, DICTIONARIES, SCHEMA_VERSION

Reference the hosted, versioned URL from a $ref.

https://nkorai.github.io/datasheet-schema/schema/datasheet-1.0.schema.json

The examples/ directory holds validated documents across all twenty-one families: real LDO regulators (including a negative current-reference part), silicon and GaN MOSFETs, three real voltage references (a shunt and two series parts), op-amps (a precision audio part and a femtoampere electrometer with its guard buffer), switching regulators (a monolithic synchronous buck, a wide-Vin external-FET buck controller, and an isolated primary-side-sensing flyback controller), diodes (a standard rectifier, a Zener, and a TVS), bipolar transistors (a small-signal NPN, a Darlington, and an RF part), and — for the passives and remaining active devices — an aluminum-electrolytic capacitor, a thick-film resistor, a power inductor, a JFET, a high-speed comparator, a precision analog switch, four ADCs (a 24-bit delta-sigma with its 2-D noise table, a 20-bit precision SAR, a 1-GSPS RF-sampling converter, and a 24-bit stereo audio ADC), and four DACs (a 20-bit precision part exercising glitch impulse in volt-seconds, a 16-bit multiplying current-output part, a 1.25-GSPS RF current-steering part, and a 32-bit stereo audio DAC), four quartz crystals (a 32.768 kHz tuning fork exercising the parabolic turnover coefficient in ppm/°C², a 20 MHz AT-cut SMD with an eight-test environmental frequency-shift array, a 40 MHz through-hole 3rd-overtone series-resonant part, and a 24 MHz RF-reference crystal with its recommended-vs-absolute-max drive split), and five LEDs spanning both optical domains (a 5 mm red indicator in candela, an OSLON white lighting LED exercising lumens, efficacy and color temperature, a 940 nm infrared emitter in watts-per-steradian, a 365 nm UV-A emitter, and a 3-in-1 RGB part whose per-die values are keyed by an emitter-color condition axis), and five laser diodes (a 980 nm Fabry-Perot with its monitor photodiode and slope efficiency in watts-per-amp, a 1550 nm DFB exercising kilohertz linewidth and wavelength current-tuning in metres-per-amp, an 850 nm 25-Gbit/s datacom VCSEL, a 30 W fiber-coupled pump module, and a 7 W blue single-emitter), and five photodiodes (a silicon PIN with its responsivity-vs-wavelength curve in amperes-per-watt, an InGaAs telecom detector, a silicon avalanche photodiode with its gain and excess-noise k-factor, a silicon photomultiplier with photon-detection-efficiency and dark-count-rate, and a two-dimensional position-sensitive detector), and five optocouplers spanning every output architecture (a Vishay 4N35 phototransistor with its base pin brought out, a Vishay 6N137 10-Mbaud open-drain logic gate exercising the |CMH|/|CML| common-mode transient immunity arrayed by output state, a Broadcom ACNW3190 reinforced-isolation IGBT gate driver carrying the full IEC 60747-5-5 safety block — working/transient/partial-discharge voltages, creepage and clearance in metres, and safety-limiting current/power/temperature — a Vishay IL300 linear coupler whose servo-photodiode transfer gain K3 = K2/K1 is a dimensionless ratio, and an onsemi MOC3021M random-phase photo-triac driver whose static dv/dt is a characterized curve-only value), and five oscillators spanning every sub-type (a SiTime SiT8008 MEMS simple XO, a SiTime SiT5356 MEMS Super-TCXO whose ppb-scale stability, aging over five windows, phase noise arrayed over carrier offset, and Allan deviation over averaging time exercise the family's normalization, a Connor-Winfield V514 quartz LVDS VCXO with its pull range and tuning block, a Connor-Winfield OH300 Stratum-3E OCXO with its oven warm-up power and time, and an Epson SG3225EEN quartz LV-PECL clock with femtosecond phase jitter arrayed over carrier frequency).

Contents

| Section | Description | |---|---| | component | Identity and ordering variants. | | pinout | Pins with normalized functions, so tools bind by function rather than vendor pin name. | | parameters | All specified values (absolute maximum, recommended, electrical, thermal, ESD), distinguished by limitClass. | | provenance | SHA-256 of the source PDF, revision, page, extraction method, and verified flag. |

Families

A dictionary defines the canonical parameter keys, units, and vendor aliases for one component family. The schema stays family-agnostic. A validator checks each document's keys against the dictionary named by its component.family.

| Family | Dictionary | Parameters | |---|---|---| | ldo | dictionary/ldo-1.0.json | 62, including dual-rail, soft-start/noise-reduction, and current-reference (LT304x) parameters. | | mosfet | dictionary/mosfet-1.0.json | 45, covering silicon, SiC, and GaN power FETs (transconductance, output/switching charge, effective Coss, switching energy) as well as small-signal parts. | | voltage_reference | dictionary/voltage_reference-1.0.json | 41, unifying series and shunt topologies, adjustable references, and temperature-sensor and heater sub-blocks. | | op_amp | dictionary/op_amp-1.0.json | 59, synthesized from a 20-datasheet corpus spanning general-purpose, precision/zero-drift, ultra-low-noise, high-speed voltage- and current-feedback, and femtoampere electrometer parts. | | dc_dc | dictionary/dc_dc-1.0.json | 92, from a 20-datasheet corpus covering monolithic buck/boost/buck-boost converters, external-FET controllers (peak-current or pull-up/pull-down-resistance gate drive), an integrated-inductor power module, and isolated primary-side-sensing flyback controllers (no VOUT pin — output inferred from the flyback pulse via an RFB/RREF ratio and the transformer turns ratio), under one envelope selected by sub-type. | | diode | dictionary/diode-1.0.json | 39, spanning standard and fast rectifiers, silicon and SiC Schottky, small-signal switching diodes, Zener diodes (with the two-point ZZT/ZZK impedance), and transient-voltage suppressors (standoff, clamping over peak-pulse-current, peak-pulse-power over a waveform axis). | | bjt | dictionary/bjt-1.0.json | 55, spanning small-signal, power, Darlington (integral resistor network + clamp diode), RF/high-frequency (gain, noise figure, output power via dBm→W), fast switching, and digital bias-resistor transistors, with component.polarity carrying NPN (positive) vs PNP (negative). | | capacitor | dictionary/capacitor-1.0.json | 32, spanning ceramic MLCC, aluminum-electrolytic, tantalum/polymer, and film, capturing the conditioned deratings parametric databases drop: capacitance vs DC bias, ESR/impedance vs frequency, ripple current with its frequency/temperature factors, and endurance lifetime (hours→seconds). | | resistor | dictionary/resistor-1.0.json | 22, spanning thick/thin-film, current-sense (Kelvin), wirewound, and high-voltage, with power-derating vs temperature, multi-range TCR, voltage coefficient, and pulse-withstand vs pulse width. | | inductor | dictionary/inductor-1.0.json | 19, spanning power, RF-multilayer, ferrite-bead, and common-mode-choke, with inductance vs DC bias (saturation), the two distinct current ratings (magnetic Isat vs thermal Irms), and the bead's R+X+|Z| impedance triple. | | jfet | dictionary/jfet-1.0.json | 30, spanning switching, amplifier, low-noise, and matched-pair JFETs — a depletion-mode device whose defining specs are IDSS and pinch-off (not a MOSFET), plus transconductance, gate leakage, and input noise. | | comparator | dictionary/comparator-1.0.json | 38, sharing the op-amp input/rail vocabulary and adding the timing group (propagation delay vs overdrive, dispersion), built-in hysteresis, and the open-collector-vs-push-pull output block. | | analog_switch | dictionary/analog_switch-1.0.json | 23, spanning discrete switches and muxes, with on-resistance vs analog voltage, charge injection (coulombs), off-isolation and crosstalk vs frequency, and break-before-make timing. | | adc | dictionary/adc-1.0.json | 92, from a 20-datasheet corpus spanning SAR, delta-sigma, pipelined/RF-sampling, and audio converters, capturing resolution/ENOB in bits, the delta-sigma 2-D noise table (over data rate and PGA gain), SNR/SINAD/SFDR/THD swept over input frequency, and A-weighted dynamic range. Linearity (INL/DNL) is normalized to ppm-of-full-scale rather than part-relative LSB. | | dac | dictionary/dac-1.0.json | 104, from a 20-datasheet corpus spanning precision string/R-2R, high-resolution, multiplying/current-output, high-speed RF current-steering, and audio converters. Shares the ADC dynamic/reference/filter vocabulary and adds the DAC-specific keys: glitch impulse and digital feedthrough in Vs (volt-seconds), settling time over step size and accuracy, SFDR/IMD/NSD swept over output frequency, multiplying bandwidth, and voltage-vs-current output carried by which key is populated. | | crystal | dictionary/crystal-1.0.json | 20, from a 20-datasheet corpus spanning 32.768 kHz tuning-fork, MHz AT-cut SMD (fundamental and overtone), automotive/AEC-Q200, and through-hole HC-49 quartz crystal units. Passive resonators only — the active XO/TCXO/VCXO/OCXO oscillators that contain a crystal are a separate family. Adds the parabolic turnover coefficient in ppm/degC2 (the defining thermal spec of a tuning-fork cut) with its turnover temperature, the RLC equivalent circuit (ESR/C0/C1/L1), drive level (operating vs absolute-max survivable, split by limitClass), and aging as a bounded ppm figure over a stated window rather than a per-year rate. | | led | dictionary/led-1.0.json | 43, from a 20-datasheet corpus spanning visible indicator, high-brightness white lighting, RGB/multi-color, infrared, and ultraviolet (UV-A/B/C) emitters. A single PN-junction emitter (laser diodes, LED-driver ICs, photodiodes, and optocouplers are separate families). Carries two mutually-exclusive optical vocabularies — photometric (luminous intensity in cd, luminous flux in lm, efficacy in lm/W, color temperature in K, CRI and CIE x/y in 1) for visible parts and radiometric (radiant intensity in W/sr, radiant flux in W) for IR/UV — with wavelength and spectral bandwidth in m, and multi-color parts keyed by an EMITTER (red/green/blue) condition axis that composes with forward current. | | laser_diode | dictionary/laser_diode-1.0.json | 53, from a 20-datasheet corpus spanning Fabry-Perot edge emitters, single-frequency DFB/DBR sources, VCSELs, and high-power/fiber-coupled modules. Reuses the emitter envelope with a disjoint vocabulary: slope (differential) efficiency in W/A, wavelength current-tuning in m/A, coherent linewidth in Hz, side-mode suppression and RIN in dB, beam divergence in deg, plus an optional back-facet monitor-photodiode block and an optional TEC/thermistor cooler block for pigtailed modules. Laser-diode driver ICs, photodiodes, and optical transceivers are separate concerns. | | photodiode | dictionary/photodiode-1.0.json | 52, from a 20-datasheet corpus spanning silicon PIN, avalanche (APD), silicon-photomultiplier (SiPM/MPPC), InGaAs, and position-sensitive (PSD) / quadrant detectors. The emitter envelope inverted — responsivity in A/W (the reciprocal of a laser's W/A) swept over an incident-wavelength axis, noise-equivalent power in W/sqrtHz, active area in m2 — with optional avalanche (gain, breakdown, excess-noise k-factor), SiPM (PDE, dark-count-rate, crosstalk, microcells), and position (resolution, detection error, interelectrode resistance) blocks. Phototransistors, ambient-light-sensor ICs, optocouplers, and solar cells are separate concerns. | | optocoupler | dictionary/optocoupler-1.0.json | 93, from a 20-datasheet corpus across Vishay, Broadcom, Toshiba, Sharp, Everlight, Lite-On, and onsemi. One dictionary spanning every output architecture over a shared LED-input and isolation-barrier core, distinguished by which output-block keys are present (the LED-family pattern): phototransistor/photodarlington (current transfer ratio in %), high-speed logic (input threshold current, propagation delay, open-drain vs totem-pole output), gate-drive (peak source/sink current, UVLO), linear (servo-photodiode transfer gain K3 = K2/K1 in 1, nonlinearity, CMRR in dB), photovoltaic MOSFET-driver, and photo-triac-driver (trigger/holding current, off/on-state voltage). The isolation block — withstand/working/transient/surge/partial-discharge voltages in V (Vrms/Vpeak carried by statistic), CMTI in V/us, creepage/clearance/insulation-thickness in m, CTI in V — is the headline. Zero new units. Load-carrying solid-state relays, LED-less digital isolators, and isolation amplifiers are separate future families. | | oscillator | dictionary/oscillator-1.0.json | 67, from a 20-datasheet corpus across SiTime, Abracon, Epson, ECS, NDK, Connor-Winfield, IQD, Vectron/Microchip, and Renesas. The packaged active frequency source (contains a quartz/MEMS/silicon resonator plus an active output stage — distinct from the passive crystal). One dictionary spans every sub-type over a shared core, distinguished by which optional keys are present (the LED/optocoupler pattern): simple XO, TCXO, VCXO/VC-TCXO (the tuning block — pull range, tuning slope in ppm/V, control voltage), DCXO (digital control), OCXO/VC-OCXO (the oven block — warm-up time/power, Allan deviation, retrace), and MCXO. Zero new units — SSB phase noise (dBc/Hz) in dB arrayed over a carrier-offset axis, all jitter in s, Allan deviation σy(τ) as 1 over an averaging-time axis, stability/tolerance/aging/pull-range in ppm (a printed ppb is ×1e-3), tuning slope in ppm/V, warm-up power in W. g-sensitivity (ppb/g) is kept verbatim as a ppm magnitude. Clock generators / PLLs / jitter cleaners (frequency synthesis or distribution), RTCs, and the passive crystal are separate families. |

To add a family, write a dictionary that conforms to dictionary/family-dictionary-1.0.schema.json and a validated example. No schema change is required.

Validation against real datasheets

The LDO dictionary was built and checked against a corpus of 39 datasheets from 20 manufacturers totaling 916 pages, including Texas Instruments, Analog Devices, onsemi, Torex, Microchip, Diodes, STMicroelectronics, Infineon, Richtek, and Toshiba. The corpus spans simple three-pin regulators through feature-rich parts with enable, power-good, and adjustable outputs. Each parameter in the dictionary appears across the corpus or in a manufacturer parameter glossary. The parameter-frequency analysis is in spec/v1.0/parameter-frequency-analysis.txt.

Conformance and versioning

The test/conformance/ directory holds positive fixtures that must validate and negative fixtures that must be rejected, including empty values, non-base units, an invalid limitClass, and missing provenance. npm test runs the full suite.

Conformance has two layers, documented in CONFORMANCE.md: portable JSON Schema validation, plus three small dictionary-driven checks a consumer implements because a family-agnostic schema cannot express them (a parameter's key is in its family dictionary; a measurement's unit matches that parameter's unit, so a temperature cannot be given in volts; a condition axis carries the right dimension). Both layers are language-agnostic — the reference runner is JavaScript, but any consumer reimplements the family checks from the dictionary JSON in a few lines.

Two version axes are kept distinct. The schema version is MAJOR.MINOR in the filename and $id, for example datasheet-1.0. The npm package uses full semantic versioning. Several 1.0.x package releases may ship the same datasheet-1.0 schema.

A MINOR schema change is additive only. A MAJOR change publishes a new $id, and every previously published schema URL remains hosted so existing references do not break. The requirement that every value carries conditions and provenance does not change across versions. See GOVERNANCE.md.

Prior art

The idea of a machine-readable datasheet has been attempted before. None of the prior efforts combines a per-value test condition with provenance back to the source page, which is the requirement for machine-extracted specifications to be trustworthy.

edatasheets (the closest neighbor)

The digital-datasheets working group, originated at Intel, defines a JSON Schema format for component datasheets with per-component-class specifications and value and condition structures. It is the nearest existing work to this project. Two facts shape the decision to publish a new schema rather than adopt it.

First, it is effectively unmaintained. Intel's companion tooling states that it will no longer provide support, accept patches, or guarantee development, and it suggests forking. Second, its design center is a manufacturer-authored format on JSON Schema draft-07. This project's design center is different. It treats provenance to the source page and the absolute-maximum versus recommended versus characterized distinction as first-class, precisely so that a value produced by an extraction pipeline can be audited against the page it came from. It targets JSON Schema 2020-12, ships a conformance suite, and is actively maintained.

Convergence would be welcome. If the digital-datasheets effort resumes, the two vocabularies can be cross-mapped. Until then, this schema is maintained and adoptable today.

Other machine-readable datasheet efforts

| Effort | What it is | Difference | |---|---|---| | JEDEC JEP30 (PartModel) | Official XML standard for machine-readable part attributes. | Heavyweight and vendor-oriented, with limited grassroots adoption. No per-value provenance. | | Google Cyanobyte | Machine-readable register maps for I2C peripherals, used for code generation. | Describes device interfaces, not electrical specifications. Dormant. | | CCSDS SOIS Electronic Data Sheets | XML device-interface specifications used in spaceflight software. | Niche aerospace scope, interface-oriented. |

Adjacent standards and datasets

| Standard or dataset | Function | Difference | |---|---|---| | IEC 61360, IEC CDD, eCl@ss | Property-name and unit dictionaries. | No test-condition field. | | IBIS, SPICE | Condition-aware behavioral models. | Model behavior, not the guaranteed datasheet table. | | Octopart, Nexar, SiliconExpert, Datasheets.com | Commercial parametric datasets and APIs. | Closed, ad-hoc schemas. Generally no test-condition capture or per-value provenance to the source PDF. | | IPC-2581 | PCB manufacturing data exchange. | Board manufacturing, not device specifications. |

License

MIT. Datasheet PDFs are copyrighted by their manufacturers and are not redistributed by this project. The schema describes extracted factual specifications, which are not themselves copyrightable.