international

README

international

Typed, immutable international identifiers and metadata for Go services. Countries, subdivisions, languages, locales, currencies, phone numbers, and postal values remain distinct types with strict parsing, explicit canonicalization, offline behavior, and versioned dataset provenance.

go get github.com/faustbrian/go-international@v1.1.0

finland, err := country.Parse("FI")
if err != nil { return err }

tag, err := locale.Parse("fi-FI")
if err != nil { return err }

number, err := phone.Parse("040 123 4567", phone.ParseOptions{
    RegionHint: finland,
})

The zero value of every scalar means absent. Text encoding rejects absent values; JSON and SQL encode them as null/NULL. Parsing never performs country inference, locale detection, delivery validation, identity claims, or runtime network access.

Start with the five-minute quickstarts, then read the API and standards reference, integration guide, and security model. Dataset versions and licenses are documented in provenance; the checked semantic baseline and update classification procedure are in the dataset report. The requirement-to-test mapping, resource budgets, and local gate evidence are in the verification report. Observable interpretations are recorded in the specification decision register. Shared construction, ownership, lifecycle, and composition expectations are in the versioned Golib ecosystem index and its Foundations family.

The module is stable and active and requires Go 1.26.6 or newer. Its APIs are stateless: callers retain all configuration, buffers, pgx maps, and validation contexts, and the module starts no background work. Parse and validation failures preserve international.ErrInvalid or international.ErrResourceLimit; unsupported wire formats preserve the calling adapter's ErrUnsupportedFormat sentinel.

Package map

Package	Use
root	Shared status, parse-error, resource-limit, normalization, and dataset-diff contracts
country, subdivision	ISO 3166 and governed subdivision identities
language, locale	ISO 639 and bounded BCP 47 identities
currency	ISO 4217 alphabetic and numeric identities
phone, postal	Bounded, privacy-safe phone and country-bound postal values
adapters/postgres	pgx text registration on a caller-owned type map
adapters/validation	Pure International rules for Golib Validation
adapters/wire	Strict bounded JSON, XML, YAML, TOML, and MessagePack dispatch
internationaltest	Test-only governed fixtures and assertions

The former internationalpgx, internationalvalidation, and internationalwire paths remain supported compatibility facades; new code should use the target-oriented adapters. See the compiler-checked adapter example and the migration guide.

Licensed under MIT; dataset licenses remain with their upstream publishers. For help, see Support. Report vulnerabilities through the private process in Security.

Documentation

Start with the documentation index for datasets, provenance, integration, migration, and operations guidance.

Documentation

Overview

Package international defines shared contracts for versioned international identifier datasets. Identifier-specific behavior lives in subpackages.

Example (SuccessorAdapters)

package main

import (
	"errors"
	"fmt"

	internationalpostgres "github.com/faustbrian/go-international/adapters/postgres"
	internationalvalidation "github.com/faustbrian/go-international/adapters/validation"

	internationalwire "github.com/faustbrian/go-international/adapters/wire"
	"github.com/faustbrian/go-international/country"

	validation "github.com/faustbrian/go-validation"
	"github.com/faustbrian/go-wire"
	"github.com/jackc/pgx/v5/pgtype"
)

func main() {
	finland, _ := country.Parse("FI")
	typeMap := pgtype.NewMap()
	internationalpostgres.Register(typeMap)
	dataType, _ := typeMap.TypeForValue(finland)

	ctx, _ := validation.NewContext(validation.DefaultLimits())
	report := internationalvalidation.Country().Validate(ctx, "FI")

	_, unsupported := internationalwire.Encode(wire.FormatSOAP, finland)
	fmt.Println(dataType.Name, report.Err(), errors.Is(unsupported, internationalwire.ErrUnsupportedFormat))
}

Output:
text <nil> true

Index

• Constants
• Variables
• func LowercaseUnicode(input string, maximumBytes int) (string, error)
• type DatasetDiff
  • func DiffRecords(before, after []Record) (DatasetDiff, error)
• type ParseError
  • func NewParseError(kind, reason string) *ParseError
  • func (err *ParseError) Error() string
  • func (err *ParseError) Unwrap() error
• type Provenance
  • func (provenance Provenance) Equal(other Provenance) bool
  • func (provenance Provenance) Validate() error
• type Record
• type Status
  • func ParseStatus(input string) (Status, error)
  • func (status Status) Known() bool
  • func (status Status) MarshalJSON() ([]byte, error)
  • func (status Status) MarshalText() ([]byte, error)
  • func (status Status) String() string
  • func (status *Status) UnmarshalJSON(input []byte) error
  • func (status *Status) UnmarshalText(input []byte) error

Examples

