# Specifying with .specly The complete language reference for writing SpecVerse specifications. Describe WHAT your system does; let the engines + manifests determine HOW it's built. **See also:** - [SPECVERSE-INTRO.md](SPECVERSE-INTRO.md) — philosophy and ecosystem overview - [SPECVERSE-TOOLING.md](SPECVERSE-TOOLING.md) — CLI commands (validate / infer / realize / init / gen / dev / cache / ai / session / smoke) - [SPECVERSE-REALIZING.md](SPECVERSE-REALIZING.md) — code generation, manifests, instance factories - [SPECVERSE-EXTENDING.md](SPECVERSE-EXTENDING.md) — adding entity types, engines, factories, LLM providers --- ## Contents ### Part 1: Core Concepts - [Your First Spec](#your-first-spec) - [The Three Sections](#the-three-sections) - [Convention Shorthand](#convention-shorthand) ### Part 2: Components - [Models](#models) — attributes, metadata, profiles, relationships, lifecycles, constraints, behaviors - [Controllers](#controllers) — CURVED operations and custom actions - [Services](#services) — cross-model business logic - [Events](#events) — domain events with typed payloads - [The Event System](#the-event-system) — publish / subscribe - [Views](#views) — UI specifications - [Primitives](#primitives) — custom type definitions - [Imports and Exports](#imports-and-exports) ### Part 3: Extension Entities - [Commands](#commands) — CLI generation - [Measures](#measures) — aggregation metrics - [Conventions](#conventions) — shorthand definitions - [Promotions](#promotions) — domain extension example - [Distributions](#distributions) — packaging (IDE / CLI / npm / Docker) ### Part 4: Deployments - [Deployment Structure](#deployment-structure) - [Instance Types Reference](#instance-types-reference) - [Operation Policies](#operation-policies) - [Autoscaling and Resources](#autoscaling-and-resources) - [Namespaces](#namespaces) ### Part 5: Examples - [Personal Blog (simple)](#personal-blog) - [E-Commerce (business scale)](#e-commerce) - [Enterprise SaaS (enterprise scale)](#enterprise-saas) ### Part 6: Reference - [Type Reference](#type-reference) - [Convention Cheat Sheet](#convention-cheat-sheet) --- ## Your First Spec A `.specly` file defines WHAT your system does, not HOW it's built: ```yaml components: TaskManager: version: "1.0.0" description: "A simple task management system" models: Task: attributes: id: UUID required unique title: String required description: String priority: String values=[low,medium,high] default=medium dueDate: DateTime lifecycles: status: flow: todo -> in_progress -> done ``` That's a complete, valid spec. The inference engine generates the rest — controllers, services, events, views — from this minimal definition. See [SPECVERSE-REALIZING.md](SPECVERSE-REALIZING.md) for what inference expands this into. ## The Three Sections Every `.specly` file has three top-level sections: ```yaml components: # WHAT the system does MyApp: models: ... controllers: ... services: ... events: ... views: ... deployments: # WHERE it runs development: instances: ... manifests: # HOW it's built (technology choices) implementation: capabilityMappings: ... ``` **components** define the logical architecture. **deployments** define runtime topology. **manifests** (or a separate manifest YAML file) map abstract capabilities to concrete technology implementations. ## Convention Shorthand SpecVerse reduces boilerplate by 90% with shorthand conventions: ```yaml # Attribute pattern: name: Type modifiers email: Email required unique verified name: String required age: Integer min=0 max=150 price: Money min=0 default=9.99 status: String values=[active,inactive,suspended] default=active tags: String[] optional # Array of strings createdAt: DateTime auto=now id: UUID auto=uuid4 # Relationship pattern: name: type Target modifiers author: belongsTo User posts: hasMany Post cascade tags: manyToMany Tag through=PostTag profile: hasOne Profile dependent # Lifecycle shorthand status: flow: draft -> published -> archived ``` Full [Convention Cheat Sheet](#convention-cheat-sheet) at the end. --- ## Models Models are the foundation. Everything else is derived from them. ### Attributes Attributes use convention shorthand — type followed by modifiers: ```yaml models: Product: attributes: id: UUID required unique # Type + boolean modifiers email: Email required unique # Built-in Email type price: Money min=0 default=9.99 # Key=value modifiers status: String values=[a,b,c] # Enum values tags: String[] # Array type ``` **Available types:** `String`, `Integer`, `Number`, `Boolean`, `UUID`, `DateTime`, `Date`, `Email`, `URL`, `Money`, `JSON`, plus custom primitives. **Available modifiers:** `required`, `optional`, `unique`, `searchable`, `verified`, `default=`, `min=`, `max=`, `values=[]`, `auto=` (e.g. `auto=now`, `auto=uuid4`, `auto=autoincrement`, `auto=sequence`). ### Identity: who generates the value `auto=` declares **who owns a field's value**: | `auto=` | Meaning | Realize | Interpreter | |---|---|---|---| | `uuid4` | SpecVerse generates a UUID | `@default(uuid())` | generated | | `autoincrement` | DB-assigned integer key | `@default(autoincrement())` | generated | | `now` | timestamp at write | `@default(now())` | generated | | *(none, on a field named `id`)* | primary-key convention → generated | `@default(uuid())` | generated | | **`none` / `provided` / `external`** | **issued OUTSIDE SpecVerse — require it as input, never generate** | `@id` with **no default**, required | required, never synthesised | `auto=none` (aka `provided` / `external`) is the **externally-owned / opaque key**: a primary key or id supplied by another system (e.g. a Firebase/Replit-Auth uid). It **overrides** the "a field named `id` is auto-generated" convention, so both the realized backend and the runtime interpreter require it as input rather than inventing a value. `spv ai analyse` infers it automatically when a Prisma/Drizzle source declares a primary key with no generator. ```yaml User: attributes: id: String required auto=none # the auth provider issues this id; we don't email: Email required unique ``` For complex cases use the explicit form: ```yaml attributes: status: type: String required: true default: "active" values: ["active", "inactive", "suspended"] ``` ### Metadata Metadata generates synthetic fields automatically. Don't manually define fields that metadata generates. ```yaml models: Post: metadata: id: uuid # Generates id field (uuid|integer|auto|composite|manual) audit: timestamps: true # Adds createdAt, updatedAt users: true # Adds createdBy, updatedBy softDelete: true # Adds deletedAt, isDeleted status: publishing # Status from lifecycle name version: true # Optimistic locking counter label: [title] # Display label field(s) ``` **Metadata options:** | Option | Description | Generated fields | |--------|-------------|------------------| | `id` | ID generation strategy | `id` field with specified type | | `label` | Display label field(s) | Used by UIs for entity display | | `audit.timestamps` | Timestamp tracking | `createdAt`, `updatedAt` | | `audit.users` | User tracking | `createdBy`, `updatedBy` | | `softDelete` | Soft delete support | `deletedAt`, `isDeleted` | | `status` | Status field | From lifecycle or explicit values | | `version` | Optimistic locking | Version counter | ### Attribute Categories Every attribute is auto-classified into one of three categories at parse time so consumers don't need name-based heuristics: - **`business`** — user-facing domain data (title, price, status) - **`metadata`** — synthetic / system fields (id, createdAt, updatedAt, version) - **`relationship`** — foreign-key scalars for belongsTo relations Forms hide `metadata` by default. List views colour-code `relationship` columns blue and `lifecycle` columns purple. ### Profiles Profiles attach reusable configuration to models. Define a model as a profile with `profile-attachment`: ```yaml models: Product: attributes: id: UUID required unique name: String required price: Money required DigitalProductProfile: description: "Profile for digital products" attributes: downloadUrl: String required fileSize: String license: String required profile-attachment: profiles: [Product] # This profile attaches to Product PhysicalProductProfile: description: "Profile for physical products" attributes: weight: Number required dimensions: String profile-attachment: profiles: [Product] ``` A `Product` can have both a `DigitalProductProfile` and a `PhysicalProductProfile` attached simultaneously — composition without inheritance. ### Relationships ```yaml relationships: orders: hasMany Order cascade # One-to-many, cascade delete customer: belongsTo Customer # Many-to-one (FK on this model) profile: hasOne Profile # One-to-one tags: manyToMany Tag through=PostTag # Many-to-many via junction ``` **Four relationship types:** | Type | Meaning | Inverse | Example | |------|---------|---------|---------| | `hasMany` | One-to-many | `belongsTo` | `posts: hasMany Post` | | `hasOne` | One-to-one | `belongsTo` | `profile: hasOne Profile` | | `belongsTo` | Many-to-one | `hasMany`/`hasOne` | `author: belongsTo User` | | `manyToMany` | Many-to-many | `manyToMany` | `tags: manyToMany Tag` | **Modifiers:** `cascade`, `dependent`, `eager`, `lazy`, `optional`, `through=ModelName`. ### Lifecycles State machines on models. The shorthand syntax: ```yaml lifecycles: order: flow: draft -> submitted -> confirmed -> shipped -> delivered ``` Or detailed form: ```yaml lifecycles: order: states: [pending, paid, processing, shipped, delivered, cancelled] transitions: pay: pending -> paid process: paid -> processing ship: processing -> shipped deliver: shipped -> delivered cancel: "* -> cancelled" # from any state ``` Multiple independent lifecycles per model are supported: ```yaml models: Article: lifecycles: editorial: flow: draft -> in_review -> approved publication: flow: unpublished -> scheduled -> published -> archived seo: flow: unoptimized -> optimized -> needs_review ``` Each lifecycle generates its own `evolve` operation, events (`{Model}Evolved`), and state-dependent UI (dropdowns, badges). ### Constraints Runtime business rules that gate when an entity can be created, updated, deleted, or evolved. Constraints live on the model itself and fire across **every** CURVED operation that mutates it — not on a specific behavior. ```yaml models: Vote: attributes: choice: String required relationships: voter: belongsTo User poll: belongsTo Poll constraints: - on: [create] requires: "Poll is open" - on: [create, update] requires: "Vote's choice is set" ``` (For "one vote per (voter, poll)" use a compound `unique` — not a constraint; see [Compound uniqueness](#compound-uniqueness--unique-a-b) below.) Each entry is `{on: [...ops], requires: ''}`. The operation list accepts `create` / `update` / `delete` / `evolve` (or `evolve.` for a specific transition). `requires:` is a single predicate string written in either **schema-layer form** or **natural-language sugar**. **How constraints are enforced** — five surfaces, all driven from the same predicate: | Mode | Surface | What it does | |---|---|---| | α | FK dropdown | Disables options that would violate a constraint — both single-FK rules (closed Polls disabled in Vote's poll picker) and **cross-relation FK-equality** (once a Poll is chosen, options from other Polls disable, scoping the dropdown to the selection) | | γ | Preflight | `POST /api//validate` fires before any mutation; failure surfaces in the form before the real request goes out | | δ | Button disable | `+ Add `, Edit, Delete, Evolve buttons disable with the constraint's text as tooltip when the parent state would fail | | ε | Error display | `FormViolationsPanel` (form-top) + inline `FieldError` (per-field) + `ValidationToast` (auto-dismiss) for server-returned violations | | ζ | Pending checks | Informational blue panel listing constraints that need server-side context (subqueries, actor checks) — "Checked at submit time" | #### Predicate vocabulary The predicate is parsed top-down through nine **sugar conventions**. The first one whose pattern matches wins; if no sugar applies, you fall back to the **schema-layer form** (raw path-op-value). | Convention | Pattern | Example input | Desugars to | |---|---|---|---| | `model_is_state` | `{Model} is {state}` | `"Poll is open"` | `self.poll.votingStatus == "open"` (auto-traverses belongsTo) | | `actor_has_role` | `{Actor} has role:{role}` | `"User has role:admin"` | `actor.role == "admin"` | | `actor_has_not_verb_on_target` | `{Actor} has not {verb} on {Target}` | `"User has not voted on Poll"` | `not Vote.exists(__v => __v.voter == actor and __v.poll == self.poll)` — **actor-based** (needs auth; compares to the logged-in user). For *data-level* "one row per combination" (e.g. one vote per voter+poll where `voter` is a field, not the actor), use a **compound `unique`** instead, not this sugar — see below. | | `actor_is_self_relation` | `{Actor} is {Model}.{relation}` | `"User is Vote.voter"` | `self.voter == actor` (ownership) | | `attr_is_set` | `{Model}'s {field} is set` | `"Vote's choice is set"` | `self.choice != null` | | `path_op_value` | `{lhs} {op} {rhs}` | `"self.endDate > self.startDate"` | `self.endDate > self.startDate` (paths on both sides; either path may end in a **derived FK** like `self.option.pollId` — see cross-relation FK-equality below) | | `lhs_in_list` | `{lhs} in {list}` | `'self.choice in ["yes", "no"]'` | `Set("yes", "no").contains(self.choice)` | | `path_op_qstring` | `{path} {op} {"qstring"}` | `'self.poll.votingStatus == "open"'` | (identity — already schema-layer form) | | `path_op_number` | `{path} {op} {number}` | `"self.viewCount > 100"` | (identity) | Two special variables are always in scope: - **`self`** — the entity being mutated (with relations traversed via dots: `self.poll.votingStatus`) - **`actor`** — the authenticated user from `request.user`. Null when no auth middleware is wired; constraints that reference `actor.*` paths fail-OPEN (logged, treated as pass) until auth lands #### Compound predicates `and` / `or` / `not` compose the sugars or the schema-layer form: ```yaml constraints: # Authors can only edit their own draft posts. - on: [update] requires: "User is Post.author and Post is draft" # Bypass for moderators. - on: [update, delete] requires: '(User is Post.author and Post is draft) or User has role:moderator' # Date sanity check. - on: [create, update] requires: "self.endDate > self.startDate" ``` #### Worked example: the Poll / Option / Vote pattern ```yaml models: Poll: attributes: question: String required lifecycles: votingStatus: flow: "draft -> open -> closed" relationships: options: hasMany Option Option: attributes: label: String required relationships: poll: belongsTo Poll Vote: # One vote per (voter, poll) — a COMPOUND UNIQUE on the FK columns. This is # DATA-level uniqueness (a DB unique index), NOT a validate-centric guard: # a "has this voter already voted?" pre-check is a TOCTOU race in a # multi-user world. See "Compound uniqueness" below. unique: [[voterId, pollId]] relationships: voter: belongsTo User poll: belongsTo Poll option: belongsTo Option constraints: - on: [create] requires: "Poll is open" # mode α/δ/γ/ε - on: [create] requires: "self.option.pollId == self.pollId" # the chosen option must belong to the selected poll ``` At runtime: - Vote's poll picker only shows Polls in `open` state (α) - Once a Poll is chosen, the **option** picker disables options that belong to a *different* poll — `self.option.pollId == self.pollId` scopes the FK dropdown (α). Before a poll is picked, all options are selectable. - "+ Add Vote" on a closed Poll is disabled (δ) - A duplicate `(voter, poll)` is rejected **atomically by the DB unique index** (`@@unique([voterId, pollId])`); the poll-open + chosen-option guards fire at write time (γ/ε) > **`self.option.pollId`** is a *derived FK* — `belongsTo poll` exposes a `pollId` column even though it isn't a declared attribute. Constraint paths may reference these (`self..Id`) as a terminal segment, which is how cross-relation FK-equality (one record's parent must match another's) is expressed. Enforced server-side in both the interpreter and the realized backend. #### Constraints vs behavioral `requires:` — they are different `model.constraints[].requires:` (this section) gates **CURVED operations on the model itself**. It runs automatically across create/update/delete/evolve. `behaviors..requires:` (next section) is a **precondition on one specific behavior** — declarative documentation that doesn't yet auto-enforce. The two share the word `requires` but live at different levels: behaviors are operation contracts; constraints are model invariants. Rule of thumb: if the rule should hold across **every** way the entity could change, write it as a model constraint. If it only matters for a specific operation, write it as a behavior's `requires:`. #### Author errors fail loud — broken constraints block spec load If a constraint references something that doesn't resolve — typo'd field, missing lifecycle, unknown sugar shape — the parser produces a hard error and the spec refuses to load. For example, this spec: ```yaml Vote: constraints: - on: [create] requires: "self.poll.deletedAt == null" # Poll has no deletedAt ``` …fails immediately with: ``` Component 'PollSystem', model 'Vote': could not expand constraint requires="self.poll.deletedAt == null" — no matching convention or invalid path (check that all referenced models/attributes/relationships exist). ``` This is intentional. Silently shipping a constraint that does nothing is the worst failure mode — author thinks the rule is enforced when it isn't. Fix the typo, add the missing field, or remove the constraint before the spec loads. ### Compound uniqueness — `unique: [[a, b]]` Some rules are about **uniqueness across rows**, not one record's state — e.g. *"one vote per (voter, poll)"*. These are **not** validate-centric constraints. A "does a row with this combination already exist?" pre-check followed by an insert is a **TOCTOU race** in a multi-user world: two concurrent requests both pass the check, then both write — exactly the duplicate the rule meant to prevent. The only correct enforcement is a **database unique index**, which makes the check-and-write atomic. Declare it at the model level: ```yaml Vote: unique: [[voterId, pollId]] # at most one row per (voterId, pollId) relationships: voter: belongsTo User poll: belongsTo Poll ``` Each inner array is a tuple of column names that must be unique *together*. Single-column uniqueness stays at the attribute level (`email: Email required unique`). Reference a belongsTo FK by its derived `Id` column name (`voterId`, `pollId`). - **Realized backend:** a real DB unique index — Prisma `@@unique([voterId, pollId])` / SQL `UNIQUE (voterId, pollId)` — atomic, race-safe. - **app-demo interpreter:** mirrors the invariant with an in-memory check, so the demo rejects the same duplicates (Define-Once). > Note the distinction from `voter` being a *field* vs the *actor*: "one vote per voter+poll" is data-level (`unique` over the `voterId`/`pollId` columns), independent of who is logged in. The `{Actor} has not {verb} on {Target}` sugar is for genuinely *actor*-scoped rules (the authenticated user), which need auth wired. > > **Rule of thumb:** per-row / contextual rules → a `constraint`; cross-row invariants (uniqueness, "at most N of X") → DB-atomic (`unique`), never a read-then-write guard. #### Lifecycles imply attributes (you don't declare both) Declaring a `lifecycles:` block on a model auto-synthesizes a corresponding attribute with the lifecycle name + a `