# logistics.hs-code-validate

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

| 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