PostalCode (Semantic Module)

← Back to Modules Reference

The PostalCode semantic module validates, formats, and sanitizes postal codes and ZIP codes (such as "94105" or "EC1A 1BB").

Postal code structures vary dramatically across the globe. Rather than applying a single rigid pattern, the PostalCode semantic connects dynamically with the sibling Country field on the same entity to validate the exact formatting required by that nation.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text property)
Data Type	String
Default Max Length	255 characters
Dynamic Country Check	Supported (Validates format based on sibling Country property)
Supported Countries	25+ built-in country patterns (US, CA, GB, DE, FR, AU, JP, etc.) plus flexible alphanumeric fallback

---

Key Capabilities

1. Dynamic Geographic Validation (validate: true)

When enabled, the Serverless Engine inspects the sibling property annotated with Country on the same record:

• US (US): Requires 5 digits or 9 digits ZIP+4 format (e.g. 94105 or 94105-1234).
• Canada (CA): Validates Canadian alphanumeric formatting (e.g. K1A 0B1).
• United Kingdom (GB): Validates official Royal Mail alphanumeric formats (e.g. SW1A 1AA or EC1A 1BB).
• European Union (DE, FR, IT, ES): Enforces exact 5-digit patterns.
• Other Countries: Supports comprehensive built-in patterns for Australia, Japan, Brazil, India, Mexico, China, Poland, and more, falling back to standard 3-to-10 character alphanumeric codes.

2. Smart Update Operations

During PUT or PATCH updates, if an API client updates only the postalCode without resending the country, the engine automatically references the existing database record to retrieve the country and validate the new code safely.

3. Allowed & Disallowed Lists (allowedPostalCodes, disallowedPostalCodes)

For hyperlocal delivery zones or service-area restrictions:

• Allow specific ZIP codes to restrict checkout to supported neighborhoods.
• Disallow remote or non-deliverable territory postal codes.

---

Configuration Options

When configuring the PostalCode semantic in the Domain Modeler, you can adjust:

Option	Type	Default	Description
validate	boolean	true	Enables dynamic validation against the sibling Country property.
allowedPostalCodes	string[]	[] (all allowed)	Specific list of permitted postal codes.
disallowedPostalCodes	string[]	[] (none disallowed)	Specific list of prohibited postal codes.

---

API Lifecycle Examples

1. Valid US ZIP Code Submission

A record created with country "US" and a valid 5-digit ZIP code:

POST /addresses
Content-Type: application/json

{
  "street": "1 Market St",
  "city": "San Francisco",
  "country": "US",
  "postalCode": "94105"
}

Server Response (201 Created):

{
  "data": {
    "id": "addr_501",
    "street": "1 Market St",
    "city": "San Francisco",
    "country": "US",
    "postalCode": "94105"
  }
}

---

2. Validation Failure (Mismatched Country Format)

A client provides a US ZIP code format, but specifies the country as "GB" (United Kingdom):

{
  "country": "GB",
  "postalCode": "94105"
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Invalid postal code format for country: GB. Value: '94105'"
}

---

Validation Rules & Modeling Guidelines

• Pair with Country: For dynamic validation to function, the entity model must include a sibling property tagged with the Country semantic module.
• Applicable Property Types: Apply to a String property in the Domain Modeler.
• Length Constraints: The default Maximum Length of 255 characters provides ample headroom for international alphanumeric postal strings with spaces and hyphens.