OpenForm
SDKPrimitives

address

Last updated on

Build and validate postal addresses

Build and validate postal addresses with structured components. The Address primitive provides a standardized structure for capturing location information.

Examples

Creating addresses

// Object pattern
const addr = open.address({
  line1: '123 Main Street',
  locality: 'New York',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// Builder pattern
const addr = open.address()
  .line1('123 Main Street')
  .line2('Suite 400')
  .locality('New York')
  .region('NY')
  .postalCode('10001')
  .country('US')
  .build()

// Copy and modify
const updated = open.address()
  .from(addr)
  .line2('Suite 500')
  .build()

Parsing external data

// Parse unknown input (throws on error)
const addr = open.address.parse(jsonData)

// Safe parsing (returns result object)
const result = open.address.safeParse(jsonData)
if (result.success) {
  console.log(`${result.data.locality}, ${result.data.region}`)
} else {
  console.error(result.error.message)
}

Using with forms

const form = open.form({
  name: 'shipping',
  fields: {
    shippingAddress: { type: 'address', label: 'Shipping Address' }
  }
})

const filled = form.fill({
  fields: {
    shippingAddress: open.address()
      .line1('456 Oak Avenue')
      .locality('Los Angeles')
      .region('CA')
      .postalCode('90001')
      .country('US')
      .build()
  }
})

API

Object Pattern

open.address(input: Address): Address

Pass an Address object for validation. Returns the validated Address or throws on error.

const addr = open.address({
  line1: '123 Main St',
  locality: 'Boston',
  region: 'MA',
  postalCode: '02101',
  country: 'US'
})

Builder Pattern

Chain methods to build an Address value incrementally:

All methods return AddressBuilder and are chainable.

open.address()
line1: (value: string) => AddressBuilder
Set primary street address
line2: (value: string | undefined) => AddressBuilder
Set secondary address (apt, suite)
locality: (value: string) => AddressBuilder
Set city or town
region: (value: string) => AddressBuilder
Set state, province, or region
postalCode: (value: string) => AddressBuilder
Set postal or ZIP code
country: (value: string) => AddressBuilder
Set country code (ISO 3166-1 alpha-2)
from: (value: Address) => AddressBuilder
Initialize from existing Address
build: () => Address
Build and validate

Static Methods

parse: (input: unknown) => Address
Parse unknown input (throws on error)
safeParse: (input: unknown) => Result<Address>
Parse unknown input (returns result object)

Properties

line1: string
Primary street address line.
line2: string?
Secondary address line (apartment, suite, unit).
locality: string
City, town, or locality name.
region: string
State, province, or region.
postalCode: string
Postal code or ZIP code.
country: string
Country code (ISO 3166-1 alpha-2 recommended).

Validation

The Address primitive validates:

  • line1 must be a non-empty string
  • locality must be a non-empty string
  • region must be a non-empty string
  • postalCode must be a non-empty string
  • country must be a non-empty string
  • line2 is optional
// Valid
open.address({
  line1: '123 Main St',
  locality: 'NYC',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// With optional line2
open.address({
  line1: '123 Main St',
  line2: 'Apt 4B',
  locality: 'NYC',
  region: 'NY',
  postalCode: '10001',
  country: 'US'
})

// Invalid - throws Error
open.address({ line1: '123 Main St' })
// Error: Invalid Address: locality is required

Related

Primitives

Build and validate primitive data types

bbox

Build and validate bounding boxes

On this page

ExamplesCreating addressesParsing external dataUsing with formsAPIObject PatternBuilder PatternStatic MethodsPropertiesValidationRelated