ISO-landcodes en onderindelingscodes: een praktische gids

ISO-landcodes zijn een van die standaarden die iedereen gebruikt en bijna niemand leest. Ze lijken een opgelost probleem — twee letters, één land, klaar — tot een formulier een legitiem gebied afwijst, een rapport twee tabellen samenvoegt waarvan de landkolommen in verschillende formaten zijn geschreven, of een dropdown een vermelding bevat die jaren geleden is komen te vervallen.

Dit artikel legt de drie vormen van landcode uit, waarom ze vermengen stille breuk veroorzaakt, hoe onderindelingscodes eronder passen, en wat je opslaat en valideert in een systeem dat moet blijven werken terwijl de lijst verandert.

De drie vormen van een landcode

De internationale standaard voor landcodes definieert drie parallelle representaties van dezelfde set landen en gebieden.

De tweelettervorm domineert in software. Hij is kort, het is wat de meeste diensten van derden verwachten, en hij past comfortabel in een kolom met vaste breedte. De drielettervorm is duidelijker wanneer een mens hem buiten context leest, en daarom overleeft hij in statistische en financiële rapportage. De numerieke vorm heeft één voordeel dat makkelijk over het hoofd wordt gezien: cijfers zijn taalneutraal, en een numerieke code is enigszins robuuster tegen bepaalde soorten transcriptiefouten dan een korte lettercode, omdat hij nooit botst met een gewoon woord.

Alle drie beschrijven dezelfde set entiteiten. Precies daarom veroorzaken ze problemen: ze zijn uitwisselbaar in betekenis en niet uitwisselbaar in een tekenreeksvergelijking.

Waarom het vermengen van de codes joins geruisloos breekt

Een join tussen twee tabellen op een landkolom werkt alleen wanneer beide kolommen dezelfde vorm gebruiken. Als het ene systeem de tweelettercode opslaat en het andere de drielettercode, levert de join niets op, en niets is precies wat dit duur maakt — een leeg resultaat is makkelijk te verwarren met ontbrekende gegevens in plaats van een formaatverschil.

Tekenreeksvergelijking maakt het erger. Tweeletter- en drielettercodes bestaan beide uit hoofdletters, dus een kolom die als tekst is getypeerd accepteert elk van beide zonder klagen. Een kolom van drie tekens accepteert drielettercodes en kapt niets af, maar accepteert ook een tweelettercode die is opgevuld of as-is opgeslagen, en downstream-code die nooit twee tekens verwachtte kan zich vreemd gedragen zonder fout.

Het middel is om één keer, op één plek te beslissen wat de canonieke vorm is, en bij elke grens te converteren. Sla één vorm op, accepteer meerdere bij invoer, en normaliseer onmiddellijk. Documenteer de keuze naast de kolom, want de volgende persoon die een integratie toevoegt, raadt het niet.

Zijn onderindelingscodes dezelfde als die lokale instanties gebruiken?

Nee, en ze als één set behandelen is een veelvoorkomende bron van mismatches. Het onderindelingsdeel van de landcodestandaard beschrijft de belangrijkste bestuurlijke indelingen onder het landniveau, en het wordt opgebouwd door de landcode te combineren met een verdere code voor de indeling, gescheiden door een koppelteken. Dat geeft een wereldwijd unieke identificatie voor een indeling, wat werkelijk nuttig is wanneer gegevens grenzen overschrijden.

Lokale codelijsten zijn andere dingen. Statistische bureaus, postoperatoren, belastingautoriteiten en verkiezingsorganen onderhouden elk hun eigen indelingen en hun eigen codes voor hun eigen doeleinden. Die lijsten overlappen met de internationale en vallen er niet mee samen: ze kunnen namen gebruiken die de standaard niet kent, regio’s anders splitsen of samenvoegen, en volgens hun eigen schema’s bijwerken.

Het praktische gevolg is dat je niet moet aannemen dat een waarde uit een lokaal systeem een geldige internationale onderindelingscode is, en dat je geen internationale code moet sturen naar een systeem dat een lokale verwacht. Houd de twee uit elkaar, en bewaar de landcode naast elke onderindelingswaarde zodat het paar interpreteerbaar blijft.

Moet je ooit je eigen codes verzinnen?

