Internationaal adresformaat: regelvolgorde en veldnamen

Een internationaal adresformaat is niet één formaat. Het is een familie van conventies die het oneens zijn over wat voorop staat, hoe een indeling heet en of de naam van de ontvanger boven of onder het gebouw staat. Iedereen die een formulier, een label of een bedrukte envelop maakt, komt die meningsverschillen snel tegen, en de goedkoopste oplossing — één sjabloon met een paar optionele regels — houdt op te werken zodra een tweede land aan de lijst wordt toegevoegd.

Dit artikel behandelt hoe adressen wereldwijd daadwerkelijk worden geordend, welke velden variëren, waarom het schrift ertoe doet, en hoe je de gegevens zo modelleert dat weergavebeslissingen gescheiden blijven van opslagbeslissingen.

Twee richtingen om een adres te schrijven

Adressen worden op sommige plaatsen van de kleinste eenheid naar buiten geschreven en op andere van de grootste naar binnen, en de twee gewoonten produceren gespiegelde regelvolgordes.

In een groot deel van Oost-Azië loopt een adres traditioneel van de grote eenheid naar de kleine: eerst land of provincie, dan stad of wijk, dan district, dan straat, dan huisnummer, dan de unit. Westerse conventies lopen de andere kant op: huisnummer en straat, dan stad, dan regio, dan postcode, dan land. Geen van beide volgordes is logischer; elk groepeert informatie zoals de lokale postdienst en de lokale lezer het verwachten.

Internationale post voegt daar nog een conventie aan toe. Omdat het bestemmingsland is wat sorteermachines als eerste nodig hebben, staat het traditioneel als laatste regel, alleen, in hoofdletters of anderszins prominent. Dat is een routeringsconventie en geen dataregel, en het is de reden waarom bedrukte enveloppen er vaak heel anders uitzien dan de volgorde waarin een formulier de velden verzamelt.

Kan één sjabloon elk land aan?

Alleen slecht. Een sjabloon hardcodeert een aanname over welke velden bestaan, welke op dezelfde regel staan en in welke volgorde ze verschijnen, en die aannames zijn precies wat tussen landen verandert.

Een enkel vast sjabloon zet een huisnummer vóór een straatnaam in een land dat het erna zet, voegt een komma in waar de lokale conventie een markeringskarakter heeft, of reserveert een regel voor een deelstaat die het adres nooit gebruikt. Overweeg wat er in de praktijk gebeurt: sommige landen laten een indeling gewoonlijk helemaal weg en lokaliseren een adres in plaats daarvan via plaats en postcode, zodat een verplicht regiovelden gebruikers dwingt de plaats te herhalen of een benadering te kiezen. Anderen gebruiken een indelingsniveau dat geen equivalent in het sjabloon heeft, en de naam belandt in welk veld dan ook vrij is.

De oplossing is kleiner dan het klinkt: houd de gegevens compleet en laat de weergavelaag de regelvolgorde bepalen. De ordening hoort bij de presentatie, en geen enkel veld zou ervan afhankelijk moeten zijn.

Wat is het verschil tussen een staat, een provincie en een prefectuur?

Het zijn allemaal bestuurlijke indelingen van het eerste niveau, en het woord ervoor verschilt per land — staat, provincie, prefectuur, regio, kanton, gouvernement, emiraat, oblast. Het label is belangrijk voor de lezer en helemaal niet voor het datamodel, en daarom veroorzaakt het elk ervan “Staat” noemen meer problemen dan het oplost.

De problemen zijn concreet. Een gebruiker in een land dat de indeling anders noemt, moet raden wat het formulier bedoelt. Een supportscript dat records op staat filtert, sluit records uit waarvan de indeling in het bronsysteem onder een andere naam leeft. Een validatieregel die tegen een lijst met Amerikaanse staten wordt gecontroleerd, wijst vrijwel elk adres buiten de Verenigde Staten af.

Houd het veld generiek in het schema en lokaliseer het label op het moment van weergeven. Bewaar de waarde samen met de landcode, aangezien een indelingsnaam alleen betekenisvol is naast het land waartoe die behoort; twee landen kunnen een indelingsnaam delen en verschillende plaatsen bedoelen. De familieverwantschap tussen deze codes wordt beschreven in de gids over ISO-land- en onderindelingscodes.

Schrift, transliteratie en het stille falen van alleen-Latijnse velden

