@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/guides/owners/users/02-adding-users.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog users
+sidebar_label: Creating a user
+title: Creating users
+description: Creating and managing users within EventCatalog.
+---
+
+Adding a user to your Catalog is a great way to add an owner for a domain, service or message.
+
+### What do users look like in EventCatalog?
+
+![Example](../../img/users/example.png)
+
+## Adding a new user
+
+To add a new user, create a new file within the `/users` folder with an `md` file.
+
+- `/users/{user id}.mdx` 
+  - (example `/users/dboyne.mdx`)
+
+The `md` contents are split into two sections, **frontmatter** and the **markdown content**.
+
+_Here is an example of what a user markdown file may look like._
+
+```md title="/users/full-stack.md (example)"
+---
+# id of the user
+id: dboyne
+
+# display name for the user
+name: David Boyne
+
+# URL path for a profile image
+avatarUrl: "https://pbs.twimg.com/profile_images/1262283153563140096/DYRDqKg6_400x400.png"
+
+# users role in the company
+role: Lead developer
+
+# optional user email address
+email: test@test.com
+
+# optional slack link to DM the user
+slackDirectMessageUrl: https://yourteam.slack.com/channels/boyney123
+---
+
+## Overview
+
+<!-- Contents about the user -->
+
+```
+
+**That's it!**
+
+Once you add your new user to EventCatalog, it will now show in the docs.
+
+## Adding content
+
+With **users** you can write any Markdown you want and it will render on your page. Every command gets its own page.
+
+Users do not support custom components.
+
+### Tips for user content
+
+It's entirely up to you what you want to add to your users markdown content but here are a few things you might want to consider.
+
+- Context of the user. Who are they? 
+- Contact info for the user?
+

package/dist/docs/development/guides/owners/users/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Users",
+  "position": 12,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/users",
+    "description": "A collection of guides to help you understand users and how they work with EventCatalog."
+  }
+}

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