Nee. Verzonnen codes zijn niet te onderscheiden van geldige, en dat is juist het probleem. Een plausibel uitziende tweeletterige reeks die toevallig met geen enkel land overeenkomt, slaagt voor een tekencontrole, sorteert netjes tussen de echte vermeldingen, en faalt ergens ver weg — bij een verzendlabel, een belastingberekening, of een analytische samenvoeging waarvan de totalen geruisloos ophouden op te tellen.

Twee gewoonten voorkomen de meeste schade. Valideer landcodes tegen een echte, onderhouden lijst in plaats van een patroon, en behandel elke waarde die niet in de lijst staat als een probleem om naar boven te halen in plaats van een waarde om op te slaan. Waar een dataset werkelijk een bucket nodig heeft voor iets onbekends — een niet-vertrouwde import, een gebruiker die niet wilde antwoorden — gebruik dan een expliciete, gedocumenteerde sentinel die niet met een landcode kan worden verward, en houd die buiten elke kolom die echte codes hoort te bevatten.

Waar komen verouderde of onbekende codes vandaan?

De standaard ligt niet vast. Vermeldingen worden toegevoegd, hernoemd en ingetrokken naarmate de wereld verandert, en een systeem dat jaren draait verzamelt waarden uit meerdere edities. Post komt binnen met de code die de database van de afzender kende; spreadsheets circuleren met codes die geldig waren toen ze werden geëxporteerd.

Drie situaties zijn het plannen waard. Een code die is ingetrokken maar nog in oude records voorkomt. Een code die in de standaard bestaat maar niet in je dropdown, omdat je lijst ooit is opgebouwd en nooit vernieuwd. En een waarde die helemaal geen code is, omdat een mens een landnaam typte in een veld dat er een wilde.

De behandeling verschilt per geval. Historische records kunnen hun oorspronkelijke waarde behouden terwijl nieuwe records een actuele gebruiken, mits de mapping ertussen ergens is opgeslagen. Een code die in je lijst ontbreekt mag niet als ongeldig worden afgewezen, aangezien de fout waarschijnlijk eerder in de lijst dan in de waarde zit. En vrij-tekst landnamen mogen helemaal nooit een codekolom bereiken, wat de gids over adresvalidatie en -normalisatie behandelt als deel van het bredere opschoningsprobleem.

Voor ontwikkelaars: opslaan, vermelden en terugvallen

Kies één canonieke vorm voor opslag — voor de meeste applicaties de tweelettercode — en wees er streng over binnen je eigen systeem. Houd de conversie in één helper zodat een verandering van gedachten een verandering op één plek is.

Kies één bron voor de lijst die dropdowns, validatie en weergave gebruiken, en vernieuw die bewust. Een codelijst die op meerdere plekken met de hand wordt bewerkt, raakt uit de pas met zichzelf, en het zichtbare symptoom is een gebruiker in een land dat het formulier niet aanbiedt.

Beslis wat “onbekend” in je schema betekent voordat je het nodig hebt. Een lege waarde, een gedocumenteerde sentinel en een null zijn drie verschillende uitspraken, en slechts één ervan is juist voor welk veld dan ook. Wat je ook kiest, zorg dat het niet met een echte code kan worden verward door een join, een vergelijking of een labelgenerator.

Log ten slotte wat je hebt afgewezen. Wanneer een landcode de validatie niet haalt, noteer dan de waarde en de versie van de lijst, niet het hele record. Dat is de enige betrouwbare manier om een slechte regel van een slechte invoer te onderscheiden, en het houdt persoonlijke gegevens uit je diagnostiek. Als het veld ook een telefoonnummer voedt, geldt hetzelfde principe voor de kiesschijfprefix, zoals de gids over telefoonprefixen en plaatsmatching beschrijft.

Volgende stappen

Zoek elke kolom in je schema die een land bevat en controleer of ze allemaal dezelfde vorm gebruiken; een snelle groeperingsquery over de afzonderlijke waarden toont elke kolom met een mengeling. Bevestig daarna dat je validatielijst uit één bron kan worden vernieuwd in plaats van op meerdere plekken te worden bewerkt. Open om de codes in context te zien een landpagina en vergelijk hoe het land daar wordt geïdentificeerd met hoe je eigen gegevens het noemen. Als je voorbeeldrecords nodig hebt om de conversie tussen vormen te testen, genereer dan een batch in de adresgenerator en voer de codes door je normalisatiehelper. Die records bevatten alleen synthetische waarden, dus de codes erin zijn oefenmateriaal — geen bezorgbare adressering en geen uitspraak over iemands woonplaats.