@eventcatalog/language-server 0.1.0

package/specification/06-channel.md

@@ -0,0 +1,131 @@
+# Channel
+
+A communication channel (topic, queue, exchange, etc.).
+
+```
+channel <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  address "<address-string>"
+  protocol "<protocol>"
+
+  // Channel parameters
+  parameter <name> {
+    description "<text>"
+    default "<value>"
+    enum ["<val1>", "<val2>"]
+    examples ["<ex1>", "<ex2>"]
+  }
+
+  // Routing
+  route <channel-ref>            // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## Channel-to-Channel Routing
+
+Channels can route to other channels using the `route` statement. This models message pipelines where data flows through multiple channels (e.g., Kafka topic → Kafka topic → MQTT broker):
+
+```
+channel SensorIngestion {
+  version 1.0.0
+  protocol "Kafka"
+  route SensorFiltered
+}
+
+channel SensorFiltered {
+  version 1.0.0
+  protocol "Kafka"
+  route MqttDevices
+}
+
+channel MqttDevices {
+  version 1.0.0
+  protocol "MQTT"
+}
+```
+
+This creates a chain: `SensorIngestion → SensorFiltered → MqttDevices`.
+
+A channel can route to multiple targets (fan-out):
+
+```
+channel Ingestion {
+  version 1.0.0
+  route Analytics
+  route Archive
+}
+```
+
+Routes can include versioned references:
+
+```
+channel Source {
+  version 1.0.0
+  route Target@2.0.0
+}
+```
+
+## Service-to-Channel Routing
+
+Services send/receive messages through channels:
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Simple — no channel
+  sends event OrderCreated
+
+  // To a single channel
+  sends event OrderCreated to orders-topic
+
+  // To a channel with version (using @ syntax)
+  sends event OrderCreated to orders-topic@1.0.0
+
+  // To multiple channels (comma-separated)
+  sends event OrderCreated to orders-topic, orders-backup-topic
+
+  // To multiple channels with versions
+  sends event OrderCreated to orders-topic@1.0.0, orders-backup-topic@2.0.0
+
+  // Receiving from a single channel
+  receives event PaymentProcessed from payment-events
+
+  // Receiving from multiple channels
+  receives event PaymentProcessed from payment-events, payment-retry-queue
+
+  // Receiving from channels with versions
+  receives event PaymentProcessed from payment-events@1.0.0, payment-retry-queue@2.1.0
+}
+```
+
+## EBNF
+
+```ebnf
+channel_decl     = "channel" identifier "{" common_props
+                   { channel_body_item } "}" ;
+channel_body_item= address_prop | protocol_prop | parameter_decl
+                 | route_stmt | annotation ;
+address_prop     = "address" string_lit ;
+protocol_prop    = "protocol" string_lit ;
+parameter_decl   = "parameter" identifier "{" { param_prop } "}" ;
+param_prop       = "description" string_lit
+                 | "default" string_lit
+                 | "enum" "[" string_lit { "," string_lit } "]"
+                 | "examples" "[" string_lit { "," string_lit } "]" ;
+route_stmt       = "route" resource_ref ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+```

package/specification/08-container.md

@@ -0,0 +1,54 @@
+# Container
+
+A data store, cache, or external system.
+
+```
+container <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Required
+  container-type <database | cache | objectStore | searchIndex
+                 | dataWarehouse | dataLake | externalSaaS | other>
+
+  // Optional
+  deprecated true
+  draft true
+  technology "<tech-string>"     // e.g., "postgres@15", "redis@7"
+  authoritative true
+  access-mode <read | write | readWrite | appendOnly>
+  classification <public | internal | confidential | regulated>
+  residency "<location>"
+  retention "<duration>"         // e.g., "90d", "10y"
+
+  // Relationships
+  service <service-ref>          // repeatable
+
+  // Annotations
+  @badge(...)
+  @repository(...)
+}
+```
+
+## EBNF
+
+```ebnf
+container_decl   = "container" identifier "{" common_props
+                   { container_body_item } "}" ;
+container_body_item = container_type_prop | technology_prop
+                    | authoritative_prop | access_mode_prop
+                    | classification_prop | residency_prop
+                    | retention_prop
+                    | service_ref_stmt | annotation ;
+container_type_prop   = "container-type" container_type_enum ;
+container_type_enum   = "database" | "cache" | "objectStore" | "searchIndex"
+                      | "dataWarehouse" | "dataLake" | "externalSaaS" | "other" ;
+technology_prop       = "technology" string_lit ;
+authoritative_prop    = "authoritative" bool_lit ;
+access_mode_prop      = "access-mode" ( "read" | "write" | "readWrite" | "appendOnly" ) ;
+classification_prop   = "classification" ( "public" | "internal" | "confidential" | "regulated" ) ;
+residency_prop        = "residency" string_lit ;
+retention_prop        = "retention" string_lit ;
+```

