Library Format Reference

LoomFlow’s parts library is built from manufacturer JSON files — flat, hand-writable descriptions of connector housings and the loose pieces they take. The app ships with a built-in catalog in this exact format, and you can author your own files and load them in the app. Because a library file is plain JSON, it diffs cleanly if you keep your parts files in version control. This page is the schema reference; for the authoring workflow see Adding Your Own Parts, and for browsing and placing parts see Using the Parts Library.

Know how files are grouped and merged

File names don’t matter — the manufacturer field does. Every file whose manufacturer matches (compared case-insensitively) is merged into one catalog, so deutsch-housings.json and deutsch-contacts.json, both with "manufacturer": "Deutsch", become a single Deutsch catalog. The first file loaded wins the display casing.

The merge rules:

• Cross-references resolve after the merge. A housing may reference contacts, accessories, or matesWith partners defined in any file of the same manufacturer — the built-in Deutsch catalog itself keeps housings and contacts in separate files, and a file you load can reference parts the built-in catalog already defines. References never cross manufacturers, so deleting one manufacturer’s files can’t break another’s.
• A duplicate pn across files patches. Built-in files load first, in a fixed order; files you load come after them, in the order you load them. The later definition wins (keeping the original’s picker position) — the supported way to override a built-in part without editing anything. A duplicate pn within one file is an error.

Write the top-level shape

Each file is exactly one object:

{
  "formatVersion": 1,
  "manufacturer": "Deutsch",
  "connectors": [ ... ],
  "components": [ ... ]
}

Key	Meaning
formatVersion	Always 1. The loader rejects versions it doesn’t know.
manufacturer	Display name; groups files into one catalog (case-insensitive).
connectors	Housings the user can place on the schematic.
components	Loose pieces the housings reference: contacts, wedgelocks, backshells, seals, cavity plugs.

Connector fields

Field	Required	Meaning
pn	yes	Manufacturer part number. Unique within a file; a repeat in a later file patches.
internalPn	no	Your organization’s own part number for this part. Blank in the built-in catalog by convention — fill it in your own files; it is carried into the document and the BOM.
series	yes	Product family, e.g. "DT". Groups the picker UI.
gender	yes	"male" or "female" — the gender of the contacts the housing takes (see below).
cavities	yes	Number of positions. Positive integer.
contacts	yes	Part numbers of compatible crimp contacts (type "pin" for male housings, "socket" for female).
cavityContacts	no	Per-cavity default contact, in pin order — only for mixed-size housings. Length must equal cavities; every entry must appear in contacts.
variant	no	"simple" (one cavity stands for the whole link, e.g. an HDMI cable) or "advanced" (every conductor exposed). Omit for ordinary crimp connectors. Simple only mates simple.
currentRating	no	Housing/system continuous rating in amps per circuit. The effective per-cavity limit is the minimum of this, the chosen contact’s rating, and the wire’s ampacity.
description	no	Free text shown in the picker.
color	no	Housing color, free text, e.g. "Gray".
ipRating	no	Ingress protection when mated, e.g. "IP67" or "unsealed".
application	no	Primary domain, e.g. "automotive", "motorsport".
notes	no	Anything a builder should know: temp range, seal wire-OD range, tooling.
designation	no	How cavity labels are generated on placement (see below).
face	no	Physical cavity arrangement on the mating face (see below).
wedgelock	no	Part number of the wedgelock (type: "wedgelock").
backshells	no	Part numbers of compatible backshells (type: "backshell").
seals	no	Part numbers of per-wire seals (type: "seal").
plugs	no	Part numbers of cavity plugs (type: "plug") for unused positions. Mixed-size housings list one per contact size.
matesWith	no	Connectors of the same manufacturer that plug into this one.
suppliers	no	Where to buy, in order of preference: primary/secondary/tertiary, each optional free text. Built-in-catalog convention: primary is the manufacturer; fill the rest with your own distributors.

Caution

gender describes the contacts the housing takes, not the housing’s own shape. A Deutsch DT04 receptacle takes male pins → "male"; a DT06 plug takes female sockets → "female". The validator rejects a contacts entry whose type doesn’t match.

Component fields

Field	Required	Meaning
pn	yes	Manufacturer part number; same uniqueness/patch rules as connectors.
internalPn	no	Your organization’s own part number; same convention as on connectors.
type	yes	One of "pin", "socket", "wedgelock", "backshell", "seal", "plug". A "plug" is a cavity plug that seals an unused position.
description	no	Free text.
gaugeRange	no	Accepted wire sizes, free text, e.g. "16-20 AWG".
currentRating	no	Continuous rating in amps (positive number). Set on contacts (pin/socket); omit on wedgelocks/seals/plugs/backshells.
suppliers	no	Same shape and convention as on connectors.

Cavity labels vs. the physical face

Two optional fields cover “what the pins are called” and “where the holes are”:

• designation generates cavity labels on placement. { "type": "sequential" } → 1..N; { "type": "grid", "rows": 2, "columns": 4 } → row-major grid labels like A1..B4. A grid’s row and column labels are set with the optional rowLabels and columnLabels objects, each { "type": "alphabetical" | "sequential" | "custom" } (a custom scheme adds a "custom": ["...", ...] array of labels). Defaults: rows alphabetical (A, B, C…), columns sequential (1, 2, 3…). For sequential designations, rowLabels alone sets the scheme — e.g. alphabetical for A..N pins.
• face is the mating-face drawing used by the layout view, mapped to cavities in pin order. Three shapes: { "shape": "grid", "rows": 2, "columns": 4 } (row-major, last row may be partial), { "shape": "rows", "counts": [1, 2] } (per-row counts top→bottom, each row centered — triangles, staggered faces), and { "shape": "circle", "rings": [8, 4, 1] } (round shell, rings outermost→center). rows counts and circle rings must sum to cavities — a face that draws the wrong number of holes is rejected.

Mating pairs

matesWith entries must point at connectors of the same manufacturer with the opposite gender and the same cavity count, listed in both directions — if A mates B, B must list A back. The validator reports one-way entries, gender clashes, and cavity mismatches. Encode keying variants (like the DT DT04-08PA/DT06-08SA A-key pair) as separate pns that mate only their matching key.

How a library part enters your document

The library is a read-only catalog. Assigning a library connector copies it into the document as a part, so a saved project never dangles when a library file changes (see the File Format reference). The copy takes default picks — the first entry of contacts, the wedgelock, the first of backshells, seals, and plugs — which you refine in the Inspector. Compatible contacts are copied with their currentRating and gaugeRange, so the per-cavity contact picker and ampacity check work on a machine without your library file.

How parts explode in the BOM

The BOM turns one placed library connector into several purchasable line items: the housing, one contact per connected cavity (a per-cavity override or cavityContacts entry beats the default), the wedgelock/backshell/seal picks, and one cavity plug per empty cavity when the part has a plug pick. The full quantity rules are in Using the Parts Library.

Validate your files

Loading is two-phase: per-file structure checks (field shapes, duplicate pns), then per-manufacturer reference integrity after the merge — so a file may legitimately lean on parts another file of the same manufacturer defines. Errors name the exact part and field, e.g. connector "DT04-2P": contacts[1] references unknown component .... To validate a file, load it via Load manufacturer JSON… in the Parts library panel — a file with problems is rejected on the spot with the full list of errors, and a valid file joins the catalog for the rest of the session.