logistics.hs-code-validate

Check the format of a commodity code: 6-digit HS, 8-digit CN or 10-digit TARIC/UK code, with chapter and heading checks.

1.0.0 · published 2026-10-03 by charlie · Anterra

Pinned by 16 tests, run in TypeScript, Python and Rust.

What it does

Checks that a commodity code is well formed: the right number of digits, a chapter that exists in the Harmonized System, and a heading that is not `00`. It answers rather than throws, like the other validators: a malformed code is the answer "no", with a reason.

## Lengths

For example

validate_hs_code(847130) → valid true, normalised 847130, kind hs, chapter 84, heading 8471, subheading 847130, reason — a 6-digit HS subheading
validate_hs_code(8471.30.00) → valid true, normalised 84713000, kind cn, chapter 84, heading 8471, subheading 847130, reason — an 8-digit CN code written with dots
validate_hs_code(0101 21 00 00) → valid true, normalised 0101210000, kind taric, chapter 01, heading 0101, subheading 010121, reason — a 10-digit code keeps the leading zero of chapter 01

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

def validate_hs_code(value: str) -> HsCodeCheck

value	string	digits, optionally grouped with spaces or dots, e.g. "8471.30.00"
returns	HsCodeCheck

The type it declares, generated into your project

@dataclass(frozen=True)
class HsCodeCheck:
    """The result of checking a commodity code. Every string but reason is null when valid is false; reason is null when it is true."""

    valid: bool
    #: the digits only
    normalised: Optional[str]
    #: hs (6 digits), cn (8) or taric (10, also the UK's commodity code length)
    kind: Optional[str]
    #: first two digits, leading zero kept: "01"
    chapter: Optional[str]
    #: first four digits
    heading: Optional[str]
    #: first six digits, the internationally shared HS subheading
    subheading: Optional[str]
    #: empty, bad-character, bad-length, bad-chapter, reserved-chapter, national-chapter or bad-heading
    reason: Optional[str]

Your code names it in one line, in the file that uses it

from fune.logistics.hs_code_validate import validate_hs_code  # logistics.hs-code-validate@^1

impl/python.py · 53 lines · open · raw

from .logistics_hs_code_validate_types import HsCodeCheck

_KINDS = {6: "hs", 8: "cn", 10: "taric"}


def _invalid(reason: str) -> HsCodeCheck:
    return HsCodeCheck(
        valid=False, normalised=None, kind=None, chapter=None, heading=None, subheading=None, reason=reason
    )


