address.postalCode

Generates realistic postal codes in various international formats. Supports US ZIP codes, Canadian postal codes, and UK postcodes with proper formatting and validation rules for each region.

Keywords

Specifies which country's postal code format to generate. Must be one of: US (default),CA, or UK. When not specified, generates US postal codes.

Specifies the postal code style. Must be one of: basic (default) or extended. For US, basic generates 5-digit ZIP codes while extended generates ZIP+4. For CA and UK, style is ignored as they only have one format.

Behavior

The generated postal codes follow region-specific formatting rules:

• US (default, basic): 5-digit ZIP codes (00001–99999)
• US (extended): ZIP+4 format with hyphen (12345-6789)
• CA (Canadian): Alphanumeric format with space (A1A 1A1) — excludes certain letters (D, F, I, O, Q, U) per Canada Post rules
• UK (British): Variable-length postcode format (SW1A 1AA) — outward code from common UK postcode areas

Values are not guaranteed to be unique. Generation is deterministic based on the simulation seed.

Examples

Default US ZIP code:

{
  "type": "address.postalCode"
}

US ZIP+4 (extended style):

{
  "type": "address.postalCode",
  "country": "US",
  "style": "extended"
}

Canadian postal code:

{
  "type": "address.postalCode",
  "country": "CA"
}

UK postcode:

{
  "type": "address.postalCode",
  "country": "UK"
}

In an entity definition:

{
  "entities": {
    "customer": {
      "fields": {
        "name": { "type": "person.name" },
        "streetAddress": { "type": "address.address1" },
        "postalCode": {
          "type": "address.postalCode",
          "country": "US"
        },
        "country": { "const": "United States" }
      }
    }
  }
}

Notes

The generated postal codes are fictional and suitable for testing and simulation purposes. They follow realistic patterns but are not real postal codes.

For complete mailing addresses, combine this schema with other address components like address.address1, address.address2, city, and state fields.

When using region-specific postal codes, ensure your simulation also uses appropriate values for related fields (e.g., Canadian postal codes should be paired with Canadian provinces and cities).