Data Spec

Reference for the Data Spec format — document structure, fields, and validation rules.

This page describes the structure of a Data Spec document. A Data Spec describes the logical data model of an application — business entities, their fields, and relationships. It is not a physical database schema but a conceptual model that AI agents can interpret to generate database schemas, API endpoints, validation logic, and more.

For methodology and workflows, see How It Works. For advanced techniques, see Patterns & Practices.

Public format file: data-spec-format-0-0-1.yaml

Document Root

A Data Spec document is a YAML file with the following top-level fields.

Field	Type	Required	Description
`docType`	string	yes	Always `data-spec`
`format_version`	string	yes	Format version (e.g., `"0.0.1"`)
`metadata`	object	yes	Document metadata
`description`	string	no	Detailed description of the system
`enums`	object	no	Enumeration definitions
`entities`	object	yes	Entity definitions (the core of the spec)
`relations`	array	no	Relationships between entities
`diagram`	object	no	Visualization settings

Metadata

The metadata object describes the data model.

Field	Type	Required	Description
`name`	string	yes	Name of the system or data model
`version`	string	no	Version of this Data Spec
`author`	string	no	Author name
`created_at`	date	no	Creation date
`updated_at`	date	no	Last update date
`description_short`	string	no	One-line summary

Description

An optional multi-line text field at the document root. Describes the system's purpose, goals, and main capabilities.

description: |
  Task management system for small teams.
  Supports projects, tasks with deadlines, and team collaboration.
  Integrates with calendar and notification services.

Enums

Enumerations define fixed sets of values used by entity fields. Each enum is defined under enums with a unique name (snake_case).

Short Form

For simple enums without descriptions per value.

enums:
  task_status:
    values: [draft, active, completed, archived]
    description: "Lifecycle status of a task"

Full Form

For enums where each value needs a label or description.

enums:
  priority:
    description: "Task priority level"
    values:
      - name: low
        label: Low
        description: "Can be done when time allows"
      - name: medium
        label: Medium
        description: "Should be done this week"
      - name: high
        label: High
        description: "Must be done today"
      - name: critical
        label: Critical
        description: "Requires immediate attention"

Entities

Entities are the core of a Data Spec. Each entity represents a business object and is defined under entities with a unique name (snake_case).

Field	Type	Required	Description
`label`	string	no	Human-readable name
`description`	string	no	What this entity represents
`table_name`	string	no	Database table name if different from the entity name
`fields`	object	yes	Field definitions
`unique_constraints`	array	no	Composite unique constraints

Fields

Each field is defined under fields with a unique name (snake_case).

Field	Type	Required	Description
`type`	string	yes	Data type (see below)
`label`	string	no	Human-readable field name
`description`	string	no	What this field represents
`required`	boolean	no	Field is required for business logic (default: false)
`pk`	boolean	no	Primary key (default: false)
`unique`	boolean	no	Unique constraint (default: false)
`default`	any	no	Default value (e.g., `now`, `uuid_generate_v4()`, or a literal)
`fk`	string	no	Foreign key reference in format `entity_name.field_name`

Field Types

Seven base logical types are available.

Type	Description
`string`	Text value
`integer`	Whole number
`decimal`	Number with decimal precision
`boolean`	True or false
`datetime`	Date and time
`uuid`	Universally unique identifier
`json`	Arbitrary JSON structure

A field type can also reference an enum name defined in the enums section.

fields:
  status:
    type: task_status    # references the task_status enum
    required: true

Unique Constraints

Composite unique constraints define combinations of fields that must be unique together.

unique_constraints:
  - [project_id, task_number]
  - [user_id, email_type]

Entity Example

entities:
  task:
    label: Task
    description: "A unit of work assigned to a user within a project"
    fields:
      id:
        type: uuid
        pk: true
      title:
        type: string
        required: true
        description: "Task title"
      status:
        type: task_status
        required: true
        default: draft
      priority:
        type: priority
        required: true
        default: medium
      due_date:
        type: datetime
        description: "Deadline for the task"
      project_id:
        type: uuid
        required: true
        fk: project.id
      assignee_id:
        type: uuid
        fk: user.id
      created_at:
        type: datetime
        default: now
    unique_constraints:
      - [project_id, title]

Relations

Relations describe logical relationships between entities. Each relation is bidirectional (entity_a ↔ entity_b) with a specified cardinality.

Field	Type	Required	Description
`entity_a`	string	yes	First entity name
`entity_b`	string	yes	Second entity name
`cardinality`	string	yes	`one_to_one`, `one_to_many`, or `many_to_many`
`label`	string	no	Short relationship name (e.g., `"contains"`, `"assigns"`)
`description`	string	no	Detailed description of the relationship

Cardinality Types

Cardinality	Meaning	Example
`one_to_one`	Each A has exactly one B	User → Profile
`one_to_many`	Each A has many B	Project → Tasks
`many_to_many`	A has many B, B has many A	Students ↔ Courses

Relations Example

relations:
  - entity_a: project
    entity_b: task
    cardinality: one_to_many
    label: "contains"
    description: "A project contains multiple tasks"

  - entity_a: user
    entity_b: task
    cardinality: one_to_many
    label: "is assigned"
    description: "A user can be assigned to multiple tasks"

  - entity_a: user
    entity_b: project
    cardinality: many_to_many
    label: "participates in"
    description: "Users participate in multiple projects, projects have multiple members"

Diagram

Optional visualization settings for ER diagrams. Used by Spec Canvas to render entity relationship diagrams.

Field	Type	Required	Description
`format`	string	no	Visualization format (e.g., `mermaid`)
`hints`	object	no	Layout hints for diagram nodes

Node Hints

Each entity can have optional positioning and styling hints under hints.nodes.

Field	Type	Description
`x`	number	Horizontal position
`y`	number	Vertical position
`group`	string	Logical group or subdomain name
`color`	string	Node color (hex)

diagram:
  format: mermaid
  hints:
    nodes:
      project:
        x: 100
        y: 100
        group: core
        color: "#4CAF50"
      task:
        x: 300
        y: 100
        group: core
        color: "#2196F3"

Using with UI Spec

When a Data Spec and a UI Spec exist in the same project, the UI Spec can reference entities and fields in block purposes. AI agents understand these references and use them for type-safe code generation.

# In a UI Spec block:
purpose: "Form for creating a new Task. Fields: Task.title (required), Task.priority (dropdown), Task.due_date (date picker), Task.assignee_id (user selector)"

The AI agent reads the Data Spec to understand field types, constraints, enum values, and relationships — and generates appropriate UI controls, validation, and data binding. For more on integrating Data Spec with UI Spec, see Patterns & Practices.

Data Spec

On this page