AdrCalculatorResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/freightutils-com/json-schema/freightutils-com-adr-calculator-response-schema.json",
  "title": "AdrCalculatorResponse",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/freightutils-com-openapi.json#/components/schemas/AdrCalculatorResponse",
  "type": "object",
  "properties": {
    "blocking_errors": {
      "type": "array",
      "description": "Present only on the all-ambiguous 200 (no verdict): [{ code: AMBIGUOUS_UN_VARIANT, message, recovery }], in the plain body too. recovery.params never pick a row (sent unchanged: asked again); pick from candidates[] by packing group, concentration or description; send packing_group or variant_index.",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "recovery": {
            "type": "object"
          }
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AdrCalculatorItem"
      }
    },
    "total_points": {
      "type": [
        "number",
        "null"
      ],
      "description": "Sum of all item points. Null when no load verdict was reached — a line is withheld (items[].withheld), declared on a basis 1.1.3.6.3 does not count (items[].basis_mismatch), or carries no transport category in Table A column (15) (items[].category_unresolved)."
    },
    "threshold": {
      "type": "integer",
      "description": "1.1.3.6 threshold (always 1000)."
    },
    "exempt": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether the shipment qualifies for 1.1.3.6 exemption. Null when no load verdict was reached, never false as a stand-in. false with total_points null = already NOT exempt on the resolved lines (carriage prohibited, category 0, a maximum exceeded, or a partial sum over 1,000) while a line is withheld."
    },
    "has_category_zero": {
      "type": "boolean",
      "description": "Whether any item is transport category 0 (never exempt)."
    },
    "has_quantity_exceedance": {
      "type": "boolean",
      "description": "Whether any single item exceeds its maximum quantity per transport unit."
    },
    "warnings": {
      "type": "array",
      "description": "Any warnings about the calculation.",
      "items": {
        "type": "string"
      }
    },
    "message": {
      "type": "string",
      "description": "Human-readable verdict. For loads whose entries are outside ADR scope this is a dedicated scope verdict (e.g. 'Not subject to ADR (road). Section 5.5.3 applies: ...' or 'Carriage prohibited by ADR (road). ...'), never a 1.1.3.6 claim."
    },
    "not_subject_to_adr": {
      "type": "boolean",
      "description": "Present and true when EVERY item in the load is NOT SUBJECT TO ADR (Table A) — the 1.1.3.6 calculation was not applied."
    },
    "conditions_ref": {
      "type": "string",
      "description": "ADR section whose carriage conditions still apply to a not-subject load (e.g. 5.5.3 for dry ice)."
    },
    "conditions": {
      "type": "array",
      "description": "Verbatim ADR 2025 carriage conditions for conditions_ref (e.g. section 5.5.3: ventilation, package marking, vehicle warning mark, documentation, unpackaged dry ice, training).",
      "items": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string",
            "description": "ADR 2025 subsection."
          },
          "heading": {
            "type": "string",
            "description": "Short practitioner-facing heading."
          },
          "requirement": {
            "type": "string",
            "description": "Verbatim requirement text from ADR 2025."
          },
          "note": {
            "type": "string",
            "description": "Verbatim accompanying note/example from ADR 2025, where one exists."
          }
        },
        "required": [
          "ref",
          "heading",
          "requirement"
        ]
      }
    },
    "carriage_prohibited": {
      "type": "boolean",
      "description": "Present and true when the load contains a CARRIAGE PROHIBITED Table A entry — exempt is false and the load may not be carried by road under ADR, whether or not another line is withheld."
    },
    "human_review_required": {
      "type": "boolean",
      "description": "Present and true when at least one line is withheld for an unpinned multi-variant UN. candidates[] then lists that line's rows."
    },
    "candidates": {
      "type": "array",
      "description": "The withheld lines' candidate Table A rows, each tagged with the item_index and un_number of the line it belongs to. Present only with human_review_required.",
      "items": {
        "type": "object",
        "properties": {
          "item_index": {
            "type": "integer"
          },
          "un_number": {
            "type": "string"
          },
          "variant_index": {
            "type": "integer"
          },
          "packing_group": {
            "type": [
              "string",
              "null"
            ]
          },
          "proper_shipping_name": {
            "type": "string"
          },
          "transport_category": {
            "type": [
              "string",
              "null"
            ]
          },
          "multiplier": {
            "type": [
              "integer",
              "null"
            ]
          },
          "expected_unit": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "L",
              "kg",
              null
            ],
            "description": "The 1.1.3.6.3 counted dimension of the candidate row — the only difference between two candidates when a packing group collides on state alone (UN 3375 PG II: liquid in L, solid in kg)."
          },
          "fu_id": {
            "$ref": "#/$defs/FuId"
          },
          "fu_version_id": {
            "$ref": "#/$defs/FuVersionId"
          }
        }
      }
    },
    "_source": {
      "$ref": "#/$defs/SourceEnvelope"
    },
    "resolved_subtotal_points": {
      "type": "number",
      "description": "Points of the lines that resolved (state COUNTED). Present on every verdict."
    },
    "threshold_exceeded_by_resolved_items": {
      "type": "boolean",
      "description": "The resolved lines alone exceed the 1,000-point threshold: unresolved lines can only add points, so the load is not exempt."
    },
    "verdict_basis": {
      "type": "string",
      "enum": [
        "all_items",
        "resolved_items_alone",
        "none"
      ],
      "description": "all_items: every line resolved. resolved_items_alone: a verdict settled by the resolved lines while others are BLOCKED. none: no verdict (exempt null)."
    },
    "unresolved_item_indexes": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Indexes of the BLOCKED lines (withheld, basis mismatch, category unresolved, invalid quantity)."
    },
    "basis": {
      "type": "string",
      "enum": [
        "adr_2027",
        "1.6.1.61",
        "1.6.1.1"
      ],
      "description": "ADR 2027 answers: what the verdict rests on — adr_2027, or a transitional measure open on the stated as_of that clears a load ADR 2027 does not: 1.6.1.61 (note-a rule) before 1.6.1.1 (ADR 2025), with basis_until and strict_adr_2027 beside it. Deleted entries (UN 2941): 1.6.1.1 to 2027-06-30."
    },
    "basis_until": {
      "type": "string",
      "format": "date",
      "description": "The last day the transitional basis may be applied (with basis 1.6.1.61 or 1.6.1.1)."
    },
    "strict_adr_2027": {
      "type": "object",
      "description": "Beside a verdict given on a transitional basis: the load on ADR 2027 itself (basis, total_points, exempt, has_category_zero, has_quantity_exceedance). An entry ADR 2027 deletes adds entry_deleted, deleted_un_numbers and message, with the four figures null."
    },
    "transitional_1_6_1_61": {
      "type": "object",
      "description": "ADR 2027 answers carrying one of the nine note-a UN numbers: the load on the 1.6.1.61 basis (points_on_this_basis, exempt_on_this_basis, until 2030-12-31, note)."
    },
    "transitional_1_6_1_1": {
      "type": "object",
      "description": "ADR 2027 answers inside the 1.6.1.1 window (a stated as_of to 30 June 2027) where ADR 2027 itself is not exempt: the load on ADR 2025 (points_on_this_basis, exempt_on_this_basis, until 2027-06-30, note)."
    },
    "figure_basis": {
      "type": "string",
      "enum": [
        "upper_bound_gross"
      ],
      "description": "Present when the load clears on a gross mass counted as an upper bound of the net mass; its true points are lower."
    }
  },
  "required": [
    "items",
    "total_points",
    "threshold",
    "exempt",
    "has_category_zero",
    "has_quantity_exceedance",
    "warnings",
    "message"
  ],
  "$defs": {
    "AdrCalculatorItem": {
      "type": "object",
      "properties": {
        "un_number": {
          "type": "string",
          "description": "UN number of the substance — or, on an air-only line, the canonical ID number (e.g. ID8000)."
        },
        "state": {
          "type": "string",
          "enum": [
            "COUNTED",
            "AIR_ONLY_ID",
            "NOT_SUBJECT_TO_ADR",
            "BLOCKED",
            "EXCLUDED_NIL"
          ],
          "description": "The line's route: COUNTED (one Table A row), AIR_ONLY_ID (ID-prefixed, stated ICAO limited quantities, nothing counted), NOT_SUBJECT_TO_ADR, BLOCKED (no points from the line as sent; its flag says why) or EXCLUDED_NIL (quantity 0, not carried)."
        },
        "proper_shipping_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Official ADR proper shipping name. Null on a withheld line (no row was pinned — never the first row's name)."
        },
        "class": {
          "type": [
            "string",
            "null"
          ],
          "description": "ADR hazard class. Null on a withheld line whose candidate rows differ in class."
        },
        "transport_category": {
          "type": [
            "string",
            "null"
          ],
          "description": "Transport category (0-4). Null on a withheld line."
        },
        "packing_group": {
          "type": [
            "string",
            "null"
          ],
          "description": "The resolved ADR Table A packing group for this row (echoed so a multi-variant resolution is traceable). On a withheld line: the packing group the caller supplied, or null."
        },
        "variant_index": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The resolved ADR Table A variant index for this row. Null on a withheld line."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity being transported."
        },
        "multiplier": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Points multiplier for this transport category. Null for out-of-scope rows (not_subject_to_adr / carriage_prohibited) and withheld lines — they never enter the points math."
        },
        "points": {
          "type": [
            "number",
            "null"
          ],
          "description": "Calculated points (quantity x multiplier). Null for out-of-scope rows, basis mismatches and withheld lines."
        },
        "quantity_unit": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "L",
            "kg",
            null
          ],
          "description": "Echo of the unit the caller declared (null when none was declared)."
        },
        "quantity_basis": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "net",
            "gross",
            null
          ],
          "description": "Echo of the basis the caller declared (null when none was declared)."
        },
        "expected_unit": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "L",
            "kg",
            null
          ],
          "description": "The dimension ADR 1.1.3.6.3 counts this row in — L for liquids and compressed gases, kg for solids, liquefied/refrigerated/dissolved gases and articles; null when the row does not pin one."
        },
        "basis_mismatch": {
          "type": "boolean",
          "description": "Present and true when the declared unit or basis cannot be a 1.1.3.6.3 quantity for this row. The line never enters the points math; total_points and exempt are null (unless the load is already settled by other lines)."
        },
        "category_unresolved": {
          "type": "boolean",
          "description": "Present and true when the row carries no transport category in Table A column (15) — a dash (e.g. UN 3166) or 'See SP 671' (UN 3316 kits): no 1.1.3.6 multiplier, so points, total_points and exempt are null and a warning names the column value."
        },
        "withheld": {
          "type": "boolean",
          "description": "Present and true when this line's UN resolves to more than one ADR Table A row and nothing pinned one. Row fields are null; the candidate rows sit under the response's candidates[] tagged with this line's item_index. total_points and exempt are null while any line is withheld."
        },
        "ambiguity_reason": {
          "type": "string",
          "enum": [
            "multiple_variants",
            "packing_group_collision",
            "no_matching_variant"
          ],
          "description": "Why the withheld line could not be pinned. Present only with withheld."
        },
        "equivalent_variants": {
          "type": "array",
          "description": "Present when the supplied packing_group left several Table A rows that agree on class, transport category, scope and the 1.1.3.6.3 counted dimension: the rows this verdict holds for. The row fields above are the first one's.",
          "items": {
            "type": "object",
            "properties": {
              "variant_index": {
                "type": "integer"
              },
              "proper_shipping_name": {
                "type": "string"
              }
            }
          }
        },
        "variant_note": {
          "type": "string",
          "description": "Plain-language statement of the equivalence: which rows, which fields they share, whose fields are shown. Present only with equivalent_variants."
        },
        "not_subject_to_adr": {
          "type": "boolean",
          "description": "Present and true when this row is NOT SUBJECT TO ADR (Table A) — excluded from the 1.1.3.6 calculation."
        },
        "carriage_prohibited": {
          "type": "boolean",
          "description": "Present and true when this row is CARRIAGE PROHIBITED (Table A) — the load cannot be carried by road under ADR."
        },
        "conditions_ref": {
          "type": "string",
          "description": "ADR section whose carriage conditions still apply to a not-subject row (e.g. 5.5.3)."
        },
        "air_only_id": {
          "type": "boolean",
          "description": "Present and true on an ID-prefixed air-only line: no ADR Table A entry, row fields null, never in the points — the ADR answer for limited-quantity packages to the ICAO TI (3.4.9, 3.4.10, 1.1.3.6.5), stated in the warning. Never not_subject_to_adr."
        },
        "entry_required": {
          "type": "boolean",
          "description": "Present (true) on an ID-prefixed line sent without icao_limited_quantity: no Table A entry and nothing establishes 3.4.9 / 3.4.10, so the line is BLOCKED."
        },
        "icao_limited_quantity": {
          "type": "boolean",
          "description": "Echo: the request stated icao_limited_quantity: true for this ID-prefixed line."
        },
        "nil_quantity": {
          "type": "boolean",
          "description": "Present (true) on a line sent with quantity 0: read as not carried and left out of every sum and test."
        },
        "upper_bound_gross": {
          "type": "boolean",
          "description": "Present (true) on a gross mass counted as an upper bound of the net mass, on a load that clears on it."
        },
        "edition_basis": {
          "type": "string",
          "enum": [
            "2025"
          ],
          "description": "The edition whose Table A row the line was counted on, when it is not the edition asked for: 2025 on an ADR 2027 answer given on the 1.6.1.1 basis because the line's ADR 2027 entry is deleted (strict_adr_2027.entry_deleted)."
        },
        "fu_id": {
          "$ref": "#/$defs/FuId"
        },
        "fu_version_id": {
          "$ref": "#/$defs/FuVersionId"
        }
      },
      "required": [
        "un_number",
        "state",
        "proper_shipping_name",
        "class",
        "transport_category",
        "quantity",
        "multiplier",
        "points"
      ]
    },
    "FuId": {
      "type": "string",
      "pattern": "^fu:[a-z][a-z0-9-]*(?::(?:[A-Za-z0-9._~()+-]|%[0-9A-F]{2})+)+$",
      "description": "Stable, edition-free identifier of this record: fu:<namespace>:<segment>[:<segment>…]. A join key, the same in every edition, kept in an append-only ledger. Not a regulatory reference, a citation or a promise the content never changes. GET /api/resolve?q=<fu_id> returns it."
    },
    "FuVersionId": {
      "type": "string",
      "pattern": "^(fu:[a-z][a-z0-9-]*(?::(?:[A-Za-z0-9._~()+-]|%[0-9A-F]{2})+)+)@([A-Za-z0-9._-]+)$",
      "description": "The identifier of this edition's record: <fu_id>@<edition token>. Present only where the dataset has editions (ADR, HS, UN/LOCODE, airports, Incoterms, ADR codes, ICS2, emission factors); airlines, ULDs, containers, vehicles and pallets have none."
    },
    "SourceEnvelope": {
      "type": "object",
      "description": "Additive provenance citation for the dataset or method behind this response, from FreightUtils' single provenance source of truth. Shapes: reference, methodology (calculators), or reference with provenance_status:'pending-verification'. Fields appear only when a real value exists.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "reference",
            "methodology"
          ]
        },
        "authority": {
          "type": "string"
        },
        "dataset": {
          "type": "string"
        },
        "source_url": {
          "type": "string"
        },
        "data_vintage": {
          "type": "string"
        },
        "licence": {
          "type": "string"
        },
        "retrieved_via": {
          "type": "string"
        },
        "standard": {
          "type": "string"
        },
        "reference": {
          "type": "string"
        },
        "computed_by": {
          "type": "string"
        },
        "provenance_status": {
          "type": "string",
          "enum": [
            "pending-verification"
          ]
        },
        "dataset_edition": {
          "type": "string",
          "description": "Edition this response is served from (editioned reference datasets only), e.g. 'UN/LOCODE 2025-1'."
        },
        "authority_current_edition": {
          "type": "string",
          "description": "The authority's current in-force edition at the last check. Differs from dataset_edition only when the served data lags the authority."
        },
        "checked_at": {
          "type": "string",
          "description": "YYYY-MM-DD of the last served-vs-authority edition comparison (on-demand checker, staleness-guarded)."
        }
      },
      "required": [
        "type"
      ]
    }
  }
}