Codici ISO di paese e suddivisione: una guida pratica

I codici ISO di paese sono uno di quegli standard che tutti usano e quasi nessuno legge. Sembrano un problema risolto — due lettere, un paese, fatto — finché un modulo non respinge un territorio legittimo, un report non unisce due tabelle le cui colonne del paese erano scritte in formati diversi, o un menu a tendina non viene distribuito con una voce che ha smesso di esistere anni fa.

Questo articolo spiega le tre forme del codice di paese, perché mescolarle causa rotture silenziose, come si inseriscono i codici di suddivisione al di sotto, e che cosa memorizzare e validare in un sistema che deve continuare a funzionare mentre l’elenco cambia.

Le tre forme di un codice di paese

Lo standard internazionale per i codici di paese definisce tre rappresentazioni parallele dello stesso insieme di paesi e territori.

La forma a due lettere domina nel software. È breve, è ciò che si aspettano la maggior parte dei servizi di terze parti e sta comodamente in una colonna a larghezza fissa. La forma a tre lettere è più chiara quando la legge un essere umano fuori contesto, ed è per questo che sopravvive nella reportistica statistica e finanziaria. La forma numerica ha un vantaggio facile da trascurare: le cifre sono neutrali rispetto alla lingua, e un codice numerico è un po’ più robusto di un codice breve a lettere contro certi tipi di errore di trascrizione, perché non entra mai in collisione con una parola comune.

Tutte e tre descrivono lo stesso insieme di entità. È proprio per questo che causano problemi: sono intercambiabili nel significato e non intercambiabili in un confronto tra stringhe.

Perché mescolare i codici rompe le unioni in silenzio

Un’unione tra due tabelle su una colonna del paese funziona solo quando entrambe le colonne usano la stessa forma. Se un sistema memorizza il codice a due lettere e un altro memorizza il codice a tre lettere, l’unione non restituisce nulla, e proprio il nulla è ciò che rende questo costoso — un risultato vuoto è facile da scambiare per dati mancanti anziché per una discordanza di formato.

Il confronto tra stringhe peggiora la situazione. I codici a due e a tre lettere sono entrambi lettere maiuscole, quindi una colonna tipizzata come testo accetta l’uno o l’altro senza lamentarsi. Una colonna di tre caratteri accetta i codici a tre lettere e non tronca nulla, ma accetta anche un codice a due lettere riempito o memorizzato così com’è, e il codice a valle che non si aspettava due caratteri può comportarsi in modo strano senza un errore.

Il rimedio è decidere una volta, in un unico posto, qual è la forma canonica, e convertire a ogni confine. Memorizza una forma, accettane diverse in input e normalizza immediatamente. Documenta la scelta accanto alla colonna, perché la prossima persona che aggiungerà un’integrazione non la indovinerà.

I codici di suddivisione sono gli stessi che usano le agenzie locali?

No, e trattarli come un unico insieme è una fonte comune di discordanze. La parte relativa alle suddivisioni dello standard dei codici di paese descrive le principali divisioni amministrative al di sotto del livello del paese, ed è costruita combinando il codice del paese con un ulteriore codice per la divisione, separati da un trattino. Ne risulta un identificatore globalmente unico per una divisione, cosa davvero utile quando i dati attraversano i confini.

Gli elenchi di codici locali sono cose diverse. Agenzie statistiche, operatori postali, autorità fiscali e organismi elettorali mantengono ciascuno le proprie divisioni e i propri codici per i propri fini. Quegli elenchi si sovrappongono a quello internazionale e non coincidono con esso: possono usare nomi che lo standard non ha, dividere o unire regioni in modo diverso e aggiornarsi secondo i propri calendari.

La conseguenza pratica è che non dovresti presumere che un valore proveniente da un sistema locale sia un codice di suddivisione internazionale valido, e non dovresti inviare un codice internazionale a un sistema che ne aspetta uno locale. Tieni separati i due, e memorizza il codice del paese accanto a qualsiasi valore di suddivisione affinché la coppia resti interpretabile.

Dovresti mai inventare i tuoi codici?

No. I codici inventati sono indistinguibili da quelli validi, ed è questo il problema. Una stringa di due lettere dall’aspetto plausibile che non corrisponde a nessun paese supererà un controllo di caratteri, si ordinerà ordinatamente tra le voci reali e fallirà da qualche parte lontano — su un’etichetta di spedizione, in un calcolo fiscale o in un aggregato analitico i cui totali smettono silenziosamente di quadrare.

