vehicles 0.4.1 → 0.8.0

data/data/plates/_decode/ua-regions.yml

@@ -0,0 +1,393 @@
+# plates/_decode/ua-regions.yml — the Ukrainian region encodings.
+#
+# THE SOURCE FINDING, and it is the Anlage-5d case rather than the German one:
+# BOTH CODE TABLES ARE INSIDE THE INSTRUMENT. Розділ III п. 3 of the ВИМОГИ до
+# номерних знаків транспортних засобів (наказ МВС від 02.03.2021 № 166,
+# z0353-21), verbatim: "Літеросполуки, які позначають адміністративно-
+# територіальну належність місця реєстрації транспортного засобу, наведені в
+# додатку 4 до цих Вимог." And п. 5: "Коди, які позначають адміністративно-
+# територіальну належність місця реєстрації транспортного засобу, наведені в
+# додатку 6 до цих Вимог." Every row below is extracted MECHANICALLY from
+# Додаток 4 and Додаток 6 of the consolidated text as published on
+# zakon.rada.gov.ua — not transcribed by hand and not taken from any secondary
+# compilation. 27 regions, 108 letter pairs, no duplicates (computed).
+#
+# ---------------------------------------------------------------------------
+# TWO ENCODINGS, DIFFERENT PLATES. Read this before decoding anything.
+# ---------------------------------------------------------------------------
+# * `annex_4_codes` — a TWO-LETTER pair. Used on types 1, 5, 12-17 and subtypes
+#   3-1, 3-2, 8-2 (Розділ III п. 3). This is the pair on the LEFT of an
+#   ordinary car plate.
+# * `annex_6_numeric` — a TWO-DIGIT code. Used on types 2, 6, 7, 11 and subtype
+#   3-3 (Розділ III п. 5). This is the small number on a red transit plate, a
+#   police plate or an owner-ordered plate.
+# A consumer that treats them as one table will decode "11" as Kyiv on a police
+# plate and as nothing at all on a car plate, which is correct — and will decode
+# "КА" as Kyiv on a car plate and as nothing on a police plate, also correct.
+# The two never appear on the same plate.
+#
+# ---------------------------------------------------------------------------
+# THE SCRIPT PROBLEM — recorded, never folded away (PRD-PLATES §2.6).
+# ---------------------------------------------------------------------------
+script:
+  printed: Cyrillic (Ukrainian)
+  finding: >-
+    Every letter of Додаток 4 is CYRILLIC. Measured from the published HTML, the
+    annex uses exactly twelve codepoints and no others:
+    І U+0406 · А U+0410 · В U+0412 · Е U+0415 · К U+041A · М U+041C ·
+    Н U+041D · О U+041E · Р U+0420 · С U+0421 · Т U+0422 · Х U+0425.
+    Those are the "letters of the Ukrainian alphabet that coincide in writing
+    with letters of the Latin alphabet" that Розділ III п. 9 requires, and the
+    restriction exists so that a Ukrainian plate is readable abroad.
+  fold: >-
+    `annex_4_codes_ascii` is the fold BY GLYPH SHAPE, not by sound:
+    І->I  А->A  В->B  Е->E  К->K  М->M  Н->H  О->O  Р->P  С->C  Т->T  Х->X.
+    It is injective over the twelve, so the fold is reversible and the reverse
+    map is the list above. Both forms are recorded on every row; neither is
+    substituted for the other anywhere in this dataset.
+  fold_traps: >-
+    Cyrillic В reads B and NEVER V. Cyrillic Н reads H and NEVER N. Cyrillic Р
+    reads P and NEVER R. Cyrillic С reads C and NEVER S. Getting any of the four
+    wrong silently relabels a region: Луганська ВВ would become "VV", Одеська ВН
+    would become "VN", Запорізька АР would become "AR" and Львівська ВС would
+    become "VS" — none of which is a Ukrainian code at all. A phonetic
+    transliteration of these codes is always wrong.
+  ascii_collision_check: >-
+    Computed: the 108 folded pairs contain no duplicates, so the fold is
+    collision-free WITHIN the current table. It is NOT collision-free against
+    history — see `superseded_systems` below, where the 1995-2004 letter series
+    reused many of the same pairs against a different region map.
+
+# ---------------------------------------------------------------------------
+# THE CAVEATS THAT MAKE THIS TABLE HONEST.
+# ---------------------------------------------------------------------------
+decodes_to: >-
+  The region whose territorial МВС service centre issued THIS COMBINATION, at
+  the moment of issue. Ст. 34 of the Закон «Про дорожній рух» assigns the
+  combination on registration, and постанова КМУ від 07.09.1998 № 1388 makes
+  the service centre of the place of registration the issuer.
+does_not_decode_to: >-
+  Where the vehicle is now; where its CURRENT owner lives; or where it was
+  registered most recently. Постанова КМУ № 1388 lets an owner keep a
+  буквено-цифрова комбінація in storage on deregistration and re-attach it to
+  another of that owner's vehicles, so a combination outlives the registration
+  that produced it. Treat the code as region-at-issue and nothing else.
+caveat_online_registration:
+  date: "2022-12-12"
+  instrument: "Наказ МВС № 814 від 12.12.2022, amending Розділ III п. 1 of the Вимоги"
+  what_changed: >-
+    A vehicle "зареєстрован[ий] на підставі договору, укладеного в електронній
+    формі у визначеному законодавством порядку" carries NO region code at all.
+    In the region slot it carries one of four літеросполуки that identify the
+    CHANNEL of registration instead of a place.
+  effect_on_this_table: >-
+    A left-hand pair must be tested against `online_registration_codes` FIRST.
+    If it matches, the plate carries no geographic information whatsoever and a
+    parse API must return "no region" rather than "unknown region".
+caveat_choice_of_combination:
+  date: "2023-06-30"
+  what_changed: >-
+    The Cabinet of Ministers amended the plate-assignment rules to let an owner
+    CHOOSE the plate or its letter-and-digit combination at registration. The
+    region pair is still issued by the registering service centre, but the
+    running number inside it is no longer allocated strictly in sequence, so
+    the ordinal carries no reliable date signal after this point.
+  evidence: secondary-dated
+  source: "https://biz.liga.net/ua/all/avto/novosti/avtovladeltsam-razreshili-vybirat-nomera-pri-registratsii-avto  # 2023-07-01. Secondary; the amending постанова КМУ was not pinned in this pass"
+caveat_occupied_territories: >-
+  Crimea (UA-43), Sevastopol (UA-40) and parts of Donetsk, Luhansk, Zaporizhzhia
+  and Kherson oblasts are under Russian occupation. Their codes REMAIN IN
+  Додаток 4 and Додаток 6 of the instrument in force on 16 December 2025, and
+  are recorded here exactly as the instrument carries them. Ukraine continues to
+  register vehicles from those regions through relocated service centres, so a
+  Crimean or Sevastopol code on a plate issued after 2014 does not locate the
+  vehicle in Crimea or Sevastopol. This table states the instrument; it makes no
+  claim about where any vehicle is.
+
+# ---------------------------------------------------------------------------
+jurisdiction: ua
+topic: regions
+authority:
+  name: "ВИМОГИ до номерних знаків транспортних засобів, Додаток 4 (літеросполуки) and Додаток 6 (коди) — Міністерство внутрішніх справ України"
+  url: "https://zakon.rada.gov.ua/laws/show/z0353-21"
+sources:
+  - "https://zakon.rada.gov.ua/laws/show/z0353-21  # Наказ МВС від 02.03.2021 № 166, ВИМОГИ, Додаток 4 «ЛІТЕРОСПОЛУКИ, які позначають адміністративно-територіальну належність місця реєстрації транспортного засобу» (27 rows x 4 pairs, extracted mechanically) and Додаток 6 «КОДИ ...» (01-27, Kyiv 11 and 31); Розділ III пп. 1, 3, 5, 6. Consolidated text, revision 16.12.2025. Accessed 2026-08-03"
+  - "https://zakon.rada.gov.ua/laws/show/1388-98-п  # постанова КМУ від 07.09.1998 № 1388, Порядок державної реєстрації — the issuer of the combination and the owner's right to store and re-attach it. Accessed 2026-08-03"
+  - "http://www.infocar.com.ua/law_ukr/law_22.html  # ДСТУ 4278:2004, Додаток Б — the 2004 letter table (27 regions + the загальнодержавна pair ІІ) used for `superseded_systems`. Verbatim reproduction of the national standard. Accessed 2026-08-03"
+  - "https://uk.wikipedia.org/wiki/Номерні_знаки_України  # the ERA ATTRIBUTION of the four Додаток 4 columns and the 1995-2004 numeric-code system. secondary-wikipedia; accessed 2026-08-03"
+period: { start: 2021 }
+period_evidence: enabling-instrument
+period_note: >-
+  2021 is the date of the INSTRUMENT that currently carries the tables, not the
+  date the codes began. The first column of Додаток 4 is the 2004 set, which has
+  been in continuous use since ДСТУ 4278:2004 came into force on 20 February
+  2004; the annex was last amended by Наказ МВС № 354 від 27.04.2023. Per-code
+  start dates are NOT asserted — see `column_eras` for why.
+
+# ---------------------------------------------------------------------------
+# THE COLUMN QUESTION — the one place this table refuses to state a fact.
+# ---------------------------------------------------------------------------
+column_eras:
+  finding: >-
+    Додаток 4 prints four columns of літеросполуки under a SINGLE unlabelled
+    heading, "Літеросполука" (verified against the annex's own HTML: one
+    `colspan=4` header cell). The instrument therefore does NOT say that column
+    1 is the 2004 set, column 2 the 2013 set and columns 3-4 the 2021 additions.
+  what_is_claimed_here: >-
+    Only that all four pairs in a row are, today, valid літеросполуки for that
+    region. That is what the instrument says and it is all this table asserts in
+    `annex_4_codes`.
+  secondary_attribution:
+    evidence: secondary-wikipedia
+    claim: >-
+      The Ukrainian Wikipedia article attributes column 1 to the 2004
+      distribution, column 2 to a 2013 amendment of ДСТУ 4278:2004 that added
+      the НА-НХ, ІА-ІН and КА-КХ ranges, and columns 3-4 to a 2021 addition of
+      two further codes per region.
+    corroboration: >-
+      Column 1 IS corroborated independently and primarily: it matches Додаток Б
+      of ДСТУ 4278:2004 pair for pair (АК Crimea, АВ Vinnytsia, АС Volyn, …,
+      СН Sevastopol). Columns 2-4 have no primary corroboration in this pass.
+    known_divergence: >-
+      For Crimea the article gives the second-era code as "КК"; the instrument's
+      second column is "МА", and "КК" appears in the instrument as one of Kyiv
+      city's four codes. Where the article and the annex disagree, THE ANNEX IS
+      RECORDED. This divergence is the reason the era attribution is quarantined
+      into this block instead of being written onto the rows.
+  source: "https://uk.wikipedia.org/wiki/Номерні_знаки_України  # section «Коди адміністративних регіонів». secondary-wikipedia; accessed 2026-08-03"
+
+# ---------------------------------------------------------------------------
+# The region slot when it is NOT a region (Розділ III п. 1, from 12.12.2022).
+# ---------------------------------------------------------------------------
+online_registration_codes:
+  applies_to: "vehicles registered on a contract concluded in electronic form"
+  instrument: "Наказ МВС № 814 від 12.12.2022, amending Розділ III п. 1"
+  codes:
+    - code: "ЕD"
+      code_ascii: "ED"
+      script: "MIXED — Cyrillic Е U+0415 followed by LATIN D. Recorded as published; the instrument mixes scripts inside a single two-character token here and nowhere else"
+      channel: "Електронний кабінет водія (the МВС driver's e-cabinet)"
+      channel_evidence: secondary-wikipedia
+    - code: "DC"
+      code_ascii: "DC"
+      script: "Latin"
+      channel: "Електронний кабінет водія"
+      channel_evidence: secondary-wikipedia
+    - code: "DI"
+      code_ascii: "DI"
+      script: "Latin"
+      channel: "Портал «Дія»"
+      channel_evidence: secondary-wikipedia
+    - code: "PD"
+      code_ascii: "PD"
+      script: "Latin"
+      channel: "Портал «Дія»"
+      channel_evidence: secondary-wikipedia
+  note: >-
+    The instrument names the four літеросполуки and says only that they replace
+    the region code for electronically registered vehicles. WHICH channel maps
+    to WHICH pair is a Wikipedia claim, tagged per code above; the instrument
+    does not split them. What IS primary is that a plate carrying any of the
+    four encodes no geography.
+  source: "https://zakon.rada.gov.ua/laws/show/z0353-21  # Розділ III п. 1, as amended by Наказ МВС № 814 від 12.12.2022. Accessed 2026-08-03"
+
+# ---------------------------------------------------------------------------
+# What this table is NOT: the older systems, recorded so a consumer knows the
+# limits rather than guessing at them.
+# ---------------------------------------------------------------------------
+superseded_systems:
+  - system: "2004 letters"
+    period: { start: 2004 }
+    status: "still valid — column 1 of every row below"
+    extra: >-
+      ДСТУ 4278:2004 Додаток Б also carried a 28th entry with no region:
+      «ІІ — Загальнодержавна» (a nationwide, region-free pair). It is NOT in
+      Додаток 4 of the 2021 order. Ukrainian Wikipedia reports ІІ was withdrawn
+      from issue in 2006 (secondary-wikipedia). Plates bearing ІІ may still
+      exist; this table cannot decode them to a region, and should not try.
+  - system: "1995-2004 numeric"
+    period: { start: 1995, end: 2004 }
+    status: "NOT MODELLED — no primary secured in this pass"
+    description: >-
+      From 1995 to 2004 the plate carried five digits and a two-letter series,
+      with a TWO-DIGIT region code on the band under the flag (ДСТУ 3650-97,
+      named as the governing standard by постанова КМУ від 11.07.2000 № 1081
+      п. 2). The numeric codes 01-27 of Додаток 6 descend from that system. The
+      LETTER series of that era were allocated regionally on a different map
+      from today's — Ukrainian Wikipedia records, for example, КР/КО/РК for
+      Crimea and КА/КВ/КЕ/КІ/КН/КТ/ІІ/ОО for Kyiv city — so a pre-2004 pair
+      MUST NOT be decoded against `annex_4_codes`. ДСТУ 3650-97 itself was not
+      reached in this pass.
+    evidence: secondary-wikipedia
+
+# ---------------------------------------------------------------------------
+# 27 regions. `annex_4_codes` and `annex_6_numeric` are the instrument's own;
+# `annex_4_codes_ascii` is the glyph fold defined in `script:` above;
+# `region` is the annex's own Ukrainian wording, verbatim.
+# `region_en` and `iso_3166_2` are EDITORIAL cross-references added by this
+# dataset for consumers — they are not in the instrument, and the ISO codes
+# were not checked against the ISO register in this pass.
+# ---------------------------------------------------------------------------
+regions:
+  - region: "Автономна Республіка Крим"
+    region_en: "Autonomous Republic of Crimea"
+    iso_3166_2: "UA-43"
+    annex_4_codes: ["АК", "МА", "ТК", "МК"]
+    annex_4_codes_ascii: ["AK", "MA", "TK", "MK"]
+    annex_6_numeric: ["01"]
+  - region: "Вінницька область"
+    region_en: "Vinnytsia Oblast"
+    iso_3166_2: "UA-05"
+    annex_4_codes: ["АВ", "КВ", "ІМ", "РІ"]
+    annex_4_codes_ascii: ["AB", "KB", "IM", "PI"]
+    annex_6_numeric: ["02"]
+  - region: "Волинська область"
+    region_en: "Volyn Oblast"
+    iso_3166_2: "UA-07"
+    annex_4_codes: ["АС", "КС", "СМ", "ТС"]
+    annex_4_codes_ascii: ["AC", "KC", "CM", "TC"]
+    annex_6_numeric: ["03"]
+  - region: "Дніпропетровська область"
+    region_en: "Dnipropetrovsk Oblast"
+    iso_3166_2: "UA-12"
+    annex_4_codes: ["АЕ", "КЕ", "РР", "МІ"]
+    annex_4_codes_ascii: ["AE", "KE", "PP", "MI"]
+    annex_6_numeric: ["04"]
+  - region: "Донецька область"
+    region_en: "Donetsk Oblast"
+    iso_3166_2: "UA-14"
+    annex_4_codes: ["АН", "КН", "ТН", "МН"]
+    annex_4_codes_ascii: ["AH", "KH", "TH", "MH"]
+    annex_6_numeric: ["05"]
+  - region: "Житомирська область"
+    region_en: "Zhytomyr Oblast"
+    iso_3166_2: "UA-18"
+    annex_4_codes: ["АМ", "КМ", "ТМ", "МВ"]
+    annex_4_codes_ascii: ["AM", "KM", "TM", "MB"]
+    annex_6_numeric: ["06"]
+  - region: "Закарпатська область"
+    region_en: "Zakarpattia Oblast"
+    iso_3166_2: "UA-21"
+    annex_4_codes: ["АО", "КО", "МТ", "МО"]
+    annex_4_codes_ascii: ["AO", "KO", "MT", "MO"]
+    annex_6_numeric: ["07"]
+  - region: "Запорізька область"
+    region_en: "Zaporizhzhia Oblast"
+    iso_3166_2: "UA-23"
+    annex_4_codes: ["АР", "КР", "ТР", "МР"]
+    annex_4_codes_ascii: ["AP", "KP", "TP", "MP"]
+    annex_6_numeric: ["08"]
+  - region: "Івано-Франківська область"
+    region_en: "Ivano-Frankivsk Oblast"
+    iso_3166_2: "UA-26"
+    annex_4_codes: ["АТ", "КТ", "ТО", "ХС"]
+    annex_4_codes_ascii: ["AT", "KT", "TO", "XC"]
+    annex_6_numeric: ["09"]
+  - region: "Київська область"
+    region_en: "Kyiv Oblast"
+    iso_3166_2: "UA-32"
+    annex_4_codes: ["АІ", "КІ", "ТІ", "ЕЕ"]
+    annex_4_codes_ascii: ["AI", "KI", "TI", "EE"]
+    annex_6_numeric: ["10"]
+  - region: "м. Київ"
+    region_en: "Kyiv (city)"
+    iso_3166_2: "UA-30"
+    annex_4_codes: ["АА", "КА", "ТТ", "КК"]
+    annex_4_codes_ascii: ["AA", "KA", "TT", "KK"]
+    annex_6_numeric: ["11", "31"]
+  - region: "Кіровоградська область"
+    region_en: "Kirovohrad Oblast"
+    iso_3166_2: "UA-35"
+    annex_4_codes: ["ВА", "НА", "ХА", "ЕА"]
+    annex_4_codes_ascii: ["BA", "HA", "XA", "EA"]
+    annex_6_numeric: ["12"]
+  - region: "Луганська область"
+    region_en: "Luhansk Oblast"
+    iso_3166_2: "UA-09"
+    annex_4_codes: ["ВВ", "НВ", "ЕР", "ЕВ"]
+    annex_4_codes_ascii: ["BB", "HB", "EP", "EB"]
+    annex_6_numeric: ["13"]
+  - region: "Львівська область"
+    region_en: "Lviv Oblast"
+    iso_3166_2: "UA-46"
+    annex_4_codes: ["ВС", "НС", "СС", "ЕС"]
+    annex_4_codes_ascii: ["BC", "HC", "CC", "EC"]
+    annex_6_numeric: ["14"]
+  - region: "Миколаївська область"
+    region_en: "Mykolaiv Oblast"
+    iso_3166_2: "UA-48"
+    annex_4_codes: ["ВЕ", "НЕ", "ХЕ", "ХН"]
+    annex_4_codes_ascii: ["BE", "HE", "XE", "XH"]
+    annex_6_numeric: ["15"]
+  - region: "Одеська область"
+    region_en: "Odesa Oblast"
+    iso_3166_2: "UA-51"
+    annex_4_codes: ["ВН", "НН", "ОО", "ЕН"]
+    annex_4_codes_ascii: ["BH", "HH", "OO", "EH"]
+    annex_6_numeric: ["16"]
+  - region: "Полтавська область"
+    region_en: "Poltava Oblast"
+    iso_3166_2: "UA-53"
+    annex_4_codes: ["ВІ", "НІ", "ХІ", "ЕІ"]
+    annex_4_codes_ascii: ["BI", "HI", "XI", "EI"]
+    annex_6_numeric: ["17"]
+  - region: "Рівненська область"
+    region_en: "Rivne Oblast"
+    iso_3166_2: "UA-56"
+    annex_4_codes: ["ВК", "НК", "ХК", "ЕК"]
+    annex_4_codes_ascii: ["BK", "HK", "XK", "EK"]
+    annex_6_numeric: ["18"]
+  - region: "Сумська область"
+    region_en: "Sumy Oblast"
+    iso_3166_2: "UA-59"
+    annex_4_codes: ["ВМ", "НМ", "ХМ", "ЕМ"]
+    annex_4_codes_ascii: ["BM", "HM", "XM", "EM"]
+    annex_6_numeric: ["19"]
+  - region: "Тернопільська область"
+    region_en: "Ternopil Oblast"
+    iso_3166_2: "UA-61"
+    annex_4_codes: ["ВО", "НО", "ХО", "ЕО"]
+    annex_4_codes_ascii: ["BO", "HO", "XO", "EO"]
+    annex_6_numeric: ["20"]
+  - region: "Харківська область"
+    region_en: "Kharkiv Oblast"
+    iso_3166_2: "UA-63"
+    annex_4_codes: ["АХ", "КХ", "ХХ", "ЕХ"]
+    annex_4_codes_ascii: ["AX", "KX", "XX", "EX"]
+    annex_6_numeric: ["21"]
+  - region: "Херсонська область"
+    region_en: "Kherson Oblast"
+    iso_3166_2: "UA-65"
+    annex_4_codes: ["ВТ", "НТ", "ХТ", "ЕТ"]
+    annex_4_codes_ascii: ["BT", "HT", "XT", "ET"]
+    annex_6_numeric: ["22"]
+  - region: "Хмельницька область"
+    region_en: "Khmelnytskyi Oblast"
+    iso_3166_2: "UA-68"
+    annex_4_codes: ["ВХ", "НХ", "ОХ", "РХ"]
+    annex_4_codes_ascii: ["BX", "HX", "OX", "PX"]
+    annex_6_numeric: ["23"]
+  - region: "Черкаська область"
+    region_en: "Cherkasy Oblast"
+    iso_3166_2: "UA-71"
+    annex_4_codes: ["СА", "ІА", "ОА", "РА"]
+    annex_4_codes_ascii: ["CA", "IA", "OA", "PA"]
+    annex_6_numeric: ["24"]
+  - region: "Чернігівська область"
+    region_en: "Chernihiv Oblast"
+    iso_3166_2: "UA-74"
+    annex_4_codes: ["СВ", "ІВ", "ОВ", "РВ"]
+    annex_4_codes_ascii: ["CB", "IB", "OB", "PB"]
+    annex_6_numeric: ["25"]
+  - region: "Чернівецька область"
+    region_en: "Chernivtsi Oblast"
+    iso_3166_2: "UA-77"
+    annex_4_codes: ["СЕ", "ІЕ", "ОЕ", "РЕ"]
+    annex_4_codes_ascii: ["CE", "IE", "OE", "PE"]
+    annex_6_numeric: ["26"]
+  - region: "м. Севастополь"
+    region_en: "Sevastopol (city)"
+    iso_3166_2: "UA-40"
+    annex_4_codes: ["СН", "ІН", "ОН", "РН"]
+    annex_4_codes_ascii: ["CH", "IH", "OH", "PH"]
+    annex_6_numeric: ["27"]

