addressing 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49688e426e19464f0e7a96b897e4edced4c46a194303bb8a381c5ffb897d1d4f
-  data.tar.gz: 52d8f2a6f085cad074dddedcba8e4218ce2f2ec9310789b898fbf8ff04fab435
+  metadata.gz: 3960270871e0f9694221dafc7ba2786b299a50508de02d13d6d4bd4c5a0f4a4c
+  data.tar.gz: dcb37a8e3a0f402b90c3e29afb0ea296c176e32f375d58755be1984616869a44
 SHA512:
-  metadata.gz: 190afd7e32d51607270b3866c33f2268379bcd3ea9528f223f48113bd277940704b4ae3e9353e34cbec05e5a80545e64fa52154dfcdf6fd6540cdbaa4feef34a
-  data.tar.gz: 0fd91253ba248a1a1395f7159cef755abb8082159da02712b4e91f09eec138cc92ff25b57d1a395505a44e455936c037ec3441d994e127cfd6d54174d398f6a1
+  metadata.gz: 3f6c2fe3c4c2fb6aa90b2225953348ba02b60026786cde2365028f50e5015688dbfa8d0b373ce5393b7db45863f26de8086ebffe5bb71fa6105fb3ce8db000b3
+  data.tar.gz: 7bc0d61fa1d7fd811c951e191edf5cf89702233c067645f03716da959d437cd32314c895d99984fee9552f5488cf907b65af9556cd7b05f13113c494afd478a7

data/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `addressing` will be documented in this file.
 