package/specification/09-data-product.md

@@ -0,0 +1,39 @@
+# Data Product
+
+An analytical data product.
+
+```
+data-product <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+  deprecated true
+  draft true
+
+  // Data lineage
+  input <message-type> <resource-ref>      // repeatable
+  output <message-type> <resource-ref> {   // repeatable, with optional contract
+    contract {
+      path "<path>"
+      name "<name>"
+      type "<type>"
+    }
+  }
+
+  // Annotations
+  @badge(...)
+}
+```
+
+## EBNF
+
+```ebnf
+data_product_decl = "data-product" identifier "{" common_props
+                    { dp_body_item } "}" ;
+dp_body_item      = input_stmt | output_stmt | annotation ;
+input_stmt        = "input" message_type resource_ref ;
+output_stmt       = "output" message_type resource_ref [ "{" contract_block "}" ] ;
+contract_block    = "contract" "{" "path" string_lit "name" string_lit
+                    [ "type" string_lit ] "}" ;
+```

package/specification/10-flow.md

@@ -0,0 +1,163 @@
+# Flow
+
+Flows define step-by-step business processes using a PM-friendly `when`-block syntax. Resources are referenced by name only — types are resolved from the catalog.
+
+```
+flow <id> {
+  version <semver>
+  name "<display name>"
+  summary "<text>"
+  owner <owner-ref>
+
+  // Entry chain — the starting sequence
+  <Name> ["<label>"] -> <Name> ["<label>"] -> ...
+
+  // When blocks — react to events
+  when <TriggerName>
+    <ServiceName> "<description>"
+      -> "<label>": <OutputName>
+
+  // Convergence — multiple triggers must complete
+  when <TriggerA> and <TriggerB>
+    <ServiceName> "<description>"
+}
+```
+
+## Actors and External Systems
+
+To use actors and external systems in flows, define them as top-level resources. The flow resolves their type automatically by name:
+
+```
+actor Customer {
+  name "Customer"
+  summary "End user on the storefront"
+}
+
+external-system WarehouseWMS {
+  name "Warehouse WMS"
+  summary "Legacy warehouse management system"
+}
+```
+
+Both support optional bodies with `name`, `summary`, and annotations. They can also be bare (no body):
+
+```
+actor Customer
+external-system WarehouseWMS
+```
+
+## Flow References
+
+Resources in flows are referenced by name only (no type keywords like `service` or `event`). Types are resolved from catalog definitions or sibling `.ec` files. If no matching definition is found, the default type is `step`. Compilers may warn on unresolved flow references.
+
+Each reference can include an optional label:
+
+- `Customer "places an order"` — name with display label
+- `PlaceOrder` — bare name (no label)
+- `PaymentService "processes the payment"` — service with description
+
+## Entry Chains
+
+The entry chain defines the starting sequence of a flow. It uses arrow (`->`) syntax:
+
+```
+Customer "places an order"
+  -> PlaceOrder
+  -> OrderService "creates the order"
+  -> OrderCreated
+```
+
+Multiple sources can converge into a chain using commas:
+
+```
+EventA, EventB -> MergingService
+```
+
+## When Blocks
+
+`when` blocks define reactions to events. Each block starts with one or more trigger names, followed by actions:
+
+```
+when OrderCreated
+  PaymentService "processes the payment"
+    -> "success": PaymentProcessed
+    -> "failure": PaymentFailed
+  InventoryService "reserves stock"
+    -> StockReserved
+```
+
+### Labeled Outputs
+
+Action outputs can have optional labels (quoted strings followed by a colon):
+
+```
+-> "success": PaymentProcessed    // labeled output
+-> StockReserved                   // unlabeled output
+```
+
+### Convergence
+
+Use `and` to require multiple triggers before actions execute:
+
+```
+when PaymentProcessed and StockReserved
+  FulfillmentService "ships the order"
+    -> OrderShipped
+```
+
+### Terminal Actions
+
+Actions without outputs are terminal steps:
+
+```
+when OrderShipped
+  WarehouseWMS "syncs with legacy WMS"
+  NotificationService "notifies the customer"
+```
+
+## Example
+
+```
+flow OrderFulfillment {
+  version 1.0.0
+  name "Order Fulfillment"
+  summary "End-to-end order processing from placement to delivery"
+  owner fulfillment-team
+
+  Customer "places an order"
+    -> PlaceOrder
+    -> OrderService "creates the order"
+    -> OrderCreated
+
+  when OrderCreated
+    PaymentService "processes the payment"
+      -> "success": PaymentProcessed
+      -> "failure": PaymentFailed
+    InventoryService "reserves stock"
+      -> StockReserved
+
+  when PaymentFailed
+    NotificationService "notifies the customer of failure"
+
+  when PaymentProcessed and StockReserved
+    FulfillmentService "ships the order"
+      -> OrderShipped
+
+  when OrderShipped
+    WarehouseWMS "syncs with legacy WMS"
+    NotificationService "notifies the customer"
+      -> CustomerNotified
+}
+```
+
+## EBNF
+
+```ebnf
+flow_decl         = "flow" identifier "{" common_props
+                    { flow_entry_chain | flow_when_block } "}" ;
+flow_entry_chain  = flow_ref { "," flow_ref } ( "->" flow_ref )+ ;
+flow_when_block   = "when" flow_ref { "and" flow_ref } flow_action+ ;
+flow_action       = flow_ref { flow_output } ;
+flow_output       = "->" [ string_lit ":" ] flow_ref ;
+flow_ref          = identifier [ string_lit ] ;
+```