def validate_hs_code(value: str) -> HsCodeCheck:
    """Check the format of a 6-digit HS, 8-digit CN or 10-digit TARIC/UK
    commodity code. Validators answer rather than raise: a malformed code is
    the answer "no"."""
    if not isinstance(value, str):
        return _invalid("empty")
    chars = []
    for ch in value:
        if ch == " " or ch == ".":
            continue
        # Compare with ASCII explicitly: str.isdigit() accepts full-width digits.
        if ch < "0" or ch > "9":
            return _invalid("bad-character")
        chars.append(ch)
    digits = "".join(chars)
    if not digits:
        return _invalid("empty")
    kind = _KINDS.get(len(digits))
    if kind is None:
        return _invalid("bad-length")

    # Text, not a number: chapter "01" must keep its zero.
    chapter = digits[0:2]
    if chapter == "00":
        return _invalid("bad-chapter")
    if chapter == "77":
        return _invalid("reserved-chapter")
    # 98 and 99 are left to national tariffs, so only a national-length code may use them.
    if chapter in ("98", "99") and kind == "hs":
        return _invalid("national-chapter")
    if digits[2:4] == "00":
        return _invalid("bad-heading")

    return HsCodeCheck(
        valid=True,
        normalised=digits,
        kind=kind,
        chapter=chapter,
        heading=digits[0:4],
        subheading=digits[0:6],
        reason=None,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add logistics.hs-code-validate

Download for Python logistics.hs-code-validate-1.0.0-python.fune · 11,448 bytes sha256 1c0a088bbebdac48639c0c8e28c562a1126dd74e35785ae0d2bc7b41f37941c3

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./logistics.hs-code-validate-1.0.0-python.fune, or fetch it from a terminal with fune pull logistics.hs-code-validate@1.0.0:python.

The whole function, every language, is one file too: logistics.hs-code-validate-1.0.0.fune, 15,709 bytes, sha256 eddcf67d1fabf3fa292b04fa0eebf29864dfac042423cc3aa270daf774f60579. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

# fune: before logistics.hs-code-validate

after — your function gets the result and the arguments, and returns the final result.

# fune: after logistics.hs-code-validate

replace — it requires no other capability, so there is no dependency to replace.

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show logistics.hs-code-validate --steps.

# fune: step logistics.hs-code-validate after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
a 6-digit HS subheading	847130	→	valid true, normalised 847130, kind hs, chapter 84, heading 8471, subheading 847130, reason —
an 8-digit CN code written with dots	8471.30.00	→	valid true, normalised 84713000, kind cn, chapter 84, heading 8471, subheading 847130, reason —
a 10-digit code keeps the leading zero of chapter 01	0101 21 00 00	→	valid true, normalised 0101210000, kind taric, chapter 01, heading 0101, subheading 010121, reason —
an undivided heading ends in 00 and is fine	0409.00	→	valid true, normalised 040900, kind hs, chapter 04, heading 0409, subheading 040900, reason —
chapter 97 is the last HS chapter	970191	→	valid true, normalised 970191, kind hs, chapter 97, heading 9701, subheading 970191, reason —
chapter 99 is valid in an 8-digit national code	99050000	→	valid true, normalised 99050000, kind cn, chapter 99, heading 9905, subheading 990500, reason —
chapter 98 is not part of the HS at 6 digits	980100	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason national-chapter
chapter 77 is reserved	7701000000	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason reserved-chapter
chapter 00 does not exist	000000	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-chapter
heading 00 does not exist	840012	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-heading

Show the other 6 tests

Case	Arguments		Expected
a 4-digit heading is not a commodity code	8471	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-length
nine digits	847130000	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-length
a hyphen is not a separator	8471-30	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-character
full-width digits are not ASCII digits	８４７１３０	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason bad-character
only separators	. .	→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason empty
empty		→	valid false, normalised —, kind —, chapter —, heading —, subheading —, reason empty

More from the author

| digits | kind | what it is | |---|---|---| | 6 | `hs` | the HS subheading, shared by every country that uses the Harmonized System (WCO) | | 8 | `cn` | the EU Combined Nomenclature, and the export commodity code in the UK tariff | | 10 | `taric` | the EU TARIC code, and the UK's 10-digit import commodity code |

Four digits (a heading) is not a commodity code and fails as `bad-length`, as do 7 and 9. Spaces and dots are ignored anywhere, because codes are written `8471.30.00` and `0101 21 00 00`; nothing else is tidied away.

The code is text, never a number: chapter `01` (live animals) loses its leading zero as an integer, which is the classic bug this catches in spreadsheets. The result keeps it: `chapter` is `"01"`.

## Chapter and heading checks

The HS has 97 chapters, 01 to 97, with chapter 77 reserved for future use. Chapters 98 and 99 are not part of the HS; the HS Convention leaves them for each country's national use (the EU CN uses both, for example, and the UK tariff uses 99 for special codes).

| chapter | 6 digits | 8 or 10 digits | |---|---|---| | 00 | `bad-chapter` | `bad-chapter` | | 01-76, 78-97 | valid | valid | | 77 | `reserved-chapter` | `reserved-chapter` | | 98, 99 | `national-chapter` | valid, as a national code |

Headings are numbered from 01 within each chapter, so a heading of `00` (`840012`) is `bad-heading`. The check stops there.

## What a pass means

A valid result means the code is well formed, not that it exists in any particular tariff or in force on any date: codes are added and retired every year, and the HS itself is revised every five years or so (HS 2022 is the current edition). Look the code up in the UK Trade Tariff or EU TARIC for that.

## Sources

- World Customs Organization, Harmonized System nomenclature, 2022 edition, https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools/hs-nomenclature-2022-edition.aspx ; "Chapter 77 (Reserved for possible future use in the Harmonized System)", https://www.wcoomd.org/-/media/wco/public/global/pdf/topics/nomenclature/instruments-and-tools/hs-nomenclature-older-edition/2007/hs-2007/1577_2007e.pdf - U.S. Customs and Border Protection, "What Every Member of the Trade Community Should Know About: Tariff Classification" (chapters 98 and 99 reserved for special uses by contracting parties), https://www.cbp.gov/sites/default/files/documents/icp017r2_3.pdf - HMRC, "Finding commodity codes for imports into or exports out of the UK" (only the first 6 digits are used worldwide), https://www.gov.uk/guidance/finding-commodity-codes-for-imports-or-exports - European Commission, customs tariff (CN and TARIC), https://taxation-customs.ec.europa.eu/customs-4/calculation-customs-duties/customs-tariff_en

Files

Path	Bytes
README.md	3,056
impl/python.py	1,698
impl/rust.rs	2,428
impl/typescript.ts	1,575
vectors.json	3,422