Country (Semantic Module)

← Back to Modules Reference

The Country semantic module validates, standardizes, and restricts country values using official ISO 3166-1 international standards.

Country data is essential for international shipping, tax calculation, and compliance. Tagging a property with Country ensures users enter recognized country identifiers, standardizes codes into consistent uppercase formatting, and allows you to configure allowed or disallowed country lists.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text property)
Data Type	String
Validation Standard	ISO 3166-1 (iso-3166-1 standard library)
Default Format	ISO_3166_Alpha_2 (Two-letter codes, e.g., US, CA, DE)
Casing Standardization	Automatically converted to uppercase for Alpha codes
Sibling Coordination	Provides country context for the PostalCode semantic

---

Key Capabilities

1. Supported Format Modes (format)

You can choose how country values are validated and stored in your data model:

• ISO_3166_Alpha_2 (Default): Requires standard two-letter ISO country codes (e.g., US, GB, FR, DE, JP).
• ISO_3166_Alpha_3: Requires three-letter ISO country codes (e.g., USA, GBR, FRA, DEU, JPN).
• Name: Requires official English country names (e.g., United States, United Kingdom, Germany).

2. Country Allow Lists (allowedCountries)

Restrict shipping or signups to a specific list of served countries (e.g., ['US', 'CA', 'MX']). Any transaction or profile submitted with an unlisted country is rejected with a clear validation error.

3. Country Deny Lists (disallowedCountries)

Block specific countries due to trade sanctions, export regulations, or regional service limitations.

4. Automatic Standardization

Valid input values are automatically trimmed and saved in the canonical format (e.g. lowercase "us" is saved as standardized "US").

---

Configuration Options

When configuring the Country semantic in the Domain Modeler, you can customize the following parameters:

Option	Type	Default	Description
format	'ISO_3166_Alpha_2' | 'ISO_3166_Alpha_3' | 'Name'	'ISO_3166_Alpha_2'	Required country format standard.
allowedCountries	string[]	[] (all allowed)	Allow list of permitted country codes or names.
disallowedCountries	string[]	[] (none disallowed)	Deny list of prohibited country codes or names.

---

API Lifecycle Examples

1. Creating a Record with Standard Country Code

With the default ISO_3166_Alpha_2 format:

POST /addresses
Content-Type: application/json

{
  "street": "10 Downing Street",
  "city": "London",
  "country": "gb"
}

Server Response (201 Created): The country code is standardized to uppercase:

{
  "data": {
    "id": "addr_401",
    "street": "10 Downing Street",
    "city": "London",
    "country": "GB"
  }
}

---

2. Validation Failure (Invalid ISO Code)

A client submits an unrecognized country code:

{
  "country": "XX"
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property 'country' must be a valid ISO 3166-1 Alpha-2 country code (e.g. 'US')."
}

---

3. Validation Failure (Disallowed Country)

If a country is present in disallowedCountries (e.g. disallowedCountries: ['CU', 'IR', 'KP', 'SY']):

{
  "country": "KP"
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Country 'KP' is disallowed for 'country'."
}

---

Validation Rules & Modeling Guidelines

• Applicable Property Types: Apply to a String property in the Domain Modeler.
• Coordination with Postal Codes: When paired with a sibling PostalCode property within the same entity, the engine dynamically checks that the postal code matches the format required by this country.