Due abitudini prevengono la maggior parte del danno. Valida i codici di paese rispetto a un elenco reale e mantenuto anziché a un pattern, e tratta qualsiasi valore che non sia nell’elenco come un problema da segnalare anziché un valore da memorizzare. Dove un dataset ha davvero bisogno di un contenitore per qualcosa di sconosciuto — un’importazione non attendibile, un utente che ha rifiutato di rispondere — usa una sentinella esplicita e documentata che non possa essere confusa con un codice di paese, e tienila fuori da qualsiasi colonna che dovrebbe contenere codici reali.

Da dove vengono i codici obsoleti o sconosciuti?

Lo standard non è congelato. Le voci vengono aggiunte, rinominate e ritirate mentre il mondo cambia, e un sistema in funzione da anni accumula valori provenienti da diverse edizioni. La posta arriva con il codice che il database del mittente conosceva; i fogli di calcolo circolano con codici che erano validi quando sono stati esportati.

Tre situazioni meritano di essere pianificate. Un codice che è stato ritirato ma compare ancora in vecchi record. Un codice che esiste nello standard ma non nel tuo menu a tendina, perché il tuo elenco è stato costruito una volta e mai aggiornato. E un valore che non è affatto un codice, perché un essere umano ha digitato il nome di un paese in un campo che ne voleva uno.

La gestione è diversa in ciascun caso. I record storici possono conservare il valore originale mentre i nuovi record usano uno attuale, a condizione che la mappatura tra essi sia memorizzata da qualche parte. Un codice assente dal tuo elenco non dovrebbe essere respinto come non valido, poiché il difetto è più probabilmente nell’elenco che nel valore. E i nomi di paese in testo libero non dovrebbero mai raggiungere una colonna di codici, cosa che la guida alla validazione e normalizzazione degli indirizzi tratta come parte del più ampio problema di pulizia.

Per gli sviluppatori: memorizzare, elencare e ricadere

Scegli una forma canonica per la memorizzazione — per la maggior parte delle applicazioni il codice a due lettere — e sii severo al riguardo dentro il tuo sistema. Mantieni la conversione in un unico helper, così un cambio di idea è un cambiamento in un solo posto.

Scegli un’unica fonte per l’elenco usato dai menu a tendina, dalla validazione e dalla visualizzazione, e aggiornalo deliberatamente. Un elenco di codici modificato a mano in più punti andrà alla deriva dalla concordanza con se stesso, e il sintomo visibile è un utente in un paese che il modulo non offre.

Decidi che cosa significa “sconosciuto” nel tuo schema prima di averne bisogno. Un valore vuoto, una sentinella documentata e un null sono tre affermazioni diverse, e solo una è corretta per un dato campo. Qualunque cosa tu scelga, assicurati che non possa essere scambiata per un codice reale da un’unione, da un confronto o da un generatore di etichette.

Infine, registra ciò che hai rifiutato. Quando un codice di paese non supera la validazione, annota il valore e la versione dell’elenco, non l’intero record. È l’unico modo affidabile per distinguere una regola sbagliata da un input sbagliato, e tiene i dati personali fuori dalla tua diagnostica. Se il campo alimenta anche un numero di telefono, lo stesso principio vale per il prefisso di composizione, come descrive la guida ai prefissi telefonici e all’abbinamento con la località.

Passi successivi

Trova ogni colonna nel tuo schema che contiene un paese e controlla se usano tutte la stessa forma; una rapida query di raggruppamento sui valori distinti mostrerà qualsiasi colonna che ne contenga un misto. Poi conferma che il tuo elenco di validazione possa essere aggiornato da un’unica fonte invece di essere modificato in più punti. Per vedere i codici in contesto, apri una pagina paese e confronta come il paese è identificato lì con come lo chiamano i tuoi dati. Se hai bisogno di record campione per testare la conversione tra forme, genera un lotto nel generatore di indirizzi e fai passare i codici attraverso il tuo helper di normalizzazione. Quei record contengono solo valori sintetici, quindi i codici al loro interno sono materiale di esercitazione — non indirizzamento recapitabile e non un’affermazione sulla residenza di qualcuno.