package/specification/11-diagram.md

@@ -0,0 +1,3 @@
+# Diagram
+
+_Removed from V1. May be added in a future version._

package/specification/12-user.md

@@ -0,0 +1,54 @@
+# User
+
+A user definition for ownership and team membership.
+
+```
+user <id> {
+  name "<display name>"
+  avatar "<url>"
+  role "<role>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+
+  // Team membership
+  team <team-id>
+
+  // Ownership declarations
+  owns domain <id>
+  owns service <id>
+  owns event <id>
+  owns command <id>
+  owns query <id>
+}
+```
+
+## Example
+
+```
+user dboyne {
+  name "David Boyne"
+  avatar "https://avatars.githubusercontent.com/u/3268013"
+  role "Principal Engineer"
+  email "david@company.com"
+
+  owns domain Payment
+  owns service PaymentService
+}
+```
+
+## EBNF
+
+```ebnf
+user_decl         = "user" identifier "{" user_props "}" ;
+user_props        = "name" string_lit
+                  | "avatar" string_lit
+                  | "role" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | owns_stmt
+                  | "team" identifier ;
+owns_stmt         = "owns" resource_type_kw identifier ;
+resource_type_kw  = "domain" | "service" | "event" | "command" | "query" ;
+```

package/specification/13-team.md

@@ -0,0 +1,62 @@
+# Team
+
+A team definition for ownership and membership.
+
+```
+team <id> {
+  name "<display name>"
+  summary "<text>"
+  email "<email>"
+  slack "<url>"
+  ms-teams "<url>"
+
+  // Members
+  member <user-id>               // repeatable
+
+  // Ownership declarations
+  owns domain <id>
+  owns service <id>
+  owns event <id>
+  owns command <id>
+  owns query <id>
+}
+```
+
+## Owner References
+
+Owners are referenced by team or user ID:
+
+```
+service OrderService {
+  version 1.0.0
+  owner payment-team              // team reference
+  owner dboyne                   // user reference
+}
+```
+
+## Example
+
+```
+team orders-team {
+  name "Orders Team"
+  summary "Responsible for order lifecycle"
+  email "orders@company.com"
+  slack "https://company.slack.com/channels/orders"
+
+  member dboyne
+  member jane-doe
+}
+```
+
+## EBNF
+
+```ebnf
+team_decl         = "team" identifier "{" team_props "}" ;
+team_props        = "name" string_lit
+                  | "summary" string_lit
+                  | "email" string_lit
+                  | "slack" string_lit
+                  | "ms-teams" string_lit
+                  | "member" identifier
+                  | owns_stmt ;
+```

