Type System

7.1 Four-Tier Architecture

ADL uses a closed type system organized into four tiers of increasing specialization, plus a content type category for rich UI fields. Every field in a resource MUST declare a type from this system. No custom types can be defined — the type system is fixed by this specification.

The tiers reflect the level of semantic meaning the platform attaches to the stored value:

• Tier 0 — Core: Fundamental data types with direct database mappings. Every application uses these.
• Tier 1 — Extended: Specialized storage types with format-specific behavior. Used when a core type lacks the needed semantics.
• Tier 2 — Specialized: Types with built-in validation or security behavior. Used for specific data concerns.
• Tier 3 — Domain: Types with business-domain semantics and format standards. Used for internationalization, finance, and visual identity.
• Content Types: Types for rich, structured content that requires specialized editing and rendering. Used in CMS, publishing, and UI-heavy domains.

7.2 Tier 0 — Core Types

Ten fundamental types that map directly to database primitives.

Usage Notes

string vs text: Use string for short, constrained values (names, titles, codes) where a maximum length is meaningful. Use text for long-form content (descriptions, bodies, notes) where length is unconstrained. Both map to TEXT in SQLite; in PostgreSQL, string maps to VARCHAR(n) and text maps to TEXT.

decimal precision: The decimal type stores values as strings in the JSON API and in SQLite to avoid floating-point precision loss. In PostgreSQL, it uses NUMERIC(p,s). Always specify precision and scale for financial values:

price:
  type: decimal
  precision: 10
  scale: 2
  min: 0

uuid auto-generation: By default, the id field is auto-generated as a UUID v4 on create. The client-submitted value is ignored. To allow client-provided IDs (for imports, migrations, or deterministic seeding), set allowUserProvided: true:

id:
  type: uuid
  primaryKey: true
  allowUserProvided: true

7.3 Tier 1 — Extended Types

Six types with format-specific behavior beyond core storage.

Slug Auto-Generation

A slug field requires a from attribute specifying the source field:

slug:
  type: slug
  unique: true
  from: title

The slug is generated by converting the source field’s value to lowercase, replacing spaces and non-alphanumeric characters with hyphens, and removing consecutive hyphens. The slug is regenerated on create and whenever the source field changes on update.

If the generated slug conflicts with an existing record’s slug (violating the unique constraint), the server appends a numeric suffix (-1, -2, etc.) until the slug is unique.

7.4 Tier 2 — Specialized Types

Five types with built-in validation or security behavior.

Array Configuration

The array type supports typed items and length constraints:

tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

Arrays are stored as JSON strings in the database.

7.5 Tier 3 — Domain Types

Nine types with business-domain semantics tied to international standards.

Money Type

The money type is designed for financial values where floating-point precision loss is unacceptable:

amount:
  type: money
  min: 0
  required: true

Money values are stored as strings in the API (JSON) and as TEXT in SQLite / NUMERIC(19,4) in PostgreSQL. The runtime converts between string and numeric representations for arithmetic operations (computed fields, aggregation).

For currency-aware money fields, pair with a currency field:

price:
  type: money
  min: 0
currency:
  type: currency
  default: USD

7.6 Content Types

Seven types for rich, structured content that requires specialized editors and renderers. These types store complex data as JSON in the database.

media — File References

featuredImage:
  type: media
  accept: [image/jpeg, image/png, image/webp]
  maxSize: 5mb
  minWidth: 800
  minHeight: 600
  aspectRatio: "16:9"

Media files are uploaded via multipart/form-data and stored in the media library. The field value is a JSON object containing the file metadata and reference:

{
  "id": "550e8400-...",
  "filename": "hero.jpg",
  "mimeType": "image/jpeg",
  "size": 245760,
  "width": 1920,
  "height": 1080,
  "url": "/media/550e8400-.../hero.jpg"
}

The media library tracks references from resources to media items, enabling orphan detection (§18.2).

svg — Sanitized Vector Graphics

logo:
  type: svg
  maxSize: 50kb

SVG content is sanitized on write to remove potentially dangerous elements and attributes (scripts, event handlers, external references). The sanitizer:

• Strips <script> elements
• Strips event handler attributes (onclick, onload, etc.)
• Strips external references (xlink:href to external URLs)
• Strips comments and metadata elements
• Preserves structural SVG elements (<svg>, <path>, <rect>, <circle>, <g>, <text>, etc.)

