parcel_detect_carrier_output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/eckari-com/json-schema/eckari-com-parcel-detect-carrier-output-schema.json",
  "title": "parcel_detect_carrier_output",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/eckari-com-openapi.json#/components/schemas/parcel_detect_carrier_output",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "carrier",
    "match_strength",
    "match_score",
    "candidates",
    "input",
    "formats_matched",
    "upu_s10",
    "signature_version"
  ],
  "properties": {
    "carrier": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "required": [
        "id",
        "name"
      ],
      "description": "The answer - the best-matching carrier, or null when no candidate scored at least 0.5. Always read match_strength before acting on it - a weak match names a carrier whose format has no carrier-unique marker.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable Eckari carrier identifier such as ups or royal_mail."
        },
        "name": {
          "type": "string",
          "description": "Human-readable carrier name such as UPS."
        }
      }
    },
    "match_strength": {
      "type": "string",
      "enum": [
        "distinctive",
        "strong",
        "weak",
        "none"
      ],
      "description": "How distinctive the match behind `carrier` is. distinctive = a carrier-unique marker (prefix or UPU S10 operator) plus length plus a valid check digit - only that carrier issues numbers of this shape. strong = carrier-unique marker plus length, check digit not verifiable. weak = length plus check digit only, with no carrier-unique marker; a random number of the right length passes a single decimal check digit about 1 time in 10 (about 1 in 36 for the alphanumeric mod 37,36 check), so treat a weak match as a hint. none = no carrier is named."
    },
    "match_score": {
      "type": [
        "number",
        "null"
      ],
      "description": "Deterministic signature match score for `carrier` from a fixed table (0-1, two decimals) - carrier-unique prefix plus length plus valid check digit 0.98, UPU S10 with a valid check digit 0.90, prefix plus length 0.85, length plus valid check digit 0.80, S10 structure with an invalid check digit 0.45, plus 0.02 when a country hint matches. It is a rule-based heuristic, NOT a calibrated probability, and it is null when no carrier is named.",
      "minimum": 0,
      "maximum": 1
    },
    "candidates": {
      "type": "array",
      "description": "Every carrier whose signature matched, highest score first, ties broken by carrier_id ascending. Candidates below the 0.5 reporting threshold are still listed here even though `carrier` is null, so an ambiguous or failed-check number can be inspected.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "carrier_id",
          "carrier_name",
          "match_score",
          "match_strength",
          "format_id",
          "evidence"
        ],
        "properties": {
          "carrier_id": {
            "type": "string",
            "description": "Stable Eckari carrier identifier such as ups or usps."
          },
          "carrier_name": {
            "type": "string",
            "description": "Human-readable carrier name."
          },
          "match_score": {
            "type": "number",
            "description": "This candidate's score from the same fixed table as the top-level match_score.",
            "minimum": 0,
            "maximum": 1
          },
          "match_strength": {
            "type": "string",
            "enum": [
              "distinctive",
              "strong",
              "weak"
            ],
            "description": "How distinctive this candidate's match is; same meaning as the top-level field (a candidate is never \"none\")."
          },
          "format_id": {
            "type": "string",
            "description": "Identifier of the matched format within the signature set, for example ups_1z or upu_s10."
          },
          "evidence": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "prefix",
              "length",
              "check_digit",
              "s10_origin_country",
              "country_hint"
            ],
            "description": "What about this number made the format match. A null member means that signal played no part in this match.",
            "properties": {
              "prefix": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The leading characters of the normalised number that form the carrier-unique marker, for example 1Z, or the UPU S10 service indicator such as RB. Null when the format has no distinguishing prefix."
              },
              "length": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "The exact number of characters this format requires, for example 18 for a UPS 1Z number. Null when the format accepts a range of lengths."
              },
              "check_digit": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Name of the check-digit algorithm that validated this number - ups_mod10, gs1_mod10, fedex_express_mod11, dhl_mod7, mod_37_36 or upu_s10. Null when the format defines no check digit, or when the S10 check digit did not validate."
              },
              "s10_origin_country": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 3166-1 alpha-2 country of the designated postal operator for a UPU S10 match. Null for non-postal formats."
              },
              "country_hint": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The origin_country or destination_country you supplied that matched this format's country list and added the 0.02 tie-breaker. Null when no hint applied."
              }
            }
          }
        }
      }
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "original",
        "normalised"
      ],
      "description": "The tracking number as supplied and as evaluated.",
      "properties": {
        "original": {
          "type": "string",
          "description": "Input as supplied, trimmed. Never altered otherwise."
        },
        "normalised": {
          "type": "string",
          "description": "Upper-cased value with spaces and hyphens removed - the string the rules were evaluated against."
        }
      }
    },
    "formats_matched": {
      "type": "integer",
      "description": "Number of distinct formats in the signature set whose pattern matched the normalised number, counted before check digits were applied. Zero with no candidates means no covered format matches this shape at all; a value above zero with no candidates means a covered format matched but its check digit did not validate - a typo or a partial capture rather than an unknown carrier.",
      "minimum": 0
    },
    "upu_s10": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "description": "Parsed UPU S10 components; null when the number does not have the S10 structure.",
      "required": [
        "service_indicator",
        "service_type",
        "serial",
        "check_digit_valid",
        "origin_country"
      ],
      "properties": {
        "service_indicator": {
          "type": "string",
          "description": "Two-letter S10 service indicator such as RB."
        },
        "service_type": {
          "type": [
            "string",
            "null"
          ],
          "description": "Service class implied by the first indicator letter, for example letter_post_registered; null when unrecognised."
        },
        "serial": {
          "type": "string",
          "description": "Eight-digit S10 serial number."
        },
        "check_digit_valid": {
          "type": "boolean",
          "description": "True when the S10 check digit validates against the serial."
        },
        "origin_country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2 country code of the origin designated operator."
        }
      }
    },
    "signature_version": {
      "type": "string",
      "description": "Version of the signature set that produced this result; results are reproducible for a given version."
    }
  }
}