Specifications¶

A specification says what is required: which deviation is permitted at which point, by manufacturer data, standard or customer agreement. How the measurement is done is in the test plan, and who reads the value (runner, camera, technician) is decided at the workstation. The calibration puts the three together when the plan is loaded. Why they are kept apart is explained in the ADR One specification with options (German).

One specification, several options¶

There is one specification per device type. It collects everything known about that type and splits it into options:

Kind	Example
Manufacturer	"Manufacturer, 1 year" from the data sheet
Standard	"Class A" and "Class B" to DIN EN 60751
Customer	tighter or wider limits a customer agreed on
Usage	"Short check" with fewer points on the same device

Every row of the specification carries its own tolerance per option, or is not used by the option (empty cell). Manufacturer, standard and customer sit side by side, and the difference is visible per row. An option also has an interval, a coverage factor k and a note, such as the clause of the standard. Exactly one option is the default option.

A customer option refers to the customer instead of naming them. It only appears for calibrations of that customer, and export and AI comparison only include it when it is chosen explicitly.

Where specifications live¶

Location	Path	Effect
Device type	`/v2/device-type/[id]` → Specifications tab	applies to every device of that type
Device	`/v2/inventory/[id]` → Specifications tab	only for device-specific data, such as a factory test report

A device specification replaces the one of the type completely as soon as it has a released revision. Nothing is merged and nothing is copied. The device view shows both cards and marks which one applies.

The device also carries the default option of this device. It is preselected for its calibrations; for a reference standard it is the option its accuracy is calculated with.

Rows¶

Kind	Meaning
Band	Tolerance for every value between start and end. Gives a tolerance only; it does not require a test point.
Point	Tolerance for exactly one value. Every option that uses the row requires this test point.
Derived limit	Limit of a derived quantity, today the hysteresis between a rising and a falling reading.
Contribution	Uncertainty contribution the device brings along as a reference standard, such as the homogeneity of a bath. The value per option is the half-width of a rectangular distribution.
Header, comment	Text without numbers.

The fields of a row:

Field	Meaning
Function	Measuring function from the catalogue, such as DC voltage or temperature. A point of the plan finds the row by function, unit and value. If the catalogue does not know the unit (such as `lx`, `dB`, `rpm`, `l/min`), the function stays empty and the point finds the row by unit; for a unit of the catalogue the function is required.
Prefix / unit	SI prefix and unit symbol kept apart; the numbers stay as in the data sheet. Writing `mV` as the unit stores prefix `m` and unit `V`; levels and scales such as `dB`, `dBm` and `°C` and units such as `min` stay whole.
Range	Range the device under test is switched to, not the test point; the reference of `/` terms.
Value or start / end	The point, or the signed bounds of the band. "Absolute value" lets `0 … 1000 V` also cover −500 V.
Modifier from / to	Second parameter, usually the frequency band of an AC quantity.
Resolution	Display resolution at this row, the reference of `D` terms.
Tolerance per option	MET/CAL notation: `0.05% 0.003U` (percent of the value plus an absolute part in the unit of the row; `U` is not a digit count), `0.05% 3D` (digits), `0.1/` (percent of range, or of the nominal value of the test point when the row has no range, as with a source), `ppm`. A 4 µm limit on a row in mm is therefore `0.004U` or, at resolution 0.001, `4D`. Empty means: this option does not use the row.
Source	Where the row comes from: a page of the data sheet, or for a MET/CAL import the FSC, step and role such as `5500 1.003 · UUT Indicated`. For traceability only, never part of a calculation. The list shows it below the row.

Example: Pt100, options Class A, Class B, Short check

Row                         Class A       Class B       Short check
Band  −50 … 250 °C          0.15U 0.2%    0.3U 0.5%     0.3U 0.5%
Point   0 °C                0.15U         0.3U          0.3U
Point 100 °C                0.35U         0.8U          (not used)

A calibration with "Short check" only requires the point at 0 °C here; with "Class A" it requires 0 °C and 100 °C, each with the limits of class A.

Draft, release, revisions¶

A specification is a controlled document:

Only the draft is edited (Edit draft or Start new draft), at most one per specification. The editor shows rows and options as a matrix.
Release draft checks the content (at least one option, the default option exists, readable tolerances, no two identical point rows in one option) and makes the revision immutable with person, time and content hash. From then on it applies to new calibrations.
Revisions lists every state; the comparison shows per option what changed against the previous revision.
A released revision is withdrawn (with a reason), never deleted. Only a draft is deleted; a specification without a released revision disappears with it.
With the lab switch Four-eyes release (Settings › Calibration › Specifications) only someone other than the last editor of the draft may release. Off by default.

A draft counts in no check. Calibrations keep the revision they were loaded with until someone applies their option again.

How a calibration gets its tolerances¶

In the Test steps tab of the calibration, above the test plan, it says which specification and option the calibration is evaluated against. It is preselected from the default option of the device, then an option for the customer of the device, then the default option of the specification. With a single option, that one applies by itself. With several choosable options and none chosen, the plan does not load (error spec_no_choice): otherwise it would arrive without tolerances and without the optional points, and reloading after the choice would delete captured values.
When the plan is loaded, calServer freezes the tolerances. A tolerance in the plan (on the step or its group) wins; it is a different yardstick and is marked as such on the certificate. Otherwise it comes from the chosen option, with range and resolution of the same row.
If no row or several rows match, the point stays without a tolerance and therefore without a verdict, never with the first row. Measurement capture shows the origin per point ("Specification · option", "Plan", "Plan (group)", "No tolerance") and the reason.
If the option is changed after loading, calServer asks for the plan to be reloaded.

