JSON Schema for US Addresses: A Developer Reference
Introduction: How One Address Bug Changed an Entire Application
When Michael launched the first version of his ecommerce application, he expected the biggest challenges to involve payment processing, website performance, and customer acquisition. He had spent weeks improving the checkout page and testing the shopping cart. Everything appeared ready for launch.
Then a customer entered a ZIP Code beginning with zero, completed the checkout process, and received an order confirmation containing an incorrect address.
Michael investigated the problem and discovered that his application stored ZIP Codes as numbers. During processing, the leading zero disappeared. Other problems soon emerged. Some customers left apartment numbers out of their address records, while others entered state names in different formats. The application accepted the information, but the data was inconsistent.
Michael realized that his application needed a standard way to describe and validate US address information.
His solution was to introduce a JSON Schema for US addresses.
JSON Schema is a vocabulary for describing the structure and constraints of JSON data. Developers use it to define required properties, acceptable data types, formatting rules, and relationships between fields. The official specification’s current published version is Draft 2020-12. <Cite refs={[“turn416819search0″,”turn416819search1”]}/>
For developers building ecommerce platforms, shipping applications, customer databases, and address-related APIs, a well-designed US address JSON Schema can reduce data inconsistencies and make software easier to maintain.
This developer reference explains how to create a practical schema, validate address objects, handle ZIP Codes and state abbreviations, and understand the difference between structural validation and real postal address verification.
What Is JSON Schema for US Addresses?
A JSON Schema for US addresses defines the expected structure of an address object and the rules its properties must follow.
For example, a checkout application might require a street address, city, state, ZIP Code, and country. It might allow an optional second address line for an apartment, suite, or unit number.
The following example demonstrates a simple address object:
{
"streetAddress": "123 Example Street",
"addressLine2": "Apartment 4B",
"city": "Austin",
"state": "TX",
"postalCode": "78701",
"country": "US"
}This is illustrative test data, not a verified mailing address.
The JSON object contains the address information, while the JSON Schema defines the rules that determine whether the object has an acceptable structure.
Without a schema, one application component might expect the state field to contain TX, while another expects Texas. A database might accept a missing ZIP Code, even though the checkout process requires one.
A shared schema establishes consistent expectations across the application.
It is important to remember that a structurally valid address object is not necessarily a real or deliverable address. JSON Schema can check whether a ZIP Code follows a specified pattern, but it cannot independently establish that the street exists or that the ZIP Code matches the street address.
Why Developers Need a US Address JSON Schema
Address information is used throughout modern software. Online stores need shipping addresses, billing systems store customer locations, and business applications maintain contact records.
When address fields are handled inconsistently, small errors can spread between services and databases.
Maintaining Consistent Address Data
A JSON Schema gives every application component a shared definition of an address.
For example, the schema can require streetAddress, city, state, and postalCode. This helps ensure that each address record contains the fields expected by downstream systems.
Consistent field names and data types also make APIs easier to document and integrate.
Reducing Data Entry Errors
A schema can identify missing required fields, unexpected data types, and incorrectly formatted values before the application processes an address.
If a customer enters 12AB as a ZIP Code, a schema using an appropriate regular expression can reject that value. The application can then display a helpful message requesting a correction.
This does not eliminate every address error, but it catches many basic problems early.
Improving API Reliability
Suppose Michael’s checkout service sends an address to an order management API. If both services follow the same schema, they can agree on the structure of the data being exchanged.
This reduces confusion about property names, optional fields, and expected formats.
Supporting Automated Testing
Developers can use JSON Schema to validate synthetic address records before using them in automated tests. This is useful for testing registration forms, shipping workflows, database imports, and API endpoints.
The schema can also help identify malformed test data before it creates misleading results.
Choosing the Right Fields for a US Address
Before creating his schema, Michael listed the address information his application actually needed.
A typical US address object may include the following properties:
streetAddress: The primary street address.addressLine2: Optional apartment, suite, unit, or additional delivery information.city: The city or locality.state: The two-letter state abbreviation.postalCode: The ZIP Code or ZIP+4 value.country: The country identifier, such asUS.
This structure is suitable for many basic applications, but it is not universal.
Some applications must support PO boxes, rural routes, military addresses, business locations, or international destinations. Others may need delivery instructions or separate billing and shipping addresses.
The schema should reflect the application’s actual requirements rather than forcing every possible address into a single rigid pattern.
It is also useful to distinguish between a postal address and a geographic location. Latitude and longitude describe coordinates, while street addresses identify locations through postal addressing conventions. An application may need both, but they serve different purposes.
A Practical JSON Schema for US Addresses
Michael began with JSON Schema Draft 2020-12 and created a basic schema for his checkout application.
The following example defines required address fields, sets reasonable length limits, and validates the basic structure of the ZIP Code.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/us-address.schema.json",
"title": "US Address",
"description": "Schema for a basic US address object",
"type": "object",
"properties": {
"streetAddress": {
"type": "string",
"minLength": 1,
"maxLength": 150
},
"addressLine2": {
"type": "string",
"maxLength": 100
},
"city": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"state": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"postalCode": {
"type": "string",
"pattern": "^[0-9]{5}(-[0-9]{4})?$"
},
"country": {
"type": "string",
"const": "US"
}
},
"required": [
"streetAddress",
"city",
"state",
"postalCode",
"country"
],
"additionalProperties": false
}This schema uses several important JSON Schema keywords.
The type keyword specifies the expected data type. The properties keyword describes the fields in the object. The required array identifies properties that must be present. The pattern keyword applies a regular expression, while const restricts the country field to a single value.
The additionalProperties keyword prevents unlisted fields from appearing in the object. This can be useful for strict APIs, but it should be adjusted if the application needs extra properties. <Cite refs={[“turn416819search1″,”turn416819search3”]}/>
The ZIP Code pattern accepts five digits or a ZIP+4 value with a hyphen. It checks formatting only. It does not prove that the ZIP Code exists or belongs to the supplied address.
The state pattern also has a limitation. It accepts any two uppercase letters, including combinations that are not official state abbreviations. A production schema should use an explicit list of the state and territory codes the application supports.
Why ZIP Codes Must Be Stored as Strings
One of Michael’s most frustrating bugs came from treating ZIP Codes as numeric values.
A ZIP Code is an identifier, not a quantity. It is not something a program needs to add or divide. Some US ZIP Codes begin with zero, so storing them as numbers can remove an important character.
Consider the value 02108. As a string, it remains a five-character ZIP Code. If a system converts it into an integer, it may become 2108.
That change makes the stored value incorrect.
JSON Schema can prevent this problem by defining postalCode as a string. A regular expression can then check whether the value follows the expected five-digit or ZIP+4 format.
Developers should also avoid converting ZIP Codes into integers during database imports, data transformations, or API serialization.
If the application supports ZIP+4, it should preserve the hyphen or normalize the value consistently according to its chosen format. Not every address requires the extended code, so the schema should accept the formats appropriate for the application.
Validating State Abbreviations and Required Fields
A regular expression is a useful starting point for validating a state abbreviation, but it cannot confirm that the abbreviation is official.
For example, the pattern ^[A-Z]{2}$ accepts TX, CA, and NY, but it also accepts ZZ.
A stronger approach is to use the enum keyword to define the allowed values. A short example might look like this:
{
"type": "string",
"enum": ["CA", "FL", "HI", "NY", "TX"]
}This is only an illustrative subset, not a complete list of US state and territory abbreviations. A nationwide application should maintain the complete set of codes it intends to support.
Developers must also understand how required fields work. Defining a property inside properties does not automatically make that property mandatory. It must also appear in the required array.
This allows fields such as addressLine2 to remain optional. A customer who lives in a house without an apartment number should not be forced to invent one.
These small design choices help make address forms more flexible while keeping the application’s essential data consistent.
Handling Different Address Types
As Michael expanded the application, he realized that a basic street address schema did not cover every customer.
Some customers needed to enter a PO box. Others required additional delivery information. Instead of making every field mandatory, he considered using an addressType property to distinguish between supported address types.
JSON Schema supports conditional rules through keywords such as if, then, and else. These can make certain fields mandatory depending on the value of another property.
For example, an application could require streetAddress when addressType is streetAddress, or require poBoxNumber when addressType is poBox.
The exact structure should follow the application’s business rules. Developers should not assume that every address can be represented by a street number and street name.
It is also important to test conditional schemas carefully. An incorrectly designed condition may reject valid records or allow incomplete ones through.
How to Validate Address JSON in Your Application
Creating a schema is only the first step. Your application also needs a JSON Schema validator that evaluates address objects against the rules.
The general process is straightforward:
- Receive the address object from a form or API request.
- Validate the object against the selected schema.
- Identify missing fields, incorrect data types, and formatting errors.
- Return clear messages that help the user correct the problem.
- Perform additional postal address validation if the application requires it.
- Store or process the accepted address according to your application’s requirements.
For example, if postalCode is missing, the validator should report that a required property is absent. If the value is 12AB, it should fail the ZIP Code pattern.
A good application should translate technical validation errors into understandable messages. Instead of displaying a lengthy schema error to a customer, the interface could say, “Enter a ZIP Code using five digits or the ZIP+4 format.”
Developers should also validate data on the server, even if the frontend performs validation. Client-side checks improve usability, but requests can bypass the frontend entirely.
The official JSON Schema specification and JSON Schema examples provide further guidance on schema structure and validation behavior. <Cite refs={[“turn416819search1″,”turn416819search3”]}/>
JSON Schema Validation Versus Postal Address Validation
Michael eventually discovered that a structurally valid address could still be incorrect.
An address might contain a valid-looking street name, a two-letter state abbreviation, and a five-digit ZIP Code, yet fail to match an actual postal address. JSON Schema cannot independently verify the existence of a street or confirm that a ZIP Code corresponds to the submitted location.
When an application needs postal verification, developers should use an appropriate address validation service.
The United States Postal Service provides an Addresses API that can validate and standardize domestic addresses, look up ZIP Codes, and return related address information. Its official documentation describes how the service standardizes street addresses, city and state names, and ZIP Codes according to USPS addressing standards. <Cite refs={[“turn416819search2″,”turn416819search4”]}/>
United States Postal Service address: 475 L’Enfant Plaza SW, Washington, DC 20260, United States.
Developers can review the USPS Addresses API documentation before integrating postal validation into their application.
The two layers serve different purposes. JSON Schema checks whether data follows the application’s rules. Postal validation checks address information against the capabilities and reference data of a postal service.
Use both when the application requires both structural consistency and real postal address verification. Check the API’s current access requirements, terms of use, and supported functions before deployment.
Common Mistakes to Avoid When Designing an Address Schema
A schema can improve data quality, but overly restrictive or poorly designed rules can create new problems.
Using numbers for ZIP Codes: This can remove leading zeros. Always store postal codes as strings.
Making every property mandatory: Apartment and suite information is not relevant to every address. Require only the fields your application genuinely needs.
Assuming a regular expression proves validity: A pattern can check the format of a ZIP Code or state abbreviation, but it cannot verify postal correctness.
Rejecting legitimate address formats: Real addresses can include unit numbers, rural routes, PO boxes, and other variations. Design for the address types your application supports.
Ignoring schema versioning: Changes to required properties or field names can break existing API clients. Document changes and consider backward compatibility.
Trusting frontend validation alone: Validate incoming data on the server as well.
Using real customer addresses unnecessarily in tests: Synthetic test data can reduce exposure of personal information. Clearly label test records and keep them separate from production data.
Best Practices for Maintaining Your JSON Schema
As an application grows, its address schema should evolve in a controlled way.
Keep the schema version explicit and use a validator that supports the selected JSON Schema draft. Add descriptions to fields so other developers understand their purpose. Maintain a tested list of supported state codes, and use realistic examples to test both valid and invalid data.
Review the schema whenever the application adds a new address type or changes its API contract. If several services share the same address structure, distribute the schema as a versioned resource so every service can use the same definition.
It is also worth reviewing how your validator handles keywords such as format. Under JSON Schema Draft 2020-12, format annotation and format assertion are distinct concepts, and validation behavior can depend on the implementation and configuration. Do not rely on a format declaration alone when a stronger check is required. <Cite refs={[“turn416819search0″,”turn416819search1”]}/>
Finally, protect address information appropriately. Limit access to customer records, avoid placing sensitive details in unnecessary logs, and retain only the data your application needs.
Conclusion: Build Better Address APIs With JSON Schema
Michael’s original problem was a missing zero in a ZIP Code. The underlying issue, however, was the absence of consistent rules for address data.
By introducing a JSON Schema for US addresses, he established a clear contract for the information his application accepted. Required fields became predictable, ZIP Codes retained their formatting, and developers had a consistent way to validate address objects across services.
For developers, JSON Schema offers a practical foundation for improving address data quality in ecommerce platforms, shipping systems, customer databases, and APIs. It makes data requirements explicit and helps catch structural errors before they spread through an application.
The most important lesson is to understand what the schema can and cannot do. It can validate data structure and formatting, but it cannot independently confirm that an address is real or deliverable.
Start with the address fields your application needs, choose suitable validation rules, and test the schema against realistic examples. Add a postal validation service when your use case requires verification against postal reference data.
With a well-designed JSON Schema and a clear validation process, developers can reduce avoidable address errors, improve API reliability, and build applications that handle US address information more consistently.