+## [2.2.0](https://github.com/robinvdvleuten/addressing/compare/v2.1.0...v2.2.0) (2026-10-01)
+
+
+### Features
+
+* add AddressValidator, which validates a plain address ([2d1b8fe](https://github.com/robinvdvleuten/addressing/commit/2d1b8fe8e7b501d8950a61349fa400bd1687d353)), closes [#52](https://github.com/robinvdvleuten/addressing/issues/52)
+* add FieldViolation, one field of an address that breaks a rule of its address format ([2d1b8fe](https://github.com/robinvdvleuten/addressing/commit/2d1b8fe8e7b501d8950a61349fa400bd1687d353))
+* remove the undocumented AddressFormatHelper class, whose required fields rule moved into AddressValidator ([2d1b8fe](https://github.com/robinvdvleuten/addressing/commit/2d1b8fe8e7b501d8950a61349fa400bd1687d353))
+* remove the undocumented verify_address_format, verify_subdivisions and verify_postal_code methods from models that call validates_address_format ([2d1b8fe](https://github.com/robinvdvleuten/addressing/commit/2d1b8fe8e7b501d8950a61349fa400bd1687d353))
+* support validates_address_format on plain ActiveModel classes ([821469b](https://github.com/robinvdvleuten/addressing/commit/821469b20779854f8af78e84dcdf4ef1985c7580)), closes [#57](https://github.com/robinvdvleuten/addressing/issues/57)
+
+
+### Bug Fixes
+
+* check origin_country with the other formatter options ([4e4dfbf](https://github.com/robinvdvleuten/addressing/commit/4e4dfbfe553bb106137b9e8b5076e7c1e5b8407a)), closes [#53](https://github.com/robinvdvleuten/addressing/issues/53)
+* include address_line3 in validates_address_format default fields ([1739846](https://github.com/robinvdvleuten/addressing/commit/1739846ed3f5e3b03f3821fbb229f8a827078ed9)), closes [#47](https://github.com/robinvdvleuten/addressing/issues/47)
+* load address formats from JSON and freeze their field lists ([e9bbbc1](https://github.com/robinvdvleuten/addressing/commit/e9bbbc1c8f5dd2c603fdc61676f27c9c238f7912)), closes [#43](https://github.com/robinvdvleuten/addressing/issues/43) [#49](https://github.com/robinvdvleuten/addressing/issues/49)
+* make subdivision lookups independent of load order and platform ([31e1c4b](https://github.com/robinvdvleuten/addressing/commit/31e1c4b839419382d9cf95a66f51547906e65d89)), closes [#56](https://github.com/robinvdvleuten/addressing/issues/56)
+* raise ArgumentError for a nil origin_country in PostalLabelFormatter ([954ba68](https://github.com/robinvdvleuten/addressing/commit/954ba68ce63224b5095e408160d762102b44752f)), closes [#45](https://github.com/robinvdvleuten/addressing/issues/45)
+* read a subdivision definition that upstream writes as an empty array ([7dc6e72](https://github.com/robinvdvleuten/addressing/commit/7dc6e72fa76efe16e063f264a095bbdf83aafe1a))
+* read the data files as UTF-8, independent of the locale ([aeafad8](https://github.com/robinvdvleuten/addressing/commit/aeafad861c637dd1e4b7e3b9e2f2931f129fa64c)), closes [#44](https://github.com/robinvdvleuten/addressing/issues/44)
+* report a missing country code as a field violation ([15c23e6](https://github.com/robinvdvleuten/addressing/commit/15c23e63dc85a2cd394a2605fc57fd55ca8d0fb1)), closes [#58](https://github.com/robinvdvleuten/addressing/issues/58)
+* share one blank check between Subdivision and AddressValidator ([b469c0b](https://github.com/robinvdvleuten/addressing/commit/b469c0b244bb771d624bebe9667e41090b46fba6))
+* upcase country codes on Address and the postal label origin ([f1e6554](https://github.com/robinvdvleuten/addressing/commit/f1e6554d9291011f6e44bc91799646b9b7b39f62)), closes [#46](https://github.com/robinvdvleuten/addressing/issues/46)
+* validate the html_tag and locale formatter options ([cbd90c3](https://github.com/robinvdvleuten/addressing/commit/cbd90c31daa569cd6418185bf4cfa36acc4d1078))
+
+
+### Performance Improvements
+
+* cache fewer country lists and address formats ([1c5bc0a](https://github.com/robinvdvleuten/addressing/commit/1c5bc0a142ad70c8a54a11c97c9b9a0562a66ab8))
+* check for subdivision children without building them ([04eb8c1](https://github.com/robinvdvleuten/addressing/commit/04eb8c135bfb66b088ca9bd26b174a0540574c0f))
+
+## [2.1.0](https://github.com/robinvdvleuten/addressing/compare/v2.0.1...v2.1.0) (2026-09-18)
+
+
+### Features
+
+* sync data with commerceguys repository (v2.3.0) ([0ccf627](https://github.com/robinvdvleuten/addressing/commit/0ccf627b2abed8498d0b81bf57075346aa75c401))
+* sync data with commerceguys repository (v2.3.1) ([acf6e04](https://github.com/robinvdvleuten/addressing/commit/acf6e042a3eb08f932f17db339689ab76baffacd))
+
 ## [2.0.1](https://github.com/robinvdvleuten/addressing/compare/v1.1.0...v2.0.1) (2026-05-27)
 
 

data/README.md

@@ -1,146 +1,192 @@
 # Addressing
 
-A Ruby addressing library, powered by CLDR and Google's address data.
+A Ruby library that knows how postal addresses are written in every country — which fields exist, in what order, what to call them, and which ones are required. Give it an address and a country code, and it produces a correctly formatted label or HTML block, validates the postal code, and tells your form whether to ask for a "State", a "Province", or a "Prefecture".
 
-- Countries, with translations for over 250 locales. Powered by [CLDR](http://cldr.unicode.org) v46.
-- Address formats for over 200 countries.
-- Subdivisions (administrative areas, localities, dependent localities) for 60 countries.
-- Both latin and local subdivision names, when relevant (e.g: Okinawa / 沖縄県).
-- Formatting, both in HTML and plain text.
+Most country-data gems give you a list of countries and their subdivisions. This one gives you the **address format** behind each of them, so a checkout form or shipping label built on it is correct in Japan and Brazil, not just in the US.
 
-Address formats and subdivisions were initially generated from [Google's Address Data Service](https://chromium-i18n.appspot.com/ssl-address), and are now owned and maintained by the library itself.
+- **Address formats for 205 countries.** Field order, required fields, uppercasing rules, postal code patterns, and the right label for each field.
+- **256 countries, translated into 148 locales.** Names, three-letter and numeric codes, currency, and timezones. Powered by [CLDR](http://cldr.unicode.org) v48.
+- **Subdivisions for 63 countries.** Up to three levels (administrative area → locality → dependent locality), in both latin and local scripts (Okinawa / 沖縄県).
+- **Zero runtime dependencies.** Pure Ruby 3.3+. Address formats load from a single 56 KB JSON file; the 1.5 MB of country and subdivision data is read lazily, country names per locale and subdivisions per country, only when you ask for it.
+- **Rails-ready.** A `validates_address_format` validator for Active Record and ActiveModel. On Active Record, it runs only when an address field actually changed.
+- **Immutable.** `Address` objects never mutate; `with_*` methods return copies.
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/robinvdvleuten/addressing/test.yml?branch=main)](https://github.com/robinvdvleuten/addressing/actions?query=workflow%3Atest)
-[![MIT license](https://img.shields.io/github/license/robinvdvleuten/addressing.svg)](https://github.com/robinvdvleuten/addressing/blob/main/LICENSE)
+```rb
+formatter = Addressing::DefaultFormatter.new(html: false)
+
+puts formatter.format(Addressing::Address.new(country_code: "US",
+  administrative_area: "CA", locality: "Mountain View",
+  postal_code: "94043", address_line1: "1098 Alta Ave"))
+# 1098 Alta Ave
+# Mountain View, CA 94043
+# United States
+
+puts formatter.format(Addressing::Address.new(country_code: "JP",
+  administrative_area: "26", locality: "京都市南区",
+  postal_code: "601-8213", address_line1: "九条町1", locale: "ja"), locale: "ja")
+# 日本
+# 〒601-8213
+# 京都府京都市南区
+# 九条町1
+```
+
+Same code, two countries, two completely different layouts — including the `〒` prefix and the reversed field order Japan uses.
+
+Address formats and subdivisions were initially generated from [Google's Address Data Service](https://chromium-i18n.appspot.com/ssl-address), and are kept in sync with the PHP [commerceguys/addressing](https://github.com/commerceguys/addressing) library.
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Addresses](#addresses)
+- [Address formats](#address-formats)
+- [Countries](#countries)
+- [Subdivisions](#subdivisions)
+- [Formatting addresses](#formatting-addresses)
+- [Validating addresses](#validating-addresses)
+- [Contributing](#contributing)
 
 ## Installation
 
-Add this line to your application’s Gemfile:
+Add the gem to your Gemfile:
 
 ```rb
 gem "addressing"
 ```
 
-## Getting Started
+Then install it:
 
-The [Address](lib/addressing/address.rb) class represents a postal adddress, with attributes for the following fields:
+```
+bundle install
+```
+
+Requires Ruby 3.3 or newer. There are no other runtime dependencies — Active Record or ActiveModel is only needed for the validator, and `tzinfo` only for `Country#timezones`.
 
-- Country code
-- Administrative area
-- Locality (City)
-- Dependent Locality
-- Postal code
-- Sorting code
-- Address line 1
-- Address line 2
-- Address line 3
-- Organization
-- Given name (First name)
-- Additional name (Middle name / Patronymic)
-- Family name (Last name)
+## Addresses
 
-Field names follow the OASIS [eXtensible Address Language (xAL)](http://www.oasis-open.org/committees/ciq/download.shtml) standard.
+The [Address](lib/addressing/address.rb) class represents a postal address. Field names follow the OASIS [eXtensible Address Language (xAL)](http://www.oasis-open.org/committees/ciq/download.shtml) standard:
+
+`country_code`, `administrative_area`, `locality`, `dependent_locality`, `postal_code`, `sorting_code`, `address_line1`, `address_line2`, `address_line3`, `organization`, `given_name`, `additional_name`, `family_name`, `locale`.
 
 ```rb
-# Create a new Address instance.
 address = Addressing::Address.new(
   country_code: "US",
   administrative_area: "CA",
   locality: "Mountain View",
-  dependent_locality: "MV",
   postal_code: "94043",
-  sorting_code: "94044",
   address_line1: "1600 Amphitheatre Parkway",
-  address_line2: "Google Bldg 41",
   organization: "Google Inc.",
   given_name: "John",
-  additional_name: "L.",
-  family_name: "Smith",
-  locale: "en"
+  family_name: "Smith"
 )
+```
 
-# Modify an existing instance through chainable methods.
-address = address.with_country_code('US')
-                 .with_administrative_area('CA')
+Addresses are immutable. The `with_*` methods return a modified copy and can be chained:
+
+```rb
+address = Addressing::Address.new
+  .with_country_code("US")
+  .with_administrative_area("CA")
+  .with_locality("Mountain View")
+  .with_address_line1("1098 Alta Ave")
 ```
 
-The [AddressFormat](lib/addressing/address_format.rb) class provides the following information:
+## Address formats
 
-- Which fields are used, and in which order
-- Which fields are required
-- Which fields need to be uppercased for the actual mailing (to facilitate automated sorting of mail)
-- The labels for the administrative area (state, province, parish, etc.), locality (city/post town/district, etc.), dependent locality (neighborhood, suburb, district, etc) and the postal code (postal code or ZIP code)
-- The regular expression pattern for validating postal codes
+The [AddressFormat](lib/addressing/address_format.rb) class describes how a country writes its addresses: which fields are used and in which order, which are required, which must be uppercased for mailing, what each field is called, the postal code pattern, and which fields have predefined subdivision data.
 
 ```rb
-# Get the address format for Brazil.
-address_format = Addressing::AddressFormat.get('BR')
+format = Addressing::AddressFormat.get("BR")
+
+p format.required_fields
+# ["address_line1", "administrative_area", "locality", "postal_code", "given_name", "family_name"]
+
+p format.administrative_area_type  # "state"
+p format.postal_code_type          # "postal"
+p format.subdivision_fields        # ["administrative_area", "locality"]
 ```
 
-The [Country](lib/addressing/country.rb) class provides the following information:
+Use `administrative_area_type`, `locality_type`, `dependent_locality_type`, and `postal_code_type` to label your form fields the way locals expect — "state" in Brazil, "prefecture" in Japan, "county" in Ireland.
+
+## Countries
 
-- The country name.
-- The numeric and three-letter country codes.
-- The official currency code, when known.
-- The timezones which the country spans.
+The [Country](lib/addressing/country.rb) class provides the country name, the numeric and three-letter codes, the official currency code when known, and the timezones the country spans.
 
 ```rb
-# Get the country instance for Brazil.
-brazil = Addressing::Country.get('BR')
-p brazil.three_letter_code # BRA
-p brazil.name # Brazil
-p brazil.currency_code # BRL
-p brazil.timezones
+brazil = Addressing::Country.get("BR")
+
+p brazil.three_letter_code  # "BRA"
+p brazil.name               # "Brazil"
+p brazil.currency_code      # "BRL"
 
-# Get all country instances.
+# Get all countries as a hash of country_code => Country.
 countries = Addressing::Country.all
 
-# Get the country list ({ country_code => name }), in French.
-country_list = Addressing::Country.list('fr-FR')
+# Get a { country_code => name } list, in French — useful for a <select>.
+p Addressing::Country.list("fr-FR")["BR"]  # "Brésil"
+
+# Or a single country in another locale.
+p Addressing::Country.get("BR", "fr-FR").name  # "Brésil"
+```
+
+> `Country#timezones` is backed by the [tzinfo](https://github.com/tzinfo/tzinfo) gem. Add `gem "tzinfo"` (and `tzinfo-data` on platforms without a system timezone database) if you use it.
+
+```rb
+require "tzinfo"
+p brazil.timezones.first(2)  # ["America/Noronha", "America/Belem"]
 ```
 
-The [Subdivision](lib/addressing/subdivision.rb) class provides the following information:
+## Subdivisions
 
-- The subdivision code (used to represent the subdivison on a parcel/envelope, e.g. CA for California)
-- The subdivison name (shown to the user in a dropdown)
-- The local code and name, if the country uses a non-latin script (e.g. Cyrilic in Russia).
-- The postal code pattern (if different from the one on the address format).
+The [Subdivision](lib/addressing/subdivision.rb) class provides the subdivision code used on an envelope (`CA` for California), the name shown to the user, the local code and name for countries using a non-latin script, and a postal code pattern when it differs from the country's.
 
-Subdivisions are hierarchical and can have up to three levels: Administrative Area -> Locality -> Dependent Locality.
+Subdivisions are hierarchical, up to three levels: administrative area → locality → dependent locality. Pass the parents as an array.
 
 ```rb
-# Get the subdivisions for Brazil.
-states = Addressing::Subdivision.all(['BR'])
-states.each do |state|
-  municipalities = state.children
-end
+# All Brazilian states.
+states = Addressing::Subdivision.all(["BR"])
+p states.size  # 27
 
-# Get the subdivisions for Brazilian state Ceará.
-municipalities = Addressing::Subdivision.all(['BR', 'CE'])
-municipalities.each do |municipality|
-  p municipality.name
-end
+# One state, by code.
+ceara = Addressing::Subdivision.get("CE", ["BR"])
+p [ceara.code, ceara.name, ceara.children?]  # ["CE", "Ceará", true]
+
+# The municipalities of Ceará.
+p Addressing::Subdivision.all(["BR", "CE"]).size  # 184
+
+# A { code => name } list, ready for a <select>.
+Addressing::Subdivision.list(["BR"])
 ```
 
-### Formatting addresses
+Data is loaded lazily: asking for Brazil's states reads Brazil's file only, and `children` on a subdivision loads that branch on first access. `children` behaves like the hash that `all` returns.
 
-Addresses are formatted according to the address format, in HTML or text.
+To match the values of an address against the predefined subdivisions, ask for its subdivision chain. Pass the values in level order: administrative area, locality, dependent locality. The walk stops at an empty value, at a subdivision without children, or at a value that matches no predefined subdivision. `unmatched_level` gives the position of that last value.
 
-#### DefaultFormatter
+```rb
+chain = Addressing::Subdivision.chain("BR", ["CE", "Fortaleza"])
+p chain.subdivisions.map(&:name)  # ["Ceará", "Fortaleza"]
+p chain.unmatched_level           # nil
+
+p Addressing::Subdivision.chain("BR", ["CE", "Nowhere"]).unmatched_level  # 1
+```
 
-Formats an address for display, always adds the localized country name.
+## Formatting addresses
+
+Both formatters render according to the country's address format, in HTML (the default) or plain text (`html: false`).
+
+### DefaultFormatter
+
+Formats an address for display, always adding the localized country name.
 
 ```rb
 address = Addressing::Address.new
-address = address.with_country_code('US')
-                 .with_administrative_area('CA')
-                 .with_locality('Mountain View')
-                 .with_address_line1('1098 Alta Ave')
-
-formatter = Addressing::DefaultFormatter.new
-p formatter.format(address)
+  .with_country_code("US")
+  .with_administrative_area("CA")
+  .with_locality("Mountain View")
+  .with_address_line1("1098 Alta Ave")
 
-# Output:
+puts Addressing::DefaultFormatter.new.format(address)
 # <p translate="no">
 # <span class="address-line1">1098 Alta Ave</span><br>
 # <span class="locality">Mountain View</span>, <span class="administrative-area">CA</span><br>
@@ -148,34 +194,29 @@ p formatter.format(address)
 # </p>
 ```
 
-#### PostalLabelFormatter
+### PostalLabelFormatter
 
-Takes care of uppercasing fields where required by the format (to facilitate automated mail sorting).
+Renders a mailing label as plain text, uppercasing the fields the country requires for automated mail sorting.
 
-Requires specifying the origin country code, allowing it to differentiate between domestic and international mail. In case of domestic mail, the country name is not displayed at all. In case of international mail:
-
-1. The postal code is prefixed with the destination's postal code prefix.
-2. The country name is added to the formatted address, in both the current locale and English. This matches the recommendation given by the Universal Postal Union, to avoid difficulties in countries of transit.
+It needs the origin country, so it can tell domestic mail from international. For domestic mail the country name is omitted entirely. For international mail the postal code gets the destination's prefix, and the country name is added in both the current locale and English — the Universal Postal Union's recommendation, to avoid trouble in countries of transit.
 
 ```rb
 address = Addressing::Address.new
-address = address.with_country_code('US')
-                 .with_administrative_area('CA')
-                 .with_locality('Mountain View')
-                 .with_address_line1('1098 Alta Ave')
-
-formatter = Addressing::PostalLabelFormatter.new
-p formatter.format(address, origin_country: "FR")
+  .with_country_code("US")
+  .with_administrative_area("CA")
+  .with_locality("Mountain View")
+  .with_postal_code("94043")
+  .with_address_line1("1098 Alta Ave")
 
-# Output:
+puts Addressing::PostalLabelFormatter.new.format(address, origin_country: "FR", locale: "fr-FR")
 # 1098 Alta Ave
 # MOUNTAIN VIEW, CA 94043
 # ÉTATS-UNIS - UNITED STATES
 ```
 
-### Validating addresses
+## Validating addresses
 
-For Active Record models, use:
+For Active Record models:
 
 ```rb
 class User < ApplicationRecord
@@ -183,32 +224,91 @@ class User < ApplicationRecord
 end
 ```
 
-For performance, the address is only verified if at least one of the fields changes. Set your own condition with:
+For any other ActiveModel class, extend `Addressing::Model`:
+
+```rb
+class ShippingAddress
+  include ActiveModel::Model
+  extend Addressing::Model
+
+  attr_accessor :country_code, :administrative_area, :locality, :postal_code, :address_line1
+
+  validates_address_format
+end
+```
+
+This checks that every field the country requires is present, that no unused field is filled in, that the subdivisions exist, and that the postal code matches the country's pattern.
+
+By default it validates all address fields. On a model that tracks changes, such as an Active Record model, it only runs when at least one of them has changed; on a model without change tracking, it runs on every validation. Pass `fields:` to narrow it down:
 
 ```rb
 class User < ApplicationRecord
-  validates_address if: -> { something_changed? }, ...
+  validates_address_format fields: [:country_code, :administrative_area, :locality, :postal_code, :address_line1]
 end
 ```
 
-## Changelog
+> **Note:** `fields:` controls which attributes are *read from your model*, not which ones the country requires. The US format requires a given name and family name, so a model without those columns will fail validation with "should not be blank". Use `field_overrides:` to tell the validator that your application does not collect them. Always include `:country_code`: without it the address has no country, and validation reports `country_code` as blank.
 
-Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+```rb
+class User < ApplicationRecord
+  validates_address_format(
+    fields: [:country_code, :administrative_area, :locality, :postal_code, :address_line1],
+    field_overrides: Addressing::FieldOverrides.new(
+      Addressing::AddressField::GIVEN_NAME => Addressing::FieldOverride::HIDDEN,
+      Addressing::AddressField::FAMILY_NAME => Addressing::FieldOverride::HIDDEN,
+      Addressing::AddressField::ORGANIZATION => Addressing::FieldOverride::HIDDEN
+    )
+  )
+end
+```
 
-## Acknowledgements
+```rb
+User.new(country_code: "US", administrative_area: "CA", locality: "Mountain View",
+         postal_code: "94043", address_line1: "1098 Alta Ave").valid?
+# => true
+
+user = User.new(country_code: "US", administrative_area: "XX", locality: "Mountain View",
+                postal_code: "9404", address_line1: "1098 Alta Ave")
+user.valid?
+# => false
+user.errors.full_messages
+# => ["Administrative area should be valid", "Postal code should be valid"]
+```
 
-This gem wouldn't exist when there wasn't the awesome PHP [addressing](https://github.com/commerceguys/addressing) library. The [CommerceGuys](https://github.com/commerceguys) did an excellent job figuring out how to parse Google's address data, as described by their [backstory](https://drupalcommerce.org/blog/16864/commerce-2x-stories-addressing). Unfortunately for me, they created a PHP library where I needed a Ruby gem so this project was born.
+Each field can be overridden as `HIDDEN`, `OPTIONAL`, or `REQUIRED`. Skip postal code checking with `verify_postal_code: false`, and replace the default change-detection with any validation option, such as `if:` or `unless:`:
+
+```rb
+validates_address_format if: -> { shipping_address_changed? }
+```
+
+### Validating without a model
+
+[AddressValidator](lib/addressing/address_validator.rb) applies the same rules to a plain `Addressing::Address`, and takes the same `field_overrides:` and `verify_postal_code:` options. It returns a list of field violations; an empty list means the address is valid.
+
+```rb
+address = Addressing::Address.new(country_code: "US", administrative_area: "XX", locality: "Mountain View",
+                                  postal_code: "9404", address_line1: "1098 Alta Ave",
+                                  given_name: "John", family_name: "Smith")
+
+Addressing::AddressValidator.validate(address)
+# => [#<data Addressing::FieldViolation field=:administrative_area, kind=:invalid>,
+#     #<data Addressing::FieldViolation field=:postal_code, kind=:invalid>]
+```
+
+Each [FieldViolation](lib/addressing/field_violation.rb) holds the `field` as a symbol and the `kind` of rule it breaks: `:blank` for a required field that is missing, `:present` for a field the country does not use or that is hidden, and `:invalid` for a subdivision or postal code that does not match. The kinds are the error types that `validates_address_format` adds to `errors.details`.
+
+An address without a country code gives a single `:blank` violation on `country_code`, because there is no address format to check the other fields against. If your model already validates the presence of `country_code`, you can drop that validation.
 
 ## Contributing
 
-Everyone is encouraged to help improve this project. Here are a few ways you can help:
+Everyone is encouraged to help improve this project:
 
 - [Report bugs](https://github.com/robinvdvleuten/addressing/issues)
 - Fix bugs and [submit pull requests](https://github.com/robinvdvleuten/addressing/pulls)
 - Write, clarify, or fix documentation
 - Suggest or add new features
 
-To get started with development:
+To get started:
 
 ```
 git clone https://github.com/robinvdvleuten/addressing.git
@@ -217,8 +317,20 @@ bundle install
 bundle exec rake test
 ```
 
+Refreshing the country and address data from upstream (`rake addressing:generate`) additionally requires PHP, since it reads the definitions out of the commerceguys library. It syncs the version pinned in `tasks/data_sync.rb`, or another tag with `rake "addressing:generate[v2.3.2]"`, and writes only to `data/`. `data/UPSTREAM_VERSION` records which tag the data comes from.
+
+Upstream maintains the subdivisions and address formats by hand, so the data files can disagree with each other. `rake addressing:verify` reports such discrepancies, and runs at the end of every refresh and in the Verify data workflow. Report a discrepancy upstream instead of editing the data files here, and add it to `tasks/known_discrepancies.yml` until the fix arrives.
+
 Feel free to open an issue to get feedback on your idea before spending too much time on it.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for what has changed recently.
+
+## Acknowledgements
+
+This gem wouldn't exist without the PHP [addressing](https://github.com/commerceguys/addressing) library. The [CommerceGuys](https://github.com/commerceguys) did an excellent job figuring out how to parse Google's address data, as described in their [backstory](https://drupalcommerce.org/blog/16864/commerce-2x-stories-addressing). They built a PHP library where I needed a Ruby gem, so this project was born.
+
 ## License
 
-The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
+The MIT License (MIT). See [LICENSE](LICENSE) for more information.

data/data/UPSTREAM_VERSION

@@ -0,0 +1 @@
+v2.3.1