openpcb-core-library

Readable JSON source for the OpenPCB Core Library — the default set of symbols, footprints, 3D models, and components shipped with the OpenPCB desktop app.

Layout

symbols/<category>/<name>.symbol.json        component symbols
footprints/<category>/<name>.fp.json          physical footprints
3d/<category>/<name>.step                    source 3D model geometry
3d/<category>/<name>.model.json              sidecar metadata; pack generates GLB
components/<category>/<name>.component.json  assembled components
schemas/                                JSON Schema (draft 2020-12)
tools/validate.ts                        schema + cross-reference validator
tools/pack.ts                            builds .opclib release artifact
tools/import-kicad.ts                    manual KiCad seed import wrapper
library.json                             generated by `bun pack`
dist/*.opclib                            generated release artifact (not committed)

Commands

bun install                  # install dependencies
bun run typecheck           # type-check tools/ and components/
bun test                   # run all package tests
bun run validate           # validates the source tree
bun run pack --version X.Y.Z  # writes openpcb-core-library-X.Y.Z.opclib
bun tools/import-kicad.ts    # import symbols/footprints from a KiCad library

Gates (all enforced in CI):

bun tools/validate.ts --release --strict     # schema, provenance, pins, courtyard, parameters
bun tools/audit-3d-placement.ts --release    # 3D orientation
bun tools/audit-components.ts --no-render    # symbol overlap + orientation + cross-refs (headless)
bun tools/audit-components.ts                # ...plus a Playwright contact sheet (local only)
bun tools/check-datasheet-links.ts           # curated datasheet URLs: https, direct PDF, no mirrors

check-datasheet-links is structural by default and does no network I/O — manufacturer WAFs block automated probes (st.com and analog.com time out; onsemi, microchip, tdk and phoenixcontact answer 403), so reachability cannot gate a build without going red on correct URLs. Run the opt-in probe locally to hunt link rot:

bun tools/check-datasheet-links.ts --network                   # advisory; WAF hosts report `blocked`
bun tools/check-datasheet-links.ts --network --strict-network  # 404/410 on a probeable host is fatal

Maintenance tools:

bun tools/rebuild-previews.ts       # re-normalize every preview from `raw` after a builder change
bun tools/backfill-raw.ts           # restore a real parse on sidecars with a placeholder `raw`
bun tools/normalize-parameters.ts   # rewrite parameters onto the canonical dictionary
bun tools/gen-pinmap.ts --footprint=<path>   # identity pinMap for a manifest entry

dist/*.opclib is generated by bun pack and is not committed to the repository. --no-step produces a GLB-only core pack (~60% smaller; the app renders GLB) plus a -step.zip companion for MCAD export.

Releasing

1. Bump content/version as needed, run bun run validate --release.
2. Tag the release: git tag v1.2.3 && git push origin v1.2.3.
3. CI (.github/workflows/release.yml) typecheck → test → validate → pack → sign (if OPCLIB_SIGNING_KEY secret present) → SHA256SUMS → publish GitHub Release. Three artifacts ship: the full .opclib (GLB + STEP), a -glb.opclib core pack, and a -step.zip companion — plus SHA256SUMS and keys/openpcb-core.pub.

Signing prerequisites (one-time):

• Generate an Ed25519 key pair (see keys/README.md).
• Commit the .pub file to keys/openpcb-core.pub. Copy it into OpenPCB's resources/keys/.
• Add the PEM-encoded private key as GitHub secret OPCLIB_SIGNING_KEY.
• Set repo variable OPCLIB_KEY_ID (e.g. openpcb-core-2026).

Without the secret, packs ship unsigned (OpenPCB will warn but still import in dev mode).

KiCad provenance

This library contains data converted or adapted from the KiCad official libraries. See ATTRIBUTION.md and NOTICE.md for licensing details, original sources, and the KiCad Libraries Exception.

The KiCad source libraries are vendored at ../references/kicad-libs, pinned to KiCad 10.0.4 (https://gitlab.com/kicad/libraries @ c7e226a49). Verify the checkout with bun run fetch:kicad-libs. Import manifests resolve their kicad-symbols/…, kicad-footprints/…, and kicad-packages3D/… paths against this tree (--kicad-root ../references/kicad-libs, the importer default). In KiCad 10 symbols are unpacked per-symbol files: <Lib>.kicad_symdir/<Name>.kicad_sym.

ID convention

openpcb.core.<category>.<slug> — dotted, lowercase. Examples:

• openpcb.core.passive.resistor
• openpcb.core.footprint.passive.r-0603
• openpcb.core.symbol.passive.resistor
• openpcb.core.3d.passive.r-0603

License

CC-BY-SA-4.0 + OpenPCB Library Exception. See LICENSE.md.