blocks — Block Editor Content

content:
  type: blocks
  allowedBlocks: [paragraph, heading, image, code, list, callout]
  maxBlocks: 100

Blocks content is stored as a JSON array of block objects:

[
  {
    "type": "paragraph",
    "content": "Introduction text."
  },
  {
    "type": "heading",
    "content": "Section Title",
    "props": { "level": 2 }
  },
  {
    "type": "code",
    "content": "const x = 42;",
    "props": { "language": "javascript" }
  },
  {
    "type": "callout",
    "content": "Important note.",
    "props": { "type": "warning", "title": "Caution" }
  }
]

Custom block types are defined in the blocks: section of the domain (§18.3).

icon — Icon Set Reference

statusIcon:
  type: icon
  iconSets: [lucide, custom]

Stores an icon identifier in the format set:name (e.g., "lucide:check-circle"). The iconSets constraint limits which icon sets are valid. Icon sets are configured in the icons: section of the domain.

font — Font Reference

headingFont:
  type: font
  sources: [google, system]

Stores a font family name (e.g., "Inter"). The sources constraint limits where fonts can be loaded from. Font sources are configured in the fonts: section of the domain.

component — Nested Object

address:
  type: component
  object:
    street: { type: string, required: true }
    city: { type: string, required: true }
    state: { type: string, maxLength: 2 }
    zip: { type: string, pattern: "^[0-9]{5}$" }
    country: { type: country, default: "US" }
  collapsed: false

A component is a single nested object with typed fields. It is stored as a single JSON column. Components do not have their own id, are not independently queryable, and cannot participate in relationships. Use relationships for data that needs to be shared or queried independently.

The object definition MAY use $ref to reference a shared object:

seo:
  type: component
  object: { $ref: '#/objects/SEO' }
  collapsed: true

repeater — Ordered Array of Objects

lineItems:
  type: repeater
  sortable: true
  minItems: 1
  maxItems: 50
  object:
    productId: { type: uuid, required: true }
    quantity: { type: integer, min: 1, required: true }
    unitPrice: { type: decimal, required: true }
    notes: { type: text }

A repeater is an ordered array of objects, each conforming to the same field definitions. It is stored as a single JSON array column.

7.7 Field Constraints

Constraints restrict the values a field can hold. They are declared alongside the field type and are enforced at the API boundary on every create and update operation.

Universal Constraints

Available on all field types:

String Constraints

Numeric Constraints

Date/Time Constraints

Enum Constraint

The enum constraint restricts a string field to a fixed set of values. It can be declared inline or by reference:

# Inline enum values
priority:
  type: string
  enum: [low, medium, high, critical]
  default: medium

# Reference to a domain-level enum
status:
  type: string
  enum: PostStatus

# Or via $ref
status:
  $ref: '#/enums/PostStatus'
  default: draft

All three forms produce identical runtime behavior. The $ref form is preferred when the enum carries rich metadata (§9).

Field Security

7.8 Auto-Generated Fields

Several field types have auto-generation behavior managed by the server:

autoNow

The autoNow property automatically sets a datetime field to the current timestamp:

createdAt:
  type: datetime
  autoNow: create    # Set once on creation, never updated

updatedAt:
  type: datetime
  autoNow: always    # Set on every create and update

Fields with autoNow are auto-managed — client-submitted values for these fields are silently ignored.

Slug Auto-Generation

slug:
  type: slug
  unique: true
  from: title

The from property specifies the source field. The slug is regenerated whenever the source field changes. See §7.3 for the generation algorithm.

UUID Auto-Generation

Fields with type: uuid and primaryKey: true are auto-generated as UUID v4 on create. Client-submitted values are ignored unless allowUserProvided: true:

id:
  type: uuid
  primaryKey: true
  allowUserProvided: true    # Accept client-provided UUIDs

Autoincrement

orderNumber:
  type: autoincrement

Autoincrement fields are assigned the next sequential integer on create. They are read-only — client-submitted values are ignored. Autoincrement values are never reused, even after deletion.

7.9 Complete Type Reference

Total: 37 types across 5 categories.

Spatial type (v0.3.1): the geometry / geojson field type — GeoJSON values with optional geometryType/srid, PostGIS-backed storage, and spatial query operators — is specified in Chapter 41 — GIS & Spatial Data.

End of Chapter 7.

Next: Chapter 8 — Relationships