package/specification/14-relationships.md

@@ -0,0 +1,89 @@
+# Relationships & Pointers
+
+## Resource References
+
+Resources can be referenced by ID alone (resolves to `latest`) or with an explicit version:
+
+```
+// Reference by ID only (latest version)
+receives event OrderCreated
+
+// Reference by ID + version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Reference with single channel routing
+sends event OrderCreated to orders-topic
+
+// Reference with channel version
+sends event OrderCreated@1.0.0 to orders-topic@1.0.0
+
+// Reference with multiple channels
+sends event OrderCreated to orders-topic, backup-topic
+receives event PaymentProcessed from payment-events, payment-retry
+```
+
+## Inline vs. Reference
+
+Resources can be defined inline (creating them) or referenced (linking to existing):
+
+```
+service OrderService {
+  version 1.0.0
+
+  // Inline definition — creates the event
+  sends event OrderCreated {
+    version 1.0.0
+    summary "A new order was placed"
+  }
+
+  // Reference only — links to an existing event
+  receives event PaymentProcessed
+  receives event PaymentProcessed@2.0.0
+}
+```
+
+Inline messages do not support the `channel` statement — use `to`/`from` on the `sends`/`receives` statement for channel routing.
+
+## Pointer Syntax Summary
+
+| Syntax                        | Meaning                       |
+| ----------------------------- | ----------------------------- |
+| `<id>`                        | Latest version of resource    |
+| `<id>@<version>`              | Specific version              |
+| `<id> to <channel>`           | With single channel routing   |
+| `<id> to <channel>@<version>` | Channel with specific version |
+| `<id> to <ch1>, <ch2>, <ch3>` | Multiple channels             |
+| `<id> from <channel>`         | Received from channel         |
+| `<id> from <ch1>, <ch2>`      | Received from multiple        |
+
+## Data Relationships
+
+```
+writes-to container <container-ref>
+reads-from container <container-ref>
+```
+
+## EBNF
+
+```ebnf
+resource_ref     = identifier [ "@" version_lit ] ;
+message_type     = "event" | "command" | "query" ;
+
+sends_stmt       = "sends" message_type resource_ref [ channel_clause ]
+                 | "sends" message_type identifier inline_block ;
+receives_stmt    = "receives" message_type resource_ref [ channel_clause ]
+                 | "receives" message_type identifier inline_block ;
+
+channel_clause   = to_clause | from_clause ;
+to_clause        = "to" channel_ref_list ;
+from_clause      = "from" channel_ref_list ;
+channel_ref_list = channel_ref { "," channel_ref } ;
+channel_ref      = identifier [ "@" version_lit ] ;
+
+writes_to_stmt   = "writes-to" "container" resource_ref ;
+reads_from_stmt  = "reads-from" "container" resource_ref ;
+flow_ref_stmt    = "flow" resource_ref ;
+data_product_ref_stmt      = "data-product" resource_ref ;
+
+inline_block     = "{" message_props "}" ;
+```

package/specification/15-versioning.md

@@ -0,0 +1,41 @@
+# Versioning
+
+## Declaring Versions
+
+Every versioned resource requires a version:
+
+```
+event OrderCreated {
+  version 1.0.0
+}
+```
+
+## Referencing Versions
+
+```
+// Latest (default - no version specified)
+receives event OrderCreated
+
+// Specific version using @ syntax
+receives event OrderCreated@2.0.0
+
+// Channel with version
+sends event OrderProcessed to payments-channel@1.0.0
+
+// Multiple channels with versions
+receives event PaymentFailed from channel-a@1.0.0, channel-b@2.1.0
+```
+
+## Version Defaults
+
+When no version is specified in a reference, it resolves to `latest`.
+
+## EBNF
+
+```ebnf
+int              = digit { digit } ;
+version_lit      = int "." int "." int [ "-" prerelease ] ;
+version_prop     = "version" version_lit ;
+version_ref      = "@" version_lit ;
+resource_ref     = identifier [ version_ref ] ;
+```