ObjectStackObjectStack

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 $expand read 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

PropertyTypeRequiredDescription
streetstringoptionalStreet address
citystringoptionalCity name
statestringoptionalState/Province
postalCodestringoptionalPostal/ZIP code
countrystringoptionalCountry name or code
countryCodestringoptionalISO country code (e.g., US, GB)
formattedstringoptionalFormatted address string

AddressValue

Properties

PropertyTypeRequiredDescription
streetstringoptionalStreet address
citystringoptionalCity name
statestringoptionalState/Province
postalCodestringoptionalPostal/ZIP code
countrystringoptionalCountry name or code
countryCodestringoptionalISO country code (e.g., US, GB)
formattedstringoptionalFormatted 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

PropertyTypeRequiredDescription
urlstring✅
namestringoptional
sizenumberoptional
mimeTypestringoptional
altstringoptional
durationSecondsnumberoptionalMedia duration in seconds
durationneveroptional[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

PropertyTypeRequiredDescription
idstring✅The sys_file id the record holds
metadataRefusedtrue✅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

PropertyTypeRequiredDescription
urlstring✅
namestringoptional
sizenumberoptional
mimeTypestringoptional
altstringoptional
durationSecondsnumberoptionalMedia duration in seconds
durationneveroptional[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

PropertyTypeRequiredDescription
latnumber✅Latitude
lngnumber✅Longitude
altitudenumberoptionalAltitude in meters
accuracynumberoptionalAccuracy in meters

ReferenceIdValue

Type: string


ReferenceNameOnlyValue

Properties

PropertyTypeRequiredDescription
idstring✅The id of the referenced record, as the referencing record holds it
namestring✅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
readRefusedtrue✅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.

On this page