Address (Semantic Module)

← Back to Modules Reference

The Address semantic module is applied at the Entity level to designate that an entire data entity represents a physical geographic address (such as a customer shipping address, warehouse depot, or billing location).

Unlike property-level semantics that validate individual text fields, Address acts as a contextual domain marker. It organizes child fields—such as StreetAddress, City, Region, Country, and PostalCode—into a coherent address model that integrates seamlessly with customer profiles, orders, and logistics workflows.

---

Technical Specifications

Attribute	Specification
Scope	Entity (Applied to an entire Entity model, e.g., Address or ShippingAddress)
Primary Use Case	Structuring complete physical location entities
Sibling Property Semantics	StreetAddress, City, Region, Country, PostalCode
Runtime Mutations	None (Marker semantic; child properties handle their own validations)

---

Why Use the Address Semantic?

1. Contextual Grouping: Instantly identifies location entities in the Domain Modeler canvas, distinguishing them from generic data records.
2. Standardized Sibling Validations: When individual address properties (like PostalCode and Country) reside within an Address entity, API Now automatically connects their validation rules—for example, dynamically validating a postal code against its sibling country field.
3. Reusable Data Association: Enables 1:1 or 1:N relational patterns between primary entities (such as Customer or Order) and reusable address profiles without duplicating schema logic.

---

Modeling Example

In the Domain Modeler, create an Address entity and apply the relevant property semantics:

Property	Data Type	Semantic Annotation	Example Value
street	String	StreetAddress	"100 Market St, Suite 400"
city	String	City	"San Francisco"
state	String	Region	"California"
country	String	Country	"US"
postalCode	String	PostalCode	"94105"

---

API Lifecycle Example

Creating a Customer with an Associated Address

POST /addresses
Content-Type: application/json

{
  "street": "100 Market St, Suite 400",
  "city": "San Francisco",
  "state": "California",
  "country": "US",
  "postalCode": "94105"
}

Server Response (201 Created):

{
  "data": {
    "id": "addr_901",
    "street": "100 Market St, Suite 400",
    "city": "San Francisco",
    "state": "California",
    "country": "US",
    "postalCode": "94105"
  }
}

---

Modeling Guidelines

• Entity-Level Scope: Ensure Address is assigned in the Entity settings dialog in the Domain Modeler rather than on a single text property.
• Property Length Defaults: All string properties in the entity default to a Maximum Length of 255 characters, which accommodates international street names and regional designations.