Field Value schema — Data Protocol reference
Field runtime VALUE-shape contract. Reference for Address, AddressValue, CalendarDateValue, ClockTimeValue and 8 more: every property with its type and default.
Field runtime VALUE-shape contract (ADR-0104 D1).
FieldSchema owns what a field definition looks like; this module owns
what a field's runtime value looks like — the shape the write path
accepts, drivers persist, and an unexpanded API read returns. Before this
module the knowledge lived as private, hand-copied type sets in objectql's
record-validator, rest's import-coerce, driver-sql, and verify; adding one
multi-capable or JSON-shaped type meant updating four lists or silently
corrupting data. Those consumers now derive from the classes below.
Two canonical forms exist per field (ADR-0104 D1):
stored— the storage/wire form (e.g. lookup ⇒ record-id string,date⇒YYYY-MM-DD, select ⇒ option code).expanded— the enriched$expandread form (lookup ⇒ the related record object). For types without an expansion, expanded ≡ stored.
"Reality wins": where the deployed stored shape is coherent, the contract
adopts it — deployed data is a wire contract we don't get to rewrite by
editing Zod. This is why currency is a bare number (the never-consumed
CurrencyValueSchema object is deleted) and location is {lat, lng} (what field-zoo
stores), not the never-consumed {latitude, longitude} shape.
Purity: schemas/constants/derivation only — no runtime logic, no caching
(Prime Directive #2). Consumers cache valueSchemaFor results per field
definition; building a Zod schema per write is the one performance trap
this contract has (ADR-0104 performance budget).
Source: packages/spec/src/data/field-value.zod.ts
TypeScript Usage
import { AddressSchema, AddressValueSchema, CalendarDateValueSchema, ClockTimeValueSchema, FileLikeValueSchema, FileReferenceIdValueSchema, FileRefusedValueSchema, FileValueSchema, InstantValueSchema, LocationValueSchema, ReferenceIdValueSchema, ReferenceNameOnlyValueSchema } from '@objectstack/spec/data';
import type { Address, AddressValue, CalendarDateValue, ClockTimeValue, FileLikeValue, FileReferenceIdValue, FileRefusedValue, FileValue, InstantValue, LocationValue, ReferenceIdValue, ReferenceNameOnlyValue } from '@objectstack/spec/data';
// Validate data
const result = AddressSchema.parse(data);Address
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| street | string | optional | Street address |
| city | string | optional | City name |
| state | string | optional | State/Province |
| postalCode | string | optional | Postal/ZIP code |
| country | string | optional | Country name or code |
| countryCode | string | optional | ISO country code (e.g., US, GB) |
| formatted | string | optional | Formatted address string |
AddressValue
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| street | string | optional | Street address |
| city | string | optional | City name |
| state | string | optional | State/Province |
| postalCode | string | optional | Postal/ZIP code |
| country | string | optional | Country name or code |
| countryCode | string | optional | ISO country code (e.g., US, GB) |
| formatted | string | optional | Formatted address string |
CalendarDateValue
Type: string
ClockTimeValue
Type: string
FileLikeValue
Union Options
This schema accepts one of the following structures:
Option 1
Type: string
Option 2
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| url | string | ✅ | |
| name | string | optional | |
| size | number | optional | |
| mimeType | string | optional | |
| alt | string | optional | |
| durationSeconds | number | optional | Media duration in seconds |
| duration | never | optional | [REMOVED] FileValue.duration was renamed to durationSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to durationSeconds; the value (seconds) is unchanged, and a fractional second is still legal. |
FileReferenceIdValue
Type: string
FileRefusedValue
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | The sys_file id the record holds |
| metadataRefused | true | ✅ | The reader was refused the file's metadata (no read on sys_file, and the record being read does not own the file or its download verdict did not allow it): name, size and type are withheld. Distinct from an empty field, which holds no file at all. |
FileValue
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| url | string | ✅ | |
| name | string | optional | |
| size | number | optional | |
| mimeType | string | optional | |
| alt | string | optional | |
| durationSeconds | number | optional | Media duration in seconds |
| duration | never | optional | [REMOVED] FileValue.duration was renamed to durationSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to durationSeconds; the value (seconds) is unchanged, and a fractional second is still legal. |
InstantValue
Type: string
LocationValue
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| lat | number | ✅ | Latitude |
| lng | number | ✅ | Longitude |
| altitude | number | optional | Altitude in meters |
| accuracy | number | optional | Accuracy in meters |
ReferenceIdValue
Type: string
ReferenceNameOnlyValue
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | The id of the referenced record, as the referencing record holds it |
| name | string | ✅ | The referenced record's display name (its object's nameField, else displayNameField, else the derived title field), or the Record # floor with the id where a field-level rule on that field holds |
| readRefused | true | ✅ | The reader was refused the referenced record (the object's read gate or its row scope): only its id and display name are served, and the name links nothing. Distinct from an expanded record and from a bare id. |
Driver Turso
Turso / libSQL Driver Protocol. Reference for TursoConfig, TursoTransportMode: every property with its type and default.
Hook Body Doors
The two platform doors a sandboxed script body (a hook, action or job body) reaches for records it may not write itself: mail goes through the mail service.