@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/98-versioning-resources.md

@@ -0,0 +1,192 @@
+---
+sidebar_position: 98
+keywords:
+- versioning
+- resources
+- EventCatalog
+sidebar_label: Versioning resources
+title: Versioning resources
+description: Learn how versioning works for EventCatalog resources.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+EventCatalog resources can be versioned when you want to preserve how a resource looked at a point in time.
+
+Use versioning when a resource changes in a way that people may need to understand later, such as a service contract change, a message payload change, a domain boundary change, or a new major version of a system capability.
+
+## How versioning works
+
+The latest version of a resource lives in the normal resource folder.
+
+Older versions live inside a `versioned` folder under that resource. Each version has its own folder and its own `index.mdx` file.
+
+For example, a versioned service looks like this:
+
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx', highlight: true },
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '1.0.0',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+The root `index.mdx` is the current version. The file in `versioned/1.0.0/index.mdx` is the historical version.
+
+## Create a new version
+
+To create a new version:
+
+1. Copy the current resource into a new folder under `versioned/{version}`.
+2. Keep the copied file at the old version number.
+3. Update the root resource to the new version number.
+4. Update the root resource content to describe the latest state.
+
+For example, before changing `Orders` from `1.0.0` to `2.0.0`, copy the current file into `versioned/1.0.0/index.mdx`.
+
+```md title="/services/Orders/versioned/1.0.0/index.mdx"
+---
+id: Orders
+name: Orders
+version: 1.0.0
+summary: Handles order placement and order history.
+---
+
+## Overview
+
+This is the original Orders service documentation.
+```
+
+Then update the root file:
+
+```md title="/services/Orders/index.mdx"
+---
+id: Orders
+name: Orders
+version: 2.0.0
+summary: Handles order placement, order history, and order amendments.
+---
+
+## Overview
+
+This is the latest Orders service documentation.
+```
+
+## Versioned URLs
+
+EventCatalog creates versioned pages for resources that have versions.
+
+For example:
+
+| Resource | URL |
+|----------|-----|
+| Latest `Orders` service | `/docs/services/Orders` |
+| `Orders` service version `1.0.0` | `/docs/services/Orders/1.0.0` |
+
+This lets users compare the current resource with previous versions when they need historical context.
+
+## Referencing versions
+
+When one resource references another resource, you can include a `version` field when you want to point to a specific version.
+
+```md title="/services/Payments/index.mdx"
+---
+id: Payments
+name: Payments
+version: 1.0.0
+
+receives:
+  - id: OrderPlaced
+    version: 1.0.0
+---
+```
+
+Use a specific version when the relationship depends on that version of the resource.
+
+Leave the version out when the relationship should point to the latest version.
+
+```md title="/services/Payments/index.mdx"
+---
+id: Payments
+name: Payments
+version: 1.0.0
+
+receives:
+  - id: OrderPlaced
+---
+```
+
+## What can be versioned?
+
+You can version the resources you document in EventCatalog, including:
+
+- Domains
+- Systems
+- Services
+- Messages
+- Schemas and specifications
+- Data stores
+- Data products
+- Entities
+- Flows
+- Agents
+- Architecture decision records
+
+The folder location changes by resource type, but the pattern is the same: keep the latest resource in the root folder and store older versions under `versioned/{version}`.
+
+## Version numbers
+
+EventCatalog does not force a specific versioning strategy. Most teams use semantic versioning:
+
+| Version change | Use when |
+|----------------|----------|
+| Patch | Fixing documentation, examples, or non-behavioral details |
+| Minor | Adding fields, endpoints, resources, or capabilities in a backwards-compatible way |
+| Major | Removing or changing behavior, contracts, fields, routes, or ownership in a breaking way |
+
+The important part is consistency. Pick a convention your team understands and apply it across the catalog.
+
+## Versioning and changelogs
+
+Versioning preserves the old state of a resource. Changelogs explain why the resource changed.
+
+Use both when the change needs context. For example, a service can have version `2.0.0` and a changelog entry explaining that the service started publishing a new event or removed an old endpoint.
+
+## When to version
+
+Version resources when the old state still matters.
+
+Good examples include:
+
+- A breaking API or schema change.
+- A message contract changing.
+- A service or system taking on a new responsibility.
+- A domain boundary changing.
+- A resource being replaced or deprecated.
+
+You do not need to version every small documentation edit. If the change is just wording, formatting, or a small clarification, updating the current page is usually enough.

