File format

The package file is a JSON file with an array of “objects”, each object representing a package. The table below describes the fields for a single package. The file uses the UTF-8 character set.

Fields that are not relevant for a particular package may be omitted. For example, the “exposed-pad” field is irrelevant for a 2-pin “chip” package, and it is usually not recorded. Likewise, for packages with “endcap” or “no-lead” terminations, the lead-to-lead size is identical to the body size, and it is then sufficient to record the body size.

For fields that have an array type, if that array has no elements, the field may also be set to null. For example, when a package has no variants, the “variants” field may be set to null, rather than an empty array. Still, the preferred way to handle this case is to not include the “variants” field at all.

FieldTypeDescription
date-modifiedstringdate and time stamp of the last update to the package, in the form YYYY-MM-DDTHH:MM:SS (the letter ?T? is a literal; it is the separator between the date and the time).
namesarray of stringscommon names
descriptionstringoptional brief description
typestring“SMD” or “Through-hole”
pin-countintegernumber of pins or leads of the package
pitchnumberpin pitch in mm, if applicable
polarizedbooleantrue or false (may be absent if irrelevant)
terminalstringone of the following: “endcap”, “gull-wing”, “inward-L”, “lug-lead”, “J-lead”, “no-lead”, “ball”, “castellated” or “through-hole”
tape-orientationintegerangle between packaging orientation (EIA-481D) and normative zero-orientation (IPC-7351), in degrees
bodyobjectbody size (excluding pins) and centroid
· cx, cynumbernominal horizontal and vertical dimensions in mm
· tol.x, tol.ynumberoptional tolerance for the horizontal and vertical dimensions in mm
· x, ynumberoffset of the body centre from the centroid
lead‑to‑leadobjectlead-to-lead” size and centroid (see Figure 2)
· cx, cynumberlead-to-lead nominal horizontal and vertical dimensions in mm
· tol.x, tol.ynumberoptional tolerance for the horizontal and vertical dimensions in mm
· x, ynumberoffset of the shape centre from the centroid
referencesarray of objectsbody size (excluding pins) and centroid
· standardstringname or identification of the reference
· organizationstringorganization that established the reference
related‑packagesarray of stringsnames of other packages in the package file to which this package is related
variantsarray of objectslist of specific variants of the common name
· namestringthe (normative) name of the variant
· standardstringname of the standard or convention (if any)
· heightobjectthe height range of the variant in mm
· · lownumberminimum height in mm
· · highnumbermaximum height in mm
· exposed‑padbooleanwhether this variant has an exposed-pad
· notesstringoptional comment or notes
footprintsarray of objectslist van footprints
· typestringone of “nominal”, “least” or “most”, according to the specification in IPC-7351
· spanobjectdistance between pads in opposing rows (see Figure 4)
· · cx, cynumberdistance in mm
· contourobjectfootprint contour and centroid (see Figure 2)
· · cx, cynumbercontour horizontal and vertical dimensions in mm
· · x, ynumberoffset of the contour centre from the centroid
· pad‑shapesarray of objectslist of unique pad shapes and sizes used in the footprint
· · pad-idintegersequence number of the pad shape definition
· · cx, cynumberhorizontal and vertical dimensions of the pad in mm
· · shapestringone of “rectangle”, “round”, “roundedrect”, “obround”, “polygon” or “special”
· · exposed‑padbooleanwhether this pad represents an exposed centre pad (for variants that have an exposed-pad)
· · holenumberdiameter of the hole in the pad (applicable for through-hole packages)
· · x, ynumberoffset of the pad origin relative to the pad’s geometric centre
· pad‑positionsarray of objectlist of the pad positions
· · pin-idintegerpin number
· · pad-idintegerreference to the pad shape for this pin
· · x, ynumberposition of the pad origin, relative to the centroid position of the footprint
· · rotationnumberrotation of the pad shape, relative to the definition in the pad-shapes array

Notes

For the pad shape, a square pad is stored as a “rectangle” shape; the cx and cy parameters will establish that it is square. The radius for the rounded corners of a “roundedrect” shape is not specified; in the scope of Packages, the intent is to flag the pad shape as an intermediate form between rectangle and obround.

All coordinates assume that in the 2D projection, the Y-axis points upwards. This is in conformance with the Gerber standard. Some design programs use a downward Y-axis —a common convention in the early days of computing. Such programs should flip the sign on Y coordinates on reading the data from the JSON file.

Figure 5: X & Y axis orientation