data/data/plates/_decode/za-licence-marks.yml

@@ -0,0 +1,215 @@
+# plates/_decode/za-licence-marks.yml — South African LICENCE MARKS.
+#
+# THE SOURCE FINDING, and it decides the whole shape of plates/za.yml: South
+# Africa has TWO geographic dimensions on a plate, created by two different
+# limbs of ONE regulation, and a parse API that conflates them will be wrong
+# about half the country.
+#
+# Regulation 27 of the National Road Traffic Regulations, 2000 (GNR.225 of
+# 17 March 2000, made under the National Road Traffic Act 93 of 1996),
+# VERBATIM:
+#
+#   "27. Licence mark and licence number system
+#    (1) The MEC of each province shall, subject to subregulation (2), by
+#        notice in the Provincial Gazette, determine a licence mark for the
+#        province concerned.
+#    (2) (a) The MEC of a province shall by notice in the Provincial Gazette—
+#        (i)  allocate a licence mark to every registering authority in the
+#             province concerned, which licence mark shall consist of a
+#             combination of letters; or
+#        (ii) establish a licence number system for the province concerned
+#             which license number system shall consist of:
+#             (aa) a combination of three letters and three figures in any
+#                  sequence; or
+#             (bb) a combination of two letters, two figures and two letters
+#                  in any sequence:
+#        and the licence mark of the province concerned, referred to in sub
+#        regulation (1): Provided that vowels and the letter 'Q' shall not be
+#        used and the first letter shall not be the letter 'G'.
+#    (3) Every motor vehicle licensed in a province shall be allocated with a
+#        licence number and such licence number shall, subject to subregulation
+#        (5) and regulation 28, consist of the licence mark referred to in
+#        subregulation (2)(a)(i) and figures, or the letters and figures
+#        allocated from the licence number system referred to in subregulation
+#        (2)(a)(ii)."
+#
+# So the two dimensions are:
+#
+#   PROVINCIAL MARK  — reg 27(1). One per province, printed at the END of a
+#   licence number issued under a provincial licence NUMBER SYSTEM
+#   (reg 27(2)(a)(ii)). This is the "GP", "MP", "NC" suffix everyone knows.
+#
+#   REGISTERING-AUTHORITY MARK — reg 27(2)(a)(i). One per registering
+#   authority (a town/city licensing office), printed at the FRONT, followed
+#   by figures. This is the Western Cape "CA 123-456" and the pre-2023
+#   KwaZulu-Natal "ND 12345" style, and it is the DIRECT DESCENDANT of the
+#   pre-1994 four-province town-code system: those codes were allocated by
+#   the old provincial administrations and survived the 1994 reorganisation
+#   inside the two provinces that never switched to a suffix system.
+#
+# The two are mutually exclusive per province — reg 27(2)(a) is an "or" — and
+# a province may switch by a fresh notice under reg 27(4). KwaZulu-Natal did
+# exactly that in December 2023.
+#
+# WHAT IS AND IS NOT PINNED HERE (read before trusting a row):
+#   * The reg 27 text above is PRIMARY and was read twice, in the consolidated
+#     regulations and again in a Government Gazette reproduction (GG 37542,
+#     General Notice 287 of 9 April 2014), which agree word for word.
+#   * The reg 27(1) determinations themselves are NINE SEPARATE PROVINCIAL
+#     GAZETTE NOTICES. Three of the nine marks below are pinned to a
+#     government publication (FS, GP, WP). The other six are NOT: they are
+#     carried on `secondary-wikipedia` evidence and are flagged row by row.
+#     No provincial gazette index with full-text search was reachable in this
+#     pass (SAFLII is behind Cloudflare, opengazettes.org.za's search has been
+#     retired, gazettes.africa exposes no query endpoint) — recorded as the
+#     single largest gap in the South African pass.
+#   * NO complete registering-authority mark table is published anywhere this
+#     pass could reach. The Western Cape rows below are the marks the Western
+#     Cape Government itself prints as worked examples on its own fee table;
+#     they are a floor, not a census. eNaTIS publishes a "live vehicle
+#     population per registering authority" series that would settle it, and
+#     natis.gov.za refused every request (HTTP 403). Recorded as a gap.
+jurisdiction: za
+topic: licence-marks
+authority:
+  name: "MEC responsible for road traffic in each province, under reg. 27 of the National Road Traffic Regulations, 2000 (GNR.225 of 17 March 2000)"
+  url: "https://www.gov.za/sites/default/files/gcis_document/201409/37542gen287.pdf"
+sources:
+  - "https://disasterlaw.ifrc.org/sites/default/files/media/disaster_law/2021-06/%20ROAD%20TRAFFIC%20REGULATIONS,%202000.pdf  # National Road Traffic Regulations 2000 consolidated to GNR.359 of 2 May 2010 — reg 27(1),(2),(3),(4),(5) verbatim; accessed 2026-08-02"
+  - "https://www.gov.za/sites/default/files/gcis_document/201409/37542gen287.pdf  # Government Gazette 37542, General Notice 287 of 9 April 2014 (Department of Transport, publication of proposed amendments FOR COMMENT) — reproduces reg 27(1)-(5) and reg 35 in identical words; accessed 2026-08-02"
+  - "https://www.policeroadstransport.fs.gov.za/wp-content/uploads/2012/09/Personalised-licence-number-system-for-the-Free-State-2002.pdf  # Free State Provincial Notice 52 of 2002, Provincial Gazette 25 of 9 April 2002, para 2(1): personalised numbers 'followed by the letters FS' — the FS mark, primary; accessed 2026-08-02"
+  - "https://cmbinary.gauteng.gov.za/Media?path=transport/Documents/Documents/GP%20Application%20Form%20-%20Personalised%20Number%20Plate.pdf&Item=658&Type=Documents&Location=/transport  # Gauteng Province form PRN1-GP, 'Application for special/personalised registration number for motor vehicle': the registration-number field is pre-printed with 'G P' — the GP mark, primary; accessed 2026-08-02"
+  - "https://www.westerncape.gov.za/mobility/service/applying-special-motor-vehicle-number-plates  # Western Cape Government: 'Personalised number plates contain the letters WP (Western Province) at the end of the number plate' + the discrete-number fee table whose worked examples are the CY/CW/CG/CK/CB/CBY/CFM registering-authority marks; accessed 2026-08-02"
+  - "https://en.wikipedia.org/wiki/Vehicle_registration_plates_of_South_Africa  # FINDING AID + the six unpinned provincial marks (EC, L, MP, NC, NW, ZN) and the Port Shepstone NPS->NSC change; every fact taken from it is tagged secondary-wikipedia below; accessed 2026-08-02"
+period: { start: 2000 }
+period_evidence: instrument-in-force
+period_note: >-
+  2000 is the year of the instrument that CREATES the licence-mark power read
+  here (GNR.225 of 17 March 2000), not the year the marks came into use. The
+  registering-authority marks are decades older — the Cape "C" family and the
+  Natal "N" family were allocated by the pre-1994 provincial administrations
+  and were carried across the 1994 reorganisation unchanged — and the
+  provincial marks were determined in the second half of the 1990s under the
+  Road Traffic Act 29 of 1989 and its provincial ordinances. None of those
+  earlier instruments was pinned in this pass. A decode of a physical plate is
+  therefore period-agnostic: these marks do not date a plate.
+
+# ---------------------------------------------------------------------------
+# 1. PROVINCIAL MARKS — reg 27(1). Printed at the END of the licence number.
+#    `system` records which limb of reg 27(2)(a) the province chose, because
+#    that, not the mark, is what determines the serial grammar.
+# ---------------------------------------------------------------------------
+maximal_munch: false
+provincial_marks:
+  - code: EC
+    name: "Eastern Cape"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: secondary-wikipedia
+    note: "Mark not traced to its provincial gazette notice in this pass."
+  - code: FS
+    name: "Free State"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: authority-publication
+    note: >-
+      PRIMARY. Free State Provincial Notice 52 of 2002 para 2(1)(a)-(b)
+      requires a personalised number to be "followed by the letters FS", and
+      Provincial Notice 51 of 2002 Schedule 3 para 4 requires the retro-
+      reflective sheeting to carry "the Province by way of the letters 'FS'
+      inside a 12 mm circle interspersed throughout the sheeting".
+  - code: GP
+    name: "Gauteng"
+    system: >-
+      reg 27(2)(a)(ii)(aa) three letters and three figures; a two-letter /
+      two-figure / two-letter issue under reg 27(2)(a)(ii)(bb) is reported
+      from 2023 (secondary-wikipedia — see plates/za.yml#za-gp-standard-2l2f2l)
+    evidence: authority-publication
+    note: >-
+      PRIMARY. Gauteng Province form PRN1-GP pre-prints "G P" in each of the
+      three registration-number choice fields.
+  - code: L
+    name: "Limpopo"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: secondary-wikipedia
+    note: >-
+      The only ONE-LETTER provincial mark, which is why plates/za.yml writes
+      it with the pattern escape (\L) rather than as the letter token. The
+      province was named Northern Province until 2003 and the mark it used
+      before the rename was not established in this pass — recorded gap.
+  - code: MP
+    name: "Mpumalanga"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: secondary-wikipedia
+    note: "Mark not traced to its provincial gazette notice in this pass."
+  - code: NC
+    name: "Northern Cape"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: secondary-wikipedia
+    note: "Mark not traced to its provincial gazette notice in this pass."
+  - code: NW
+    name: "North West"
+    system: "reg 27(2)(a)(ii)(aa) — three letters and three figures"
+    evidence: secondary-wikipedia
+    note: "Mark not traced to its provincial gazette notice in this pass."
+  - code: WP
+    name: "Western Cape"
+    system: >-
+      reg 27(2)(a)(i) — registering-authority marks plus figures. WP is
+      therefore NOT a suffix on ordinary Western Cape plates: it appears only
+      on personalised numbers issued under reg 28.
+    evidence: authority-publication
+    note: >-
+      PRIMARY. Western Cape Government, verbatim: "Personalised number plates
+      contain the letters WP (Western Province) at the end of the number
+      plate." WP stands for the historic Western Province, not for the
+      province's own name.
+  - code: ZN
+    name: "KwaZulu-Natal"
+    system: >-
+      reg 27(2)(a)(ii)(bb) two letters, two figures and two letters, from
+      1 December 2023; previously reg 27(2)(a)(i) registering-authority marks
+      plus figures
+    evidence: secondary-wikipedia
+    note: >-
+      The 1 December 2023 switch itself IS pinned to a government publication
+      (SAnews.gov.za, the Government Communication and Information System) —
+      it is the two-letter mark "ZN" that rests on Wikipedia here.
+
+# ---------------------------------------------------------------------------
+# 2. REGISTERING-AUTHORITY MARKS — reg 27(2)(a)(i). Printed at the FRONT,
+#    followed by figures. INCOMPLETE BY CONSTRUCTION: see the header. Every
+#    row here is a mark a government page prints as its own worked example.
+# ---------------------------------------------------------------------------
+registering_authority_marks_note: >-
+  This is a floor, not a census, and a consumer MUST NOT treat an unlisted
+  C-initial or N-initial mark as invalid. The mechanism is the sourced fact:
+  a Western Cape mark is two or three letters beginning with C, a pre-2023
+  KwaZulu-Natal mark is two or three letters beginning with N, and both are
+  followed by up to six figures. The full tables live in Western Cape and
+  KwaZulu-Natal provincial gazettes that this pass could not reach.
+registering_authority_marks:
+  - { code: CA,  province: WP, name: "Cape Town", evidence: corroboration-only, note: "The best-known South African mark; widely printed as 'CA 123-456'. Not pinned to a Western Cape gazette in this pass." }
+  - { code: CY,  province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CY 6'." }
+  - { code: CW,  province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CW 16'." }
+  - { code: CG,  province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CG 131'." }
+  - { code: CK,  province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CK 1441'." }
+  - { code: CB,  province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CB 131'." }
+  - { code: CBY, province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked examples 'CBY 3' and 'CBY 15' — a THREE-letter registering-authority mark, which is why plates/za.yml admits 1-2 letters after the leading C." }
+  - { code: CFM, province: WP, name: "unresolved (Western Cape)", evidence: authority-publication, note: "Western Cape Government fee table, worked example 'CFM 2332' — three-letter mark." }
+  - { code: CAA, province: WP, name: "Cape Town (second series)", evidence: secondary-wikipedia, note: "Reported introduced 13 April 2019 when the CA combinations were exhausted. Not pinned to a gazette." }
+  - { code: CAW, province: WP, name: "George (first series)", evidence: secondary-wikipedia, note: "Reported exhausted in late 2019." }
+  - { code: CAG, province: WP, name: "George (second series)", evidence: secondary-wikipedia, note: "Reported introduced late 2019 when CAW was exhausted." }
+  - { code: NPS, province: ZN, name: "Port Shepstone (former)", evidence: secondary-wikipedia, note: "Reported replaced by NSC on 30 June 2020." }
+  - { code: NSC, province: ZN, name: "Port Shepstone", evidence: secondary-wikipedia, note: "Reported in use from 30 June 2020 until the province moved to the ZN system on 1 December 2023." }
+
+# ---------------------------------------------------------------------------
+# 3. NON-GEOGRAPHIC TERMINAL LETTERS — the trap this table exists to prevent.
+#    These look like provincial marks and are not: they are issuance classes
+#    under reg 27(5) and reg 71(2), and they are modelled as SERIES in
+#    plates/za.yml, never decoded as geography.
+# ---------------------------------------------------------------------------
+not_geographic:
+  - { token: G,  meaning: "Department of State — reg 27(5)(a)(ii): 'the letter G followed by two letters, three figures, and the letter G'. Also the reason the reg 27(2) proviso forbids G as the FIRST letter of an ordinary licence number.", series: "plates/za.yml#za-government-g" }
+  - { token: B,  meaning: "South African Police Service — reg 27(5)(b): 'three letters, three figures, followed by the letter B'.", series: "plates/za.yml#za-police-b" }
+  - { token: D,  meaning: "Diplomatic/consular and international organisations — reg 27(5)(d): the grammar is set by the Director-General of Foreign Affairs and is not published, but the number 'shall end in the letter D'.", series: "plates/za.yml#za-diplomatic-d" }
+  - { token: ZK, meaning: "Set aside for the use by the King of the Zulu Nation — reg 27(5)(c), as substituted by GNR.865 of 28 September 2007: 'the letters ZK followed by figures or letters or combination of figures and letters'. A PREFIX, not a suffix.", series: "plates/za.yml#za-zulu-royal-zk" }
+  - { token: A,  meaning: "Motor trade (dealer) number — reg 71(2)(a): 'the letter A followed by two letters, three figures and the licence mark of the province concerned'. A dealer number therefore carries a provincial mark AND a leading A.", series: "plates/za.yml#za-dealer-a" }

data/data/plates/_meta/classes.yml

@@ -0,0 +1,26 @@
+# The controlled vocabulary of plate classes (PRD-PLATES §2.3). A class is a
+# LEGAL/ADMINISTRATIVE issuance category, not a design variant. A
+# jurisdiction's variant becomes its OWN SERIES iff format OR design OR
+# period differs from the standard series; a color-only variant of the same
+# format+period is a sub-entry on the standard series. Grow this file by PR
+# with a definition — never ad hoc in data files.
+standard:       the default series issued to private road vehicles
+motorcycle:     reduced-size series for motorcycles where format/design differs
+moped:          insurance/registration plates for mopeds (NL/DE small plates)
+trailer:        trailers and semi-trailers where separately serialized
+diplomatic:     diplomatic corps (embassy) issuance, usually its own decode
+consular:       consular corps where distinct from diplomatic
+temporary:      short-validity plates (transit, awaiting registration)
+export:         plates for vehicles leaving the jurisdiction permanently
+dealer:         trade/garage plates bound to a business, not a vehicle
+historic:       vintage/oldtimer regimes (German H, ES historico)
+taxi:           for-hire vehicles where separately serialized or colored
+government:     civil government fleets with distinct series
+military:       armed-forces registration systems
+police:         police fleets where distinct from government
+electric:       EV-distinct plates or suffixes (German E, CN green plates)
+seasonal:       validity-window plates (German Saisonkennzeichen)
+agricultural:   farm vehicles/equipment where separately serialized
+personalized:   owner-chosen serials inside an official frame
+sport:          competition/motorsport vehicles registered under their own series, distinct from specialty (an optional design on an ordinary serial) and from historic (a sports vehicle may be new) - CZ vyhlaska 343/2014 Sb. par. 26 odst. 5, SK zakon 8/2009 Z. z. par. 127 ods. 9
+specialty:      optional-design programs on standard serials (US state programs)