package/dist/docs/development/guides/99-adding-analytics.md

@@ -9,7 +9,6 @@ import PlanBanner from '@site/src/components/MDX/PlanBanner';
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
 <PlanBanner plan="Scale" />
-<AddedIn version="3.21.0" />
 
 EventCatalog supports analytics integrations that let you track how your team navigates and uses your catalog. Connect your existing analytics tools to understand which services, events, and flows your team visits most.
 

package/dist/docs/development/guides/changelogs/02-adding-changelogs.md

@@ -10,7 +10,7 @@ description: Creating and managing changelogs within EventCatalog.
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-Changelogs are currently supported in [domains](/docs/development/guides/domains/versioning-and-changelogs/changelog), [services](/docs/development/guides/services/versioning-and-lifecycle/changelog) and [messages](/docs/development/guides/messages/common/changelog).
+Changelogs are currently supported in [domains](/docs/development/guides/domains/add-changelog), [services](/docs/development/guides/resources/services/versioning-and-lifecycle/add-changelog) and [messages](/docs/development/guides/resources/messages/versioning-and-lifecycle/add-changelog).
 
 To add a changelog to your resources you need to create a `changelog.mdx` file.
 
@@ -91,4 +91,4 @@ Domains, services and messages have a **Changelog** button. Clicking this button
 
 Domains, services and messages all have a changelog url.
 
-See example changelog: https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog
+See example changelog: https://demo.eventcatalog.dev/docs/events/InventoryAdjusted/1.0.1/changelog

package/dist/docs/development/guides/changelogs/03-automated-changelogs.md

@@ -11,7 +11,7 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 <AddedIn version="2.7.3"/>
 
-EventCatalog allows you to store schemas, API specifications and custom files along side your domains, services and messages. For [example you can add specifications to a service](/docs/development/guides/services/adding-to-services/openapi).
+EventCatalog allows you to store schemas, API specifications and custom files along side your domains, services and messages. For [example you can add specifications to a service](/docs/development/guides/resources/schemas/add-specifications-to-services/add-openapi-specifications).
 
 When you version your resources, you can also version the files. When you do this, EventCatalog will match the current version to it's previous version and calculate if any diffs should be displayed in your changelog page.
 
@@ -41,4 +41,4 @@ If any changes have been made to the `openapi.yml` file in this example, this ch
 
 ![Automated logs](./img/automated-logs.png)
 
-[You can see the example in our demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/changelog).
+[You can see the example in our demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/changelog).

package/dist/docs/development/guides/changelogs/04-reference.md

@@ -0,0 +1,77 @@
+---
+keywords:
+- EventCatalog changelogs
+- Changelog frontmatter
+sidebar_label: Reference
+title: Changelogs reference
+description: Frontmatter fields and paths for changelogs in EventCatalog.
+---
+
+This page lists the fields and paths supported by changelogs.
+
+## Paths
+
+Changelogs can be created for versioned resources using `changelog.md` or `changelog.mdx`.
+
+```txt
+/{collection}/{Resource Name}/versioned/{version}/changelog.mdx
+```
+
+For example:
+
+```txt
+/services/PaymentService/versioned/1.0.0/changelog.mdx
+/domains/Payments/versioned/1.0.0/changelog.mdx
+```
+
+## Optional fields
+
+### `createdAt` {#createdAt}
+
+- Type: `date`
+
+Date the changelog entry was created.
+
+```md title="Example"
+---
+createdAt: 2026-05-26
+---
+```
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badge metadata for the changelog entry.
+
+```md title="Example"
+---
+badges:
+  - content: Breaking change
+    backgroundColor: red
+    textColor: red
+---
+```
+
+## Badge fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | Badge text. |
+| `backgroundColor` | `string` | Badge background color. |
+| `textColor` | `string` | Badge text color. |
+| `icon` | `string` | Optional icon. |
+
+## Example
+
+```md
+---
+createdAt: 2026-05-26
+badges:
+  - content: Breaking change
+    backgroundColor: red
+    textColor: red
+---
+
+Updated the payment authorization event contract.
+```

