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

countryoptional

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.

styleoptional

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 country, basic style): 5-digit ZIP codes (00001-99999)
• US (extended style): ZIP+4 format with hyphen (12345-6789)
• CA (Canadian): Alphanumeric format with space (A1A 1A1)
  • Alternates between letters and digits
  • Excludes certain letters (D, F, I, O, Q, U) per Canada Post rules
  • Space separates the outward and inward code
  • Style parameter is ignored (only one format)
• UK (British): Variable-length postcode format (SW1A 1AA)
  • Outward code from common UK postcode areas
  • Inward code: digit + 2 letters
  • Space separates outward and inward codes
  • Style parameter is ignored (only one format)

Additional characteristics:

• Values are not guaranteed to be unique
• Generation is deterministic based on the simulation seed
• All formats follow regional postal standards
• Invalid country or style values will return an error

Examples

Default US ZIP code:

{
  "type": "address.postalCode"
}

Example outputs:

• 12345
• 90210
• 10001

US ZIP+4 (extended style):

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

Example outputs:

• 12345-6789
• 90210-1234
• 10001-5678

Canadian postal code:

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

Example outputs:

• M5V 3A8
• K1A 0B1
• V6B 2W9

UK postcode:

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

Example outputs:

• SW1A 1AA
• EC1A 1BB
• W1A 0AX

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).