@open-form/serialization

OpenForm is documents as code. It lets developers and AI agents define, validate, and render business documents using typed, composable schemas. This eliminates template drift, broken mappings, and brittle glue code — while giving AI systems a reliable document layer they can safely read, reason over, and generate against in production workflows.

Package overview

Locale and region-aware serialization of OpenForm primitive types (Money, Address, Phone, Person, Organization) into human-readable string representations.

- Multi-locale support - USA, EU, and international serializers built-in
- Pluggable architecture - Implement custom serializers via SerializerRegistry interface
- Accessibility-ready - Simple patterns for screen reader and accessibility-focused formatting
- Type-safe - Full TypeScript support

Installation

``bash
npm install @open-form/serialization
`

Usage

$3

Import a pre-configured serializer and use them directly:

`typescript
import { usaSerializers } from "@open-form/serialization";

// USA serializers (default - uses USD, US address format, formatted phone)
usaSerializers.money.stringify({ amount: 1500, currency: "USD" });
// → "$1,500.00"

usaSerializers.address.stringify({
line1: "123 Main St",
locality: "New York",
region: "NY",
postalCode: "10001",
country: "USA",
});
// → "123 Main St, New York, NY, 10001, USA"
`

$3

Create serializer instances with specific regional configurations:

`typescript
import { createSerializer } from "@open-form/serialization";

// Create serializers for different regions
const usaSerializers = createSerializer({ regionFormat: "us" });

// Use them to serialize data
const price = usaSerializers.money.stringify({
amount: 99.99,
currency: "USD",
});
// -> "$99.99"
`

$3

Configure fallback values that are used when serialization fails (e.g., when data is null or invalid). The default is an empty string ("").

`typescript
import { createSerializer } from "@open-form/serialization";

const serializers = createSerializer({
regionFormat: "us",
fallbacks: {
money: "N/A",
address: "Address not available",
phone: "–",
person: "Unknown person",
organization: "Unnamed organization",
party: "Unknown party",
coordinate: "No coordinates",
bbox: "No bounds",
duration: "No duration",
identification: "No ID",
},
});

// When serialization fails, the configured fallback is returned
serializers.money.stringify(null);
// → "N/A"

serializers.address.stringify(null);
// → "Address not available"
`

If no fallback is configured for a serializer type, an empty string is used by default:

`typescript
const serializers = createSerializer({ regionFormat: "us" });

serializers.money.stringify(null);
// → ""
`

$3

Each serializer registry provides these stringifiers:

| Type | Stringifier Signature | Returns | Description |
| ---------------- | -------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------- |
| money | stringify(Money \| number \| Partial): string | string | Serializes monetary amounts with currency symbol and locale-specific grouping |
| address | stringify(Address \| Partial