Veel adressen zijn in een ander schrift dan het Latijnse geschreven. Sommige bestemmingslanden eisen het lokale schrift voor binnenlandse bezorging en accepteren een geromaniseerde versie voor internationale routering; andere verwachten de geromaniseerde vorm op inkomende post. Geen van beide regelingen is universeel.

Er gaan twee dingen mis wanneer een systeem Latijnse tekens aanneemt. Het eerste is ronduit afwijzing: een tekenset die niet-Latijnse letters uitsluit, maakt van een geldig adres een fout, en de gebruiker kan het niet repareren omdat het adres correct is. Het tweede is stiller — een veld dat de tekens accepteert maar ze normaliseert, translitereert of afkapt, zodat de opgeslagen waarde niet meer overeenkomt met wat de gebruiker typte en een latere vergelijking faalt.

Tekens zijn niet het enige gevaar. Sommige schriften worden zonder spaties tussen de adrescomponenten geschreven, zodat een parser die op witruimte splitst één enorm token vindt in plaats van zes velden. Andere gebruiken een markering tussen de straatnaam en het nummer waar Latijnse conventies een spatie of een komma gebruiken. De lengte is ook niet uniform: een geromaniseerd adres is meestal langer dan het origineel, dus een veld dat op het lokale schrift is afgestemd kan te klein zijn voor zijn eigen transliteratie.

Omgaan met gebouwnamen, unitnummers en districten

Echte adressen bevatten eenheden die sjablonen zelden voorzien: appartementen, verdiepingen, blokken, torens, ingangsnummers, gebouwnamen, subdistrictnamen, en aanwijzingen in de vorm van een herkenningspunt. De lokale lijst van deze identificaties verschilt evenveel als de indelingsnamen.

Twee regels houden ze beheersbaar. Verzamel de unitdetails in hun eigen veld in plaats van ze aan de straatregel toe te voegen, zodat de straat behouden blijft voor parsing en geocoding. En wanneer de adressen van een land gewoonlijk een niveau bevatten dat je sjabloon mist — een district onder de stad, een gebouwnaam boven de straat — voeg dan een veld toe in plaats van samen te voegen. Een veld met één betekenis is goedkoop; een veld dat “wat er verder nog was” betekent, is waar datakwaliteit komt te overlijden.

Voor ontwikkelaars: één veld, één betekenis

Het ontwerpprincipe dat contact met de meeste landen overleeft, is het minst slimme: geef elk stukje adresinformatie zijn eigen veld met één betekenis, en laat een veldnaam nooit een land impliceren.

Praktisch betekent dat een landcodeveld, een indelingsveld dat geen “staat” heet, afzonderlijke velden voor district, plaats, straat, huisnummer en unitdetails, een postcodeveld, en een vrije regel voor informatie die in geen ervan past. Houd de velden optioneel in het schema en schrijf voor wat je per land nodig hebt op het moment van validatie, waar het land bekend is.

Voeg een weergavedefinitie per land toe, gescheiden van de gegevens: de volgorde van regels, welke velden worden samengevoegd, of de indeling in het adresblok verschijnt, en waar de postcode komt. Die scheiding laat je een land toevoegen door één definitie te bewerken in plaats van de formulierlogica opnieuw te openen. Het betekent ook dat een fout in de lay-out opgeslagen gegevens niet kan beschadigen.

Wees ten slotte voorzichtig met samenvoegen. Als je een adres van één regel voor een API-aanroep bouwt, maak het scheidingsteken dan ook deel van de weergavedefinitie, want overal met een komma samenvoegen levert een adres op dat alleen correct leest in de landen die komma’s gebruiken.

Volgende stappen

Kies drie landen die je daadwerkelijk bedient en schrijf met de hand uit hoe elk van hen dezelfde informatie ordent. Waar de drie het oneens zijn, heb je de naden gevonden waarop je sjabloon zal breken. Genereer daarna één adres per land in de adresgenerator en plak elk in je formulier om te zien of de lay-out nog klopt; de gids over adresgegevens in testfixtures legt uit hoe je die voorbeelden reproduceerbaar houdt. Houd in gedachten wat die voorbeelden zijn: gegenereerde waarden in de vorm van echte adressen, bedoeld voor testen en niet voor bezorging, en zonder enige aanwijzing over waar iemand daadwerkelijk woont.