What the completion check does with this is described under Release › Specification coverage.

Import and export¶

Both use the JSON format calserver.specification, version 2 (options and rows). An export can be imported again unchanged, also on another device type. Version 1 (one sheet per variant with the old columns) is converted on import: a sheet becomes an option.

Export: from the menu of a specification, or for a single revision in the Revisions dialog. Customer options are only included when requested explicitly.
Import: Import opens a dialog with a file picker or direct JSON input. The file picker also takes MET/CAL accuracy files (.acc); calServer reads header and table and puts the result into the field as JSON. Preview shows in advance what would happen per entry, without writing anything.

Mode	Behaviour
Create	creates the specification with a first draft; fails where the type or device already has one
Skip existing	leaves an existing specification untouched
Replace existing	writes the content into the draft of the existing specification; released revisions stay
Add options	adds the options of the payload to the draft; matching rows only get the new tolerance. The way to bring an ACC file or another data sheet to a type that already has a specification

Imports from extraction, MET/CAL or ACC always stay a draft until a person releases them.

{
  "format": "calserver.specification",
  "version": 2,
  "specifications": [
    {
      "name": "Pt100 resistance thermometer",
      "default_option": "class-b",
      "options": [
        { "key": "class-a", "name": "Class A", "kind": "standard", "note": "DIN EN 60751" },
        { "key": "class-b", "name": "Class B", "kind": "standard", "note": "DIN EN 60751" },
        { "key": "short", "name": "Short check", "kind": "usage" }
      ],
      "rows": [
        { "key": "h1", "kind": "header", "description": "Temperature" },
        { "key": "band", "kind": "band", "function": "temp", "unit": "°C",
          "range_start": -50, "range_end": 250,
          "tolerances": { "class-a": "0.15U 0.2%", "class-b": "0.3U 0.5%", "short": "0.3U 0.5%" } },
        { "key": "p0", "kind": "point", "function": "temp", "unit": "°C", "value": 0,
          "tolerances": { "class-a": "0.15U", "class-b": "0.3U", "short": "0.3U" } },
        { "key": "p100", "kind": "point", "function": "temp", "unit": "°C", "value": 100,
          "tolerances": { "class-a": "0.35U", "class-b": "0.8U" } }
      ]
    }
  ]
}

The key of an option stays the same across revisions; calibrations and devices refer to it. IDs are not part of the payload, so it can be moved between systems.

From the MET/CAL import¶

When a MET/CAL procedure is imported (on its own or as a project), its measuring points become an option metcal-<procedure> (kind usage) in the draft of the specification of the chosen device type. If the specification does not exist yet, it is created. A test point becomes a point row, negative ones included, and every row carries its source (FSC, step, role). The headings of the procedure come along; a heading without points of its own stays as a parent of the next group.

Importing the same procedure again replaces the option in the draft. If the option is already released, the import replaces nothing silently and asks instead:

Choice	What happens
New version	The option is replaced in the draft of the next revision. Until that draft is released, the released revision applies.
Further option	The measuring points become an option of their own with a new name beside it, also in the draft.
Keep	Nothing is imported; the result names the released option. Only in the project import, which asks once up front for all plans.

The test plan from the project import carries no tol once its procedure has become an option (also with "Keep", because then the option is released): the tolerance comes from the chosen option, and until that is released the plan rates nothing. In the plan, tol would always win over the specification and the option would never apply. Only without a device type (no specification import) or when the specification could not be created does the plan keep tol as its only yardstick.

The same holds for modules from the import: if every plan that calls a subprocedure gets an option, the module carries no tol either. If plans with and without an option call the same subprocedure, it does not become a module but stays inlined in each plan, so the plan without an option keeps its tol.

Sheets from the old tables¶

Before the option model, specifications lived in the tables specification and specification_detail; V2 no longer reads them. The V1→V2 migration adopts them into the option model at its end. A V2 system that maintained its sheets there (MET/CAL import, import_specifications before 2026-11-02) adopts them by hand:

docker exec calserver-api-v2 php artisan specifications:adopt-v1          # report, writes nothing
docker exec calserver-api-v2 php artisan specifications:adopt-v1 --apply  # adopts, asks first

Per context (device type or device) one specification is created, per sheet one option. A context that already has a specification in V2 stays untouched; the old tables are only read.

Authoring specifications over MCP¶

Tool	Purpose
`describe_specification_format`	Options, row kinds, lookup and release rules, import modes, example
`query_specifications`	Check what exists in the target context
`get_specification`	Output specifications in import format
`import_specifications`	Write a batch, with mode and dry run
`delete_specification`	Delete specifications that were never released; a released one is withdrawn, not deleted

Recommended flow: describe_specification_format first, then query_specifications against the target type, then import_specifications with dry_run, and finally without it.

Write access

Writing MCP tools require specification_edit or specification_delete and are additionally guarded by mcp.writes_enabled and demo mode. A dry run works even with writes switched off.

Generating a procedure¶

Generate procedure in the menu creates a test plan on the device type from the point rows of an option. The plan describes only the procedure and carries no tolerances; they come from the option the calibration chose when the plan is loaded. If the option has no point rows, one point at the end of each band is proposed. See Procedures and test steps.

Permissions¶

Operation	Effect
`specification_view`	Read, revisions, comparison and export
`specification_edit`	Create, edit and discard the draft, import, release, withdraw, set the default option of a device
`specification_delete`	Delete a specification that was never released
`calibration_edit`	Choose the option of a calibration
`procedure_edit`	Generate a procedure from a specification