• Package (SuccessorAdapters)

Constants

const MaxDatasetRecords = 100_000

MaxDatasetRecords bounds generic dataset comparison work.

Variables

var (
	// ErrInvalid identifies syntactically invalid input without retaining it.
	ErrInvalid = errors.New("international: invalid value")
	// ErrInvalidProvenance identifies incomplete or malformed source metadata.
	ErrInvalidProvenance = errors.New("international: invalid provenance")
	// ErrInvalidDataset identifies structurally invalid generated data.
	ErrInvalidDataset = errors.New("international: invalid dataset")
	// ErrResourceLimit identifies input rejected before excessive work.
	ErrResourceLimit = errors.New("international: resource limit exceeded")
)

Functions

func LowercaseUnicode

func LowercaseUnicode(input string, maximumBytes int) (string, error)

LowercaseUnicode applies locale-neutral full Unicode lowercasing within a caller-owned byte budget. The transformation may expand text and therefore checks both input and output sizes. Each call owns its Caser, so callers may invoke the function concurrently without sharing state.

Types

type DatasetDiff

type DatasetDiff struct {
	Added           []string `json:"added"`
	Removed         []string `json:"removed"`
	AliasesChanged  []string `json:"aliases_changed"`
	StatusChanged   []string `json:"status_changed"`
	MetadataChanged []string `json:"metadata_changed"`
}

DatasetDiff classifies changes that require compatibility review.

func DiffRecords

func DiffRecords(before, after []Record) (DatasetDiff, error)

DiffRecords deterministically classifies changes between two projections.

type ParseError

type ParseError struct {
	// contains filtered or unexported fields
}

ParseError is a bounded diagnostic that never stores or echoes caller input.

func NewParseError

func NewParseError(kind, reason string) *ParseError

NewParseError creates a redacted parse error for a public value kind.

func (*ParseError) Error

func (err *ParseError) Error() string

Error returns a bounded, input-redacted diagnostic.

func (*ParseError) Unwrap

func (err *ParseError) Unwrap() error

Unwrap makes all ParseError values match ErrInvalid.

type Provenance

type Provenance struct {
	Dataset         string    `json:"dataset"`
	Source          string    `json:"source"`
	RetrievedAt     time.Time `json:"retrieved_at"`
	UpstreamVersion string    `json:"upstream_version"`
	License         string    `json:"license"`
	SHA256          string    `json:"sha256"`
	Generator       string    `json:"generator"`
	Transformations []string  `json:"transformations"`
}

Provenance records enough information to reproduce and review a dataset.

func (Provenance) Equal

func (provenance Provenance) Equal(other Provenance) bool

Equal reports whether all immutable provenance fields match.

func (Provenance) Validate

func (provenance Provenance) Validate() error

Validate verifies required provenance fields without network access.

type Record

type Record struct {
	ID          string `json:"id"`
	Status      Status `json:"status"`
	Fingerprint string `json:"fingerprint"`
	AliasOf     string `json:"alias_of"`
}

Record is the compatibility-relevant projection of a generated entry.

type Status

type Status uint8

Status describes the registry standing of an identifier. It is metadata, not a claim that an identifier is suitable for a particular business use.

const (
	// StatusUnknown means no authoritative status is available.
	StatusUnknown Status = iota
	// StatusOfficial identifies a currently assigned standards entry.
	StatusOfficial
	// StatusReserved identifies an entry retained by its authority.
	StatusReserved
	// StatusTransitional identifies an entry in a defined transition period.
	StatusTransitional
	// StatusDeleted identifies an entry removed from current assignment.
	StatusDeleted
	// StatusUserAssigned identifies a standards-defined private-use entry.
	StatusUserAssigned
	// StatusHistoric identifies an entry available only through opt-in history.
	StatusHistoric
)

func ParseStatus

func ParseStatus(input string) (Status, error)

ParseStatus parses one stable wire spelling without aliases or casing repair.

func (Status) Known

func (status Status) Known() bool

Known reports whether the status came from authoritative metadata.

func (Status) MarshalJSON

func (status Status) MarshalJSON() ([]byte, error)

MarshalJSON encodes the status as its stable string spelling.

func (Status) MarshalText

func (status Status) MarshalText() ([]byte, error)

MarshalText returns the stable status wire spelling.

func (Status) String

func (status Status) String() string

String returns the stable wire spelling of the status.

func (*Status) UnmarshalJSON

func (status *Status) UnmarshalJSON(input []byte) error

UnmarshalJSON accepts only a stable status string spelling.

func (*Status) UnmarshalText

func (status *Status) UnmarshalText(input []byte) error

UnmarshalText parses one stable status wire spelling without changing the receiver on error.