City (Semantic Module)

← Back to Modules Reference

The City semantic module standardizes text properties that represent a city, town, municipality, or locality (such as "San Francisco", "London", or "Tokyo").

It ensures that city values are valid text strings and automatically strips accidental leading and trailing whitespace, keeping your customer profiles and shipping records clean and uniform.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text property)
Data Type	String
Default Max Length	255 characters
Whitespace Handling	Automatically trimmed on Create and Update operations

---

Key Capabilities

1. Automatic Whitespace Trimming

Users often introduce stray spaces when filling out checkout or registration forms. Tagging a field with City ensures that inputs such as " New York " are automatically normalized to "New York" before being saved.

2. Type Integrity

Verifies that any incoming value is a valid string, rejecting invalid nested objects or arrays with clear validation feedback.

---

API Lifecycle Examples

1. Standard City Creation

A client submits a city value with extra whitespace:

POST /addresses
Content-Type: application/json

{
  "city": "   Austin   "
}

Server Response (201 Created):

{
  "data": {
    "id": "addr_201",
    "city": "Austin"
  }
}

---

2. Validation Failure (Invalid Data Type)

If a client passes a non-string value (such as a number or object):

{
  "city": 12345
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property 'city' must be a string."
}

---

Validation Rules & Modeling Guidelines

• Applicable Property Types: Apply to a String property within an address entity or profile model.
• Property Length Constraints: By default, String properties in the Domain Modeler have a Maximum Length of 255 characters, accommodating even the longest official municipality names worldwide.