@@ -0,0 +1,64 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Schemas
+sidebar_label: Getting started
+title: Getting started with schemas
+description: Getting started with schemas in EventCatalog
+---
+
+EventCatalog supports **any schema or specification format**, including (but not limited to):
+
+- JSON / YAML
+- Avro
+- Protobuf
+- GraphQL
+- OpenAPI
+- AsyncAPI
+
+Schemas are **optional**, but they add valuable context to your messages and services by making data structures explicit and discoverable.
+
+---
+
+## Why add schemas?
+
+By adding schemas to your messages and services, you unlock several benefits:
+
+- **Schema Explorer** – Quickly find and browse schemas [(see demo)](https://demo.eventcatalog.dev/schemas/explorer)
+- **Fields Explorer** – Browse every schema field catalog-wide, search across formats, and trace fields to the services that produce and consume them [(see guide)](/docs/development/guides/schemas/fields-explorer)
+- **API access** – Access schemas programmatically through the EventCatalog API [(see guide)](/docs/development/guides/schemas/schema-api)
+- **Ask questions** – Query and explore schemas using the [EventCatalog MCP](/docs/development/ask-your-architecture/mcp-server/introduction)
+- **Visualization** – Help developers understand data structures using [schema property search and visualization](/docs/development/components/components/schema-viewer)
+- **Field Usage** – Track which services depend on specific fields to understand the impact of schema changes [(see guide)](/docs/development/guides/schemas/field-usage)
+
+---
+
+## Adding schemas to messages
+
+You can attach one or more schemas to any message type:
+
+- **Commands** -
+- **Queries**
+- **Events**
+
+Get started by following the relevant guide:
+
+- [Adding schemas to commands](/docs/development/guides/messages/common/adding-schemas)
+- [Adding schemas to queries](/docs/development/guides/messages/common/adding-schemas)
+- [Adding schemas to events](/docs/development/guides/messages/common/adding-schemas)
+
+---
+
+## Adding specifications to services
+
+In addition to message-level schemas, services can render full API and messaging specifications, including:
+
+- **AsyncAPI**
+- **OpenAPI**
+- **GraphQL**
+
+Use the guides below to add specifications to your services:
+
+- [Adding AsyncAPI specifications to services](/docs/development/guides/services/adding-to-services/asyncapi)
+- [Adding OpenAPI specifications to services](/docs/development/guides/services/adding-to-services/openapi)
+- [Adding GraphQL schemas to services](/docs/development/guides/services/adding-to-services/graphql)

package/dist/docs/development/guides/schemas/02-schema-explorer.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Schemas
+sidebar_label: Schema Explorer
+title: Schema Explorer
+description: Explore your schemas in the Schema Explorer
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.64.0" />
+
+The Schema Explorer is a powerful tool that allows your team to quickly find, filter and understand your schemas in your Architecture (see [demo](https://demo.eventcatalog.dev/schemas)). 
+
+Your teams can quickly find the schema, who owns it, who is producing or consuming it and get API (GET) access to your schemas for mocking or testing.
+
+The schema explorer supports any schema format, including JSON, YAML, Avro, Protobuf, GraphQL, OpenAPI, AsyncAPI, etc.
+
+![Example](./img/schema-explorer.png)
+
+Using the Schema Explorer, you can:
+
+- Quickly find schemas in your Architecture
+- View diffs between versions of your schemas
+- Quickly find who is consuming or producing your schemas
+- Schema ownership to query who owns a schema
+- Get API (GET) access to your schemas for mocking or testing
+
+### How to use the Schema Explorer?
+
+You can access the Schema Explorer from the sidebar, or by going to the `/schemas/explorer` page.
+
+The page will take all the schemas from your EventCatalog and render them in a searchable list.
+
+:::tip Schema Path
+You need to set the `schemaPath` in your schema frontmatter to the path to your schema file for Events, Queries and Commands.
+
+For services you need to specify the path to your specification file in the `specifications` frontmatter.
+:::
+
+The Schema Explorer is a powerful tool that allows your team to quickly find and understand your schemas in your Architecture (see [demo](https://demo.eventcatalog.dev/schemas)). The schema explorer supports any schema format, including JSON, YAML, Avro, Protobuf, GraphQL, OpenAPI, AsyncAPI, etc.
+
+![Example](./img/schema-explorer-2.png)
+
+##### Filters
+You can use the filters to quickly find schemas in your Architecture. You can filter by name, message type and schema format.
+
+##### Schema Preview
+
+The schema preview will show you a preview of the schema in a readable format, you can use the `Schema` button to switch between different views of your schema (if they are supported, JSON or Avro).
+
+##### API Access
+
+For EventCatalog Scale users, you can get API (GET) access to your schemas for mocking or testing. 
+
+##### Producers and Consumers
+
+The producers and consumers section will show you who is producing or consuming the schema. You can click on the producer or consumer to see more information about them.
+
+### Turn off the Schema Explorer
+
+You can hide the Schema Explorer by setting the it's visibility to `false` in your `eventcatalog.config.js` file.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  sidebar: [
+    {
+        id: '/schemas/explorer',
+        visible: false,
+    }
+  ]
+};
+```

package/dist/docs/development/guides/schemas/03-schema-api.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Schemas
+sidebar_label: Get access to your schemas via API
+title: Schema API
+description: Get API (GET) access to your schemas for mocking or testing
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+<AddedIn version="2.64.0" />
+<EventCatalogPro plan="Scale" />
+
+Your EventCatalog schemas for your Events, Queries, Commands and Services can be accessed via API (GET requests).
+
+:::info OpenAPI specification
+You can find the OpenAPI specification for the Schema API [here](https://github.com/event-catalog/eventcatalog/blob/main/eventcatalog-api-openapi.yaml).
+:::
+
+### Message Schemas
+
+The Message Schemas API allows you to get the schema for a specific event, query or command.
+
+```
+GET /api/schemas/events/{eventId}/{version}
+GET /api/schemas/queries/{queryId}/{version}
+GET /api/schemas/commands/{commandId}/{version}
+```
+
+You can also get the latest version of the schema by omitting the version parameter.
+
+```
+GET /api/schemas/events/{eventId}/latest
+GET /api/schemas/queries/{queryId}/latest
+GET /api/schemas/commands/{commandId}/latest
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `eventId` | The id of the event |
+| `queryId` | The id of the query |
+| `commandId` | The id of the command |
+| `version` | The version of the message or `latest` to get the latest version |
+
+### Service Specifications
+
+The Service Specifications API allows you to get the specification for a specific service.
+
+```
+GET /api/schemas/services/{serviceId}/{version}/{type}
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `serviceId` | The id of the service |
+| `version` | The version of the service |
+| `type` | The type of specification, currently only `asyncapi`, `openapi` and `graphql` are supported. |

package/dist/docs/development/guides/schemas/04-schema-mcp.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog Schemas
+sidebar_label: Connect schemas to your LLMs
+title: Schema MCP
+description: Get access to your schemas for your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc)
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+<AddedIn version="2.64.0" />
+<EventCatalogPro plan="Scale" />
+
+The [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction) allows you to get access to your documentation and context in your MCP clients (e.g Cursor, Windsurf, Claude Desktop etc).
+
+Your documented schemas for your Events, Queries, Commands and Services can be accessed via the EventCatalog MCP server.
+
+This allows you to ask questions about your schemas, get schema information for your services and messages, directly in your code editor or LLM.
+
+To get started, you can follow the guide to [get started with the EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/getting-started).

package/dist/docs/development/guides/schemas/05-field-usage.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog field usage
+- field lineage
+- schema field tracking
+sidebar_label: Consumer Field Usage
+title: Consumer Field Usage
+description: Track which services depend on specific message fields.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.24.0" />
+
+Field Usage lets consumers declare which specific fields of a message they depend on. When fields are declared, EventCatalog generates a **Field Usage** page for that message showing a cross-service view of field dependencies.
+
+This gives producers visibility into downstream impact before changing or removing a field.
+
+![Field Usage](./img/field-usage.png)
+
+## Declare fields in services
+
+To declare field dependencies, add a `fields` array to any entry in your service's `receives` frontmatter.
+
+```md title="/services/ShippingService/index.mdx"
+---
+id: ShippingService
+version: 1.0.0
+receives:
+  - id: PaymentProcessed
+    version: 1.0.0
+    fields:
+      - orderId
+      - amount
+      - currency
+    from:
+      - id: payments.events
+---
+```
+
+The `fields` array is a list of field names as strings. Only include the fields your service actually reads -- you do not need to list every field in the message.
+
+## Declare fields in domains
+
+Domains support the same `fields` property on their `receives` pointers.
+
+```md title="/domains/Billing/index.mdx"
+---
+id: Billing
+version: 1.0.0
+receives:
+  - id: PaymentProcessed
+    version: 1.0.0
+    fields:
+      - orderId
+      - amount
+---
+```
+
+## View the Field Usage page
+
+When a message has a `schemaPath` set and at least one service or domain declares `fields` for that message, a **Field Usage** link appears in the message sidebar under "API & Contracts".
+
+Navigate to any message page and click **Field Usage** in the sidebar, or go directly to:
+
+```
+http://localhost:3000/docs/{type}/{id}/{version}/field-lineage
+```
+
+The page shows a table with the following columns:
+
+| Column | Description |
+|---|---|
+| Field | The field name from the schema |
+| Type | The data type (extracted from the schema) |
+| Description | The field description (extracted from the schema) |
+| Consumers | Services or domains that declared a dependency on this field |
+
+All fields from the schema are listed -- not only the ones with declared consumers. This gives you a complete picture and makes it easy to spot unused fields.
+
+Use the **Consumed only** filter button to narrow the list down to fields that have at least one consumer.
+
+## Understand the "Fields not found in schema" section
+
+If a service declares a field that does not exist in the message schema, it appears in a separate **Fields not found in schema** warning section at the bottom of the page.
+
+This section helps you catch:
+
+- Typos in field names declared by consumers
+- Fields that were removed from the schema but are still referenced by consumers
+- Outdated documentation that has drifted from the actual schema
+
+Resolving these mismatches keeps your documentation accurate and prevents consumers from unknowingly depending on fields that no longer exist.
+
+## Supported schema formats
+
+Field metadata (type and description) is automatically extracted from the message schema. The following formats are supported:
+
+- JSON Schema
+- Avro
+- Protobuf
+
+If your schema is in a different format, the Field Usage page will still list declared consumers but will not show type or description information.
+
+## Use the SDK
+
+The `fields` property is also available when using the EventCatalog SDK to programmatically add messages to services or domains.
+
+```typescript
+import { addEventToService } from '@eventcatalog/sdk';
+
+await addEventToService('ShippingService', 'receives', {
+  id: 'PaymentProcessed',
+  version: '1.0.0',
+  fields: ['orderId', 'amount', 'currency'],
+});
+```
+
+The same `fields` option is available on `addCommandToService`, `addQueryToService`, `addEventToDomain`, `addCommandToDomain`, and `addQueryToDomain`.

package/dist/docs/development/guides/schemas/06-fields-explorer.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog schema fields explorer
+- field traceability
+- field conflict detection
+- schema field search
+sidebar_label: Fields Explorer
+title: Fields Explorer
+description: Browse, search, and trace schema fields across all messages in your catalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
+
+<AddedIn version="3.26.0" />
+
+:::info SSR required
+The Fields Explorer requires EventCatalog to run in SSR (server-side rendering) mode. It is not available in static builds.
+:::
+
+<iframe width="100%" height="415" src="https://www.youtube.com/embed/PQIBATgtuKs?si=TagMKL49ZD_G_HYE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+
+The Fields Explorer gives you a catalog-wide view of every schema field across all your events, commands, and queries (supporting AVRO, JSON, and Proto). Search and filter fields by name, format, or message type, then click any field to trace exactly which services produce and consume it.
+
+
+![Field Explorer](./img/field-search.png)
+
+## Get started
+
+Fields are indexed automatically when EventCatalog starts in SSR mode. No additional configuration is required beyond adding schemas to your messages via the `schemaPath` frontmatter property.
+
+The following schema formats are supported:
+
+- JSON Schema
+- Avro
+- Protobuf
+
+Once your catalog is running, navigate to `/schemas/fields` or click **Schema Fields** in the sidebar to open the Fields Explorer.
+
+## Search and filter
+
+The left sidebar contains all filtering options.
+
+**Full-text search** -- Type in the search box to find fields by path, type, or description. The search uses prefix matching, so `ord` will match `orderId`, `orderStatus`, etc.
+
+**Schema format** -- Filter results to a single schema format (json-schema, avro, or proto). The count next to each option shows how many fields match.
+
+**Message type** -- Narrow results to fields that appear only in events, commands, or queries.
+
+**Shared fields only** -- Show only fields whose path appears in more than one message. This is useful for spotting reused data structures and understanding cross-message coupling.
+
+## Read the fields table
+
+Each row in the table represents a single field in a specific message schema.
+
+| Column | Description |
+|---|---|
+| Field Path | The dotted path to the field (e.g. `order.shipping.address`). Hover to reveal a copy button. |
+| Type | The data type declared in the schema. |
+| Message | The event, command, or query that contains this field. Click to open that message's documentation page. |
+| Format | The schema format the field was extracted from. |
+| Required | Shown when the field is marked required in the schema. |
+| Owners | Teams or users who own the message this field belongs to. |
+
+## Trace field lineage
+
+<EventCatalogPro plan="Scale" />
+
+Clicking any field row opens a full-screen **Field Traceability** panel. This panel shows a node graph with three layers:
+
+1. **Producer services** -- services that publish the message containing this field
+2. **Messages** -- the events, commands, or queries that carry the field
+3. **Consumer services** -- services that subscribe to those messages
+
+The right-hand panel lists the same information in a collapsible format and lets you click any node to focus the graph on it.
+
+![Field Explorer](./img/field-search-graph.png)
+
+_[If you want to try this feature you can get a 14 day free trail of EventCatalog Scale](https://eventcatalog.cloud)_
+
+## Detect type conflicts
+
+<EventCatalogPro plan="Scale" />
+
+When the same field path appears in multiple messages with different data types, the Fields Explorer surfaces a **type conflict**.
+
+![Field Explorer](./img/type-conflicts-row.png)
+
+In the table, a conflict is shown as an amber warning badge with the number of distinct types (for example, `2 types`). Hovering reveals a tooltip listing each type and the count of schemas that use it.
+
+![Field Explorer](./img/type-conflicts-visual.png)
+
+Inside the Field Traceability panel, a **Type Conflict** section appears in the right-hand details panel. It lists each type variant and how many schemas use it. When conflicts exist, the node graph renders a separate field node per type, making it immediately clear which messages use each variant.
+
+To see only conflicting fields across your entire catalog, enable the **Conflicting fields** filter in the sidebar.
+
+## Understand the fields index
+
+When EventCatalog starts in SSR mode it builds a SQLite index at `.eventcatalog/fields.db` inside your catalog directory. The index is rebuilt on every start, so it always reflects the latest version of each message schema.
+
+Only the **latest version** of each event, command, and query is indexed. Older versions are not included.
+
+If a message has no `schemaPath` set, it is skipped silently. If a schema file cannot be parsed (for example, due to a syntax error), the indexer emits a warning in the startup logs and continues.
+
+## Hide the Fields Explorer
+
+You can hide the Fields Explorer from the sidebar by setting its visibility to `false` in `eventcatalog.config.js`.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  sidebar: [
+    {
+      id: '/schemas/fields',
+      visible: false,
+    }
+  ]
+};
+```

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

@@ -0,0 +1,11 @@
+{
+  "label": "Schemas & Specifications",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/schemas",
+    "description": "A collection of guides to help you understand schemas and how they work with EventCatalog."
+  }
+}

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

@@ -0,0 +1,33 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog services
+- Services
+sidebar_label: What are services?
+title: Understanding services
+description: What are services? Why are they useful for event-driven architectures?
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+In EventCatalog services represent systems that produce or receive messages (e.g [commands](/docs/development/guides/messages/commands/introduction), [events](/docs/development/guides/messages/events/introduction) or [queries](/docs/development/guides/messages/queries/introduction)).
+
+Services can have one or more specifications (OpenAPI, AsyncAPI, GraphQL) attached to them.
+
+Services can be part of a domain, subdomain or independent.
+
+:::tip
+
+If your building microservices, think of a service as a microservice, or if you are building monolith applications, think of a service as that application. The term service is loosely defined by EventCatalog as flexible to what you need.
+
+:::
+
+## Internal and external services
+
+Services in EventCatalog fall into two categories:
+
+- **Internal services** — systems your team owns and operates. Your own microservices, monoliths, or applications. This is the default when you create a service.
+- **External services** — third-party systems you integrate with but do not own, such as Stripe, Twilio, or Snowflake. You opt in to this by setting `externalSystem: true` on the service.
+
+Both are just services under the hood — they share the same schema, can send and receive messages, be versioned, have owners, and carry specifications. The distinction only affects how they are grouped in the sidebar and rendered in the visualiser, so that the systems you operate are easy to tell apart from the ones you depend on.
+