package/dist/docs/development/guides/changelogs/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Changelogs",
-  "position": 12,
+  "position": 14,
   "collapsible": true,
   "collapsed": true,
   "link": {
@@ -8,4 +8,4 @@
     "slug": "/changelogs",
     "description": "A collection of guides to help you understand changelogs and how they work with EventCatalog."
   }
-}
+}

package/dist/docs/development/guides/domains/01-introduction.md

@@ -1,22 +1,27 @@
 ---
 sidebar_position: 1
 keywords:
-- EventCatalog events
+- EventCatalog domains
 sidebar_label: What are domains?
-title: Understanding domains
+title: What are domains?
 description: What are domains? Why are they useful for event-driven architectures?
 ---
 
-Domain-Driven Design (DDD) is a software development approach that focuses on deeply understanding and accurately modelling the business domain. This methodology aims to enhance software quality by ensuring it aligns closely with the business requirements it supports. Eric Evans introduced DDD to the software development community in 2003 through his influential book, [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).
+In EventCatalog a domain describes a business boundary (term from Domain-Driven Design).
 
-The essence of domain-driven design lies in managing complexity by centering software development around the ‘domain,’ which is the specific business context where the software is used. DDD promotes the use of a [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), a shared vocabulary between developers and business stakeholders. This common language is used throughout the design and implementation process, ensuring that the software accurately represents the business domain it is designed to serve.
+For example, an e-commerce architecture may have domains such as `Fulfilment`, `Ordering`, `Payments` or `Shopping` and these domains may contain their own language, systems, services, events, and many more lower level resources.
 
-Domain-driven design has some core building blocks including entities, value objects, bounded context and aggregates.
+Documenting domains (and subdomains) in EventCatalog can help your teams understand busiess boundaries, team ownership and how these boundaries fit together in your organization.
+
+You can assign resources to your domains (e.g systems, services, messages) that can help your team dive deeper into a domain to understand implmentation details.
 
-**EventCatalog uses domains as a way to group services into a bounded context.**
+<details>
+    <summary>What is Domain Driven Design?</summary>
 
-**EventCatalog support subdomains, which can be used to group domains together.**
+    Domain-Driven Design (DDD) is a software development approach that focuses on deeply understanding and accurately modelling the business domain. This methodology aims to enhance software quality by ensuring it aligns closely with the business requirements it supports. Eric Evans introduced DDD to the software development community in 2003 through his influential book, [Domain-Driven Design: Tackling Complexity in the Heart of Software](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).
 
-Using domains in EventCatalog gives you a better way to manage your services and define their bounded context. 
+The essence of domain-driven design lies in managing complexity by centering software development around the ‘domain,’ which is the specific business context where the software is used. DDD promotes the use of a [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), a shared vocabulary between developers and business stakeholders. This common language is used throughout the design and implementation process, ensuring that the software accurately represents the business domain it is designed to serve.
+
+Domain-driven design has some core building blocks including entities, value objects, bounded context and aggregates.
 
-Domains can also directly specify the messages they send and receive, providing a high-level view of domain interactions.
+  </details>

package/dist/docs/development/guides/domains/{02-creating-domains/02-adding-domains.md → 02-create-domain.md}

@@ -2,29 +2,45 @@
 sidebar_position: 2
 keywords:
 - EventCatalog domains
-sidebar_label: Creating a domain
-title: Creating domains
+sidebar_label: Create a domain
+title: Create a domain
 description: Creating and managing domains within EventCatalog.
 ---
 
-Domains are a great way to group your documentation into logical units that can be represented in your organization.
+import PromptBox from '@site/src/components/MDX/PromptBox';
 
-EventCatalog Domains are inspired by the [Domain-Driven Design](/docs/development/guides/domains/introduction) approach.
+Domains are a great way to document a business boundary, define its [ubiquitous language](/docs/development/guides/domains/ownership-and-language/adding-ubiquitous-language) and group your documentation into logical units that can be represented in your organization.
 
-In EventCatalog a domain is a logical unit that contains related [services](/docs/development/guides/services/introduction), [entities](/docs/development/guides/domains/entities/introduction), [messages](/docs/development/guides/messages/overview), subdomains,  and other resources.
+Domains can contains resources (e.g [systems](/docs/development/guides/systems/introduction), [services](/docs/development/guides/resources/services/introduction), [entities](/docs/development/guides/resources/entities/introduction), [messages](/docs/development/guides/resources/messages/what-are-messages), subdomains,  and more).
 
-### What do domains look like in EventCatalog?
+![Example](../img/domains/domain-example.png)
 
-![Example](../../img/domains/domain-example.png)
+---
+
+### Creating a domain
+
+#### Automatic Creation
+
+<PromptBox preview="Create a new EventCatalog domain">
+Read https://www.eventcatalog.dev/docs/development/guides/domains/create-domain.md and https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/domains.md then help me create a new EventCatalog domain in my catalog.
+
+Ask me for the domain name, business boundary, summary and what it does. Then create the correct domains/{'{Domain Name}'}/index.mdx file with frontmatter and starter markdown, you can add as much markdown as you want that captures the users input.
 
-## Adding a new domain
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+
+
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can guide you through creating the domain, choosing the right folder structure, and adding the first version of the domain documentation.
+
+#### Manual Creation
 
 To add a new domain create a new folder within the `/domains` folder with an `index.mdx` file.
 
 - `/domains/{Domain Name}/index.mdx` 
   - (example `/domains/Orders/index.mdx`)
 
-The `index.mdx` contents are split into two sections, [**frontmatter**](/docs/api/domain-api) and the [**markdown content**](#adding-content).
+The `index.mdx` contents are split into two sections, [**frontmatter**](/docs/development/guides/domains/reference) and the [**markdown content**](#adding-content).
 
 _Here is an example of what a domain markdown file may look like._
 
@@ -72,14 +88,18 @@ Domain that contains all services that are related to the orders domain within F
 
 ```
 
-**That's it!**
-
 Once you add your domain it will appear in your catalog.
 
-## Adding content
+---
+
+## Adding content to your domain
 
 Your domain page will render the markdown content you add to the file. To add content to your domain page, add markdown to the file.
 
+EventCatalog supports [MDX](https://mdxjs.com/) under the hood. This gives you the ability to use components inside your domain page.
+
+You can find a list of EventCatalog components you can use here: [EventCatalog components](/docs/development/components/using-components).
+
 ```md title="/domains/Orders/index.mdx"
 ---
 id: Orders
@@ -99,10 +119,6 @@ Including EventCatalog components
 
 ```
 
-## Using components
-
-EventCatalog supports [MDX](https://mdxjs.com/) under the hood. This gives you the ability to use components inside your domain page.
 
-You can find a list of EventCatalog components you can use here: [EventCatalog components](/docs/development/components/using-components).
 
 

package/dist/docs/development/guides/domains/{02-creating-domains/02a-subdomains.md → 03-model-subdomains.md}

@@ -1,16 +1,13 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 keywords:
 - EventCatalog domains
-sidebar_label: Creating subdomains
-title: Creating subdomains
+sidebar_label: Model subdomains
+title: Model subdomains
 description: Creating and managing subdomains within EventCatalog.
-id: subdomains
 ---
 
-import AddedIn from '@site/src/components/MDX/AddedIn';
-
-<AddedIn version="2.34.0" />
+import PromptBox from '@site/src/components/MDX/PromptBox';
 
 Subdomains are optional in EventCatalog but can be a great way to group domains together. 
 
@@ -20,7 +17,7 @@ When you add a subdomain to a domain, your users will be able to see the relatio
 
 ### What do subdomains look like in EventCatalog?
 
-![Example](../../img/domains/subdomain-example.png)
+![Example](../img/domains/subdomain-example.png)
 
 _See [subdomain example](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
 
@@ -30,12 +27,27 @@ _See [subdomain example](https://demo.eventcatalog.dev/docs/domains/E-Commerce/1
 When you reference a subdomain from a domain, it will appear in the domains visualizer.
 You can use the legend to highlight resources that are part of a subdomain.
 
-![Domains Visualizer (with subdomains)](../../img/domains/subdomain-visualizer.png)
+![Domains Visualizer (with subdomains)](../img/domains/subdomain-visualizer.png)
 
 _See [subdomain example](https://demo.eventcatalog.dev/visualiser/domains/E-Commerce/1.0.0) in the EventCatalog Demo._
 
 ## Adding subdomains
 
+### Automatic Creation
+
+<PromptBox preview="Model subdomains in EventCatalog">
+Read https://www.eventcatalog.dev/docs/development/guides/domains/model-subdomains.md and https://github.com/event-catalog/skills/blob/main/skills/catalog-documentation-creator/references/domains.md then help me model subdomains in my EventCatalog catalog.
+
+Ask me for the parent domain, subdomain names, business boundaries, and summaries. Then create the correct domains/{'{Parent Domain}'}/subdomains/{'{Subdomain Name}'}/index.mdx files and update the parent domain frontmatter to reference each subdomain.
+
+You can use MDX components found here https://raw.githubusercontent.com/event-catalog/skills/refs/heads/main/skills/catalog-documentation-creator/references/components.md
+
+</PromptBox>
+
+Copy this prompt and paste it into your coding agent. Your agent can help you decide which domains should become subdomains, create the right folder structure, and update the parent domain references.
+
+### Manual Creation
+
 A subdomain is just another domain resource. But a parent domain references the subdomains.
 
 First you need to create your subdomain.
@@ -50,7 +62,7 @@ You can create a subdomain in the `/domains` folder or in a `/subdomains` folder
 
 Once you have created your subdomain, you can reference it from your parent domain.
 
-### Referencing subdomains
+#### Referencing subdomains
 
 To add a `subdomain` to a `domain` you need to reference the `subdomain` from the `domain` markdown file.
 

package/dist/docs/development/guides/domains/03-ownership-and-language/01-owners.md

@@ -12,7 +12,7 @@ description: Adding owners to domains with EventCatalog.
 
 You can assign owners to your domains to provide context of who owns this domain and how to contact them.
 
-Owners in EventCatalog are either [**users**](/docs/development/guides/owners/users/introduction) or [**teams**](/docs/development/guides/owners/teams/introduction) and are **optional**.
+Owners in EventCatalog are either [**users**](/docs/development/guides/owners/what-are-teams-and-users) or [**teams**](/docs/development/guides/owners/what-are-teams-and-users) and are **optional**.
 
 ## Adding owners to a domain
 

package/dist/docs/development/guides/domains/03-ownership-and-language/02-adding-ubiquitous-language.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 2
 keywords:
 - EventCatalog domains
 sidebar_label: Ubiquitous language
@@ -9,8 +9,6 @@ description: Creating a Ubiquitous-language dictionary for your domain
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="2.16.0" />
-
 Ubiquitous Language is a shared language that is used by all stakeholders in a project/domain to improve communication and reduce misunderstandings.
 
 In EventCatalog you can define a dictionary of ubiquitous language terms for your domain, this can help your teams understand the language used in your domain and models used in your architecture.
@@ -23,7 +21,7 @@ To add a ubiquitous language dictionary, create a new file within your domain fo
 
 The contents of the file should be a list of terms used in your domain. 
 
-Each term should have a name, summary, description and icon. The icon is optional and can be used to visually represent the term. You can find a list of icons [here](https://lucide.dev/).
+Each term should have a name, summary, description and icon. The icon is optional and can be used to visually represent the term. You can find a list of icons [here](https://lucide.dev/). Use the PascalCase React component name for Lucide icons, for example `file-text` should be configured as `FileText`.
 
 ```md title="/domains/Orders/ubiquitous-language.md"
 ---
@@ -71,5 +69,3 @@ Clicking on a term in the Domain Language explorer will open that term in a new
 
 
 
-
-

package/dist/docs/development/guides/domains/03-ownership-and-language/_category_.json

@@ -1,10 +1,10 @@
 {
   "label": "Ownership & language",
-  "position": 2,
+  "position": 5,
   "collapsible": true,
   "collapsed": true,
   "link": {
     "type": "generated-index",
     "slug": "/ownership-and-language"
   }
-}
+}