Declarations Reference

Detailed guide to all SEA™ DSL declaration types.

Entity

Purpose: Define domain concepts—things that exist.

Syntax:

entity "Name" [v <version>] [@replaces "Old" [v X]] [@changes [...]] [in <domain>]

Examples:

// Simple entity
Entity "Customer" in sales

// Versioned entity
Entity "Order" v1.0.0 in orders

// Evolution with replacement
Entity "OrderV2" v2.0.0
  @replaces "Order" v1.0.0
  @changes ["added status field", "renamed customer to buyerId"]
in orders

Resource

Purpose: Define things that flow between entities.

Syntax:

resource "Name" [Unit] [in <domain>]

Scope Resolution:

1. <unit> in <domain> — Most specific
2. in <domain> — Domain scoped
3. <unit> — Unit only

Examples:

Resource "Money" USD in finance        // Currency with unit
Resource "Token" units in auth         // Generic units
Resource "OrderItem" units in orders   // Domain-scoped
Resource "Bandwidth" bytes             // Unit only

Flow

Purpose: Define movement or transformation between entities.

Syntax:

flow "Name" from "Source" to "Target" [quantity <number>]

REQUIRED: @cqrs Annotation

Every Flow MUST have @cqrs annotation:

@cqrs { "kind": "command" }  // State change
@cqrs { "kind": "query" }    // Read operation
@cqrs { "kind": "event" }    // Notification

Additional Annotations by Kind

Complete Example:

// Command flow
Flow "CreateOrder"
  @cqrs { "kind": "command" }
  @tx { "transactional": true }
  @idempotency { "enabled": true, "key": "orderId" }
from "Customer" to "OrderAggregate" quantity 1

// Event flow
Flow "OrderCreated"
  @cqrs { "kind": "event" }
  @outbox { "mode": "required" }
from "OrderAggregate" to "EventBus"

// Query flow
Flow "GetOrderHistory"
  @cqrs { "kind": "query" }
  @read_model { "name": "OrderProjection" }
from "QueryService" to "ReadStore"

Policy

Purpose: Define business rules and constraints.

Syntax:

policy <name>
  [per <Kind> <Modality> priority <number>]
  [@rationale "..."]
  [@tags [...]]
as: <expression>

Kinds

Modalities

Examples:

// Prohibition - prevent invalid state
Policy no_negative_amount
  per Constraint Prohibition priority 10
  @rationale "Negative amounts break accounting"
as: (amount >= 0)

// Obligation - require action
Policy order_must_have_items
  per Constraint Obligation priority 10
  @rationale "Empty orders are invalid"
as: forall o in entities where o.name = "Order": (o.items > 0)

// Permission - allow action
Policy allow_discount
  per Constraint Permission priority 5
as: (discount <= 0.2)

Metric

Purpose: Define measurable KPIs and thresholds.

Syntax:

metric "Name" as: <expression>
  [@refresh_interval <N> "<unit>"]
  [@window <N> "<unit>"]
  [@threshold <number>]
  [@target <number>]
  [@unit "<string>"]
  [@severity "<string>"]

Example:

Metric "daily_payments" as:
  count(f in flows over last 24 "hours"
        where f.resource = "Money":
        f.quantity)
  @window 24 "hours"
  @threshold 1000
  @target 5000
  @unit "transactions"
  @severity "warning"
  @refresh_interval 300 "seconds"

Relation

Purpose: Define semantic triples (Subject-Predicate-Object).

Syntax:

relation "Name"
  subject: "Concept"
  predicate: "verb phrase"
  object: "Concept"
  [via: flow "FlowName"]

Example:

Relation "PurchaseAuthorization"
  subject: "Manager"
  predicate: "authorizes purchase for"
  object: "Department"
  via: flow "ApproveOrder"

Instance

Purpose: Define concrete examples for testing/scenarios.

Syntax:

instance <id> of "Entity" {
  field: <expression>,
  ...
}

Example:

instance acme_corp of "Customer" {
  name: "Acme Corporation",
  tier: "enterprise",
  credit_limit: 100000 "USD"
}

// Reference in policies
Policy acme_high_limit as: (@acme_corp.credit_limit > 50000)

ConceptChange

Purpose: Define migration between concept versions.

Syntax:

ConceptChange "Name"
  @from_version v X
  @to_version v Y
  [@migration_policy mandatory|optional]
  [@breaking_change true|false]

Example:

ConceptChange "Customer_v2_migration"
  @from_version v1.0.0
  @to_version v2.0.0
  @migration_policy mandatory
  @breaking_change true

Pattern

Purpose: Define reusable regex patterns.

Syntax:

pattern "Name" matches "<regex>"

Example:

Pattern "PhoneNumber" matches "^\\+?[1-9]\\d{1,14}$"
Pattern "UUID" matches "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

Dimension & Unit

Purpose: Define measurement systems.

Syntax:

dimension "Name"
unit "Unit" of "Dimension" factor <number> base "BaseUnit"

Example:

Dimension "Length"
Unit "meter" of "Length" factor 1 base "meter"
Unit "kilometer" of "Length" factor 1000 base "meter"
Unit "mile" of "Length" factor 1609.34 base "meter"

Last Updated: January 2026