@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/{services/adding-to-services/04-openapi.md → resources/schemas/03-add-specifications-to-services/01-add-openapi-specifications.md}

@@ -1,20 +1,19 @@
 ---
 keywords:
-- EventCatalog domains
-sidebar_label: OpenAPI specifications
-title: Adding OpenAPI specifications
-description: Attach an OpenAPI specification to your service and render them in your documentation
+- EventCatalog schemas
+- OpenAPI
+sidebar_position: 1
+sidebar_label: OpenAPI
+title: Add OpenAPI specifications
+description: Attach an OpenAPI specification to your service and render it in your documentation
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="2.6.0" />
+Services in EventCatalog allow you to attach one or more OpenAPI specifications to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/spec/openapi-v1)).
 
-Services in EventCatalog allow you to render OpenAPI specifications ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/spec/openapi-v1)).
-
-![Example](../../img/services/openapi-spec.png)
+![Example](../../../img/services/openapi-spec.png)
 
 You have two options for adding OpenAPI specifications to your service:
 
@@ -30,12 +29,28 @@ You have two options for adding OpenAPI specifications to your service:
 
 ## Adding OpenAPI files to EventCatalog
 
-This option is useful if you want to keep your OpenAPI files in your EventCatalog.
-
 To add an OpenAPI file to your service you will need to include the file itself inside the service directory.
 
-- `/services/{Service Name}/openapi.yml` 
-  - (example `/services/Orders/openapi.yml`)
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'openapi.yml', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
 Then you need to reference the file in the service frontmatter.
 
@@ -50,9 +65,7 @@ Then you need to reference the file in the service frontmatter.
 ---
 ```  
 
-## Reference the OpenAPI file from a remote URL
-
-<AddedIn version="2.61.2" />
+### Remote OpenAPI files
 
 This can be useful if you want to keep your OpenAPI files in a remote repository and render them in EventCatalog.
 
@@ -71,14 +84,13 @@ If your specifications changes you need to rebuild your EventCatalog as the page
 ---
 ```
 
-## Multiple OpenAPI Files
-
-<AddedIn version="2.39.1" />
+### Multiple OpenAPI Files
 
 If your service exposes multiple APIs or versions of the same API, you can assign multiple OpenAPI files to a single service.
 
 ```mdx title="example: /services/Orders/index.mdx"
 ---
+  # rest of service frontmatter...
   specifications:
     - type: openapi
       path: openapi-v1.yml
@@ -91,7 +103,4 @@ If your service exposes multiple APIs or versions of the same API, you can assig
 
 This will render a list of specification files on your service page and navigation bar.
 
-![Example](../../img/services/openapi-many.png)
-
-
-
+![Example](../../../img/services/openapi-many.png)

package/dist/docs/development/guides/{services/adding-to-services/05-asyncapi.md → resources/schemas/03-add-specifications-to-services/02-add-asyncapi-specifications.md}

@@ -1,20 +1,19 @@
 ---
 keywords:
-- EventCatalog domains
-sidebar_label: AsyncAPI specifications
-title: Adding AsyncAPI specifications
-description: Attach an AsyncAPI specification to your service and render them in your documentation
+- EventCatalog schemas
+- AsyncAPI
+sidebar_position: 2
+sidebar_label: AsyncAPI
+title: Add AsyncAPI specifications
+description: Attach an AsyncAPI specification to your service and render it in your documentation
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="2.6.0" />
+Services in EventCatalog allow you to attach one or more AsyncAPI specifications to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/asyncapi/order-service-asyncapi)).
 
-Services in EventCatalog allow you to render AsyncAPI specifications ([see demo](https://demo.eventcatalog.dev/docs/services/OrdersService/0.0.3/asyncapi/order-service-asyncapi)).
-
-![Example](../../img/services/asyncapi-spec.png)
+![Example](../../../img/services/asyncapi-spec.png)
 
 You have two options for adding AsyncAPI specifications to your service:
 
@@ -33,8 +32,26 @@ This option is useful if you want to keep your AsyncAPI files in your EventCatal
 
 To add an AsyncAPI file to your service you will need to include the file itself inside the service directory.
 
-- `/services/{Service Name}/asyncapi.yml` 
-  - (example `/services/Orders/asyncapi.yml`)
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'asyncapi.yml', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
 Then you need to reference the file in the service frontmatter.
 
@@ -42,16 +59,14 @@ Then you need to reference the file in the service frontmatter.
 ---
   specifications:
     - type: asyncapi
-      # Path to the OpenAPI file relative to the service directory
+      # Path to the AsyncAPI file relative to the service directory
       path: asyncapi.yml
       # Friendly name for the specification
       name: AsyncAPI Specification
 ---
 ```  
 
-## Reference the AsyncAPI file from a remote URL
-
-<AddedIn version="2.61.2" />
+### Remove AsyncAPI file
 
 This can be useful if you want to keep your AsyncAPI files in a remote repository and render them in EventCatalog.
 
@@ -63,16 +78,14 @@ If your specifications changes you need to rebuild your EventCatalog as the page
 ---
   specifications:
     - type: asyncapi
-      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
+      # Path to the AsyncAPI file from a remote URL (accessible by the build machine)
       path: https://raw.githubusercontent.com/event-catalog/generator-asyncapi/refs/heads/main/examples/product-api/asyncapi.yml
       # Friendly name for the specification
       name: Product API
 ---
 ```
 
-## Multiple AsyncAPI Files
-
-<AddedIn version="2.39.1" />
+### Multiple AsyncAPI Files
 
 You can also assign multiple AsyncAPI files to a single service.
 
@@ -92,6 +105,3 @@ This can be useful if your service exposes multiple APIs or versions of the same
 
 This will render a list of specification files on your service page and navigation bar.
 
-
-
-

package/dist/docs/development/guides/{services/adding-to-services/06-graphql.md → resources/schemas/03-add-specifications-to-services/03-add-graphql-schemas.md}

@@ -1,20 +1,19 @@
 ---
 keywords:
-- EventCatalog domains
-sidebar_label: GraphQL schemas
-title: Adding GraphQL schemas
-description: Add a GraphQL schema to your service and render them in your documentation
+- EventCatalog schemas
+- GraphQL
+sidebar_position: 3
+sidebar_label: GraphQL
+title: Add GraphQL schemas
+description: Add a GraphQL schema to your service and render it in your documentation
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-<AddedIn version="2.6.0" />
+Services in EventCatalog allow you to attach one or more GraphQL schemas to them and render them in the Catalog. ([see demo](https://demo.eventcatalog.dev/docs/services/BillingService/0.0.1/graphql/schema)).
 
-Services in EventCatalog allow you to render GraphQL schemas ([see demo](https://demo.eventcatalog.dev/docs/services/BillingService/0.0.1/graphql/schema)).
-
-![Example](../../img/services/graphql-spec.png)
+![Example](../../../img/services/graphql-spec.png)
 
 You have two options for adding GraphQL schemas to your service:
 
@@ -33,8 +32,26 @@ This option is useful if you want to keep your GraphQL files in your EventCatalo
 
 To add a GraphQL schema to your service you will need to include the file itself inside the service directory.
 
-- `/services/{Service Name}/graphql.schema` 
-  - (example `/services/Orders/graphql.schema`)
+<ProjectTree
+  items={[
+    {
+      name: 'services',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'Orders',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.graphql', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
 
 Then you need to reference the file in the service frontmatter.
 
@@ -42,8 +59,8 @@ Then you need to reference the file in the service frontmatter.
 ---
   specifications:
     - type: graphql
-      # Path to the OpenAPI file relative to the service directory
-      path: graphql.schema
+      # Path to the GraphQL schema relative to the service directory
+      path: schema.graphql
       # Friendly name for the specification
       name: GraphQL Specification
 ---
@@ -51,8 +68,6 @@ Then you need to reference the file in the service frontmatter.
 
 ## Reference the GraphQL file from a remote URL
 
-<AddedIn version="2.61.2" />
-
 This can be useful if you want to keep your GraphQL files in a remote repository and render them in EventCatalog.
 
 The pages will be built at build time, so the URL needs to be accessible by the build machine.
@@ -63,16 +78,14 @@ If your schemas changes you need to rebuild your EventCatalog as the pages are b
 ---
   specifications:
     - type: graphql
-      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
-      path: https://raw.githubusercontent.com/event-catalog/generator-graphql/refs/heads/main/examples/product-api/graphql.schema
+      # Path to the GraphQL schema from a remote URL (accessible by the build machine)
+      path: https://raw.githubusercontent.com/event-catalog/generator-graphql/refs/heads/main/examples/product-api/schema.graphql
       # Friendly name for the specification
       name: Product API
 ---
 ```
 
-## Multiple GraphQL Files
-
-<AddedIn version="2.39.1" />
+### Multiple GraphQL Files
 
 You can also assign multiple GraphQL files to a single service.
 
@@ -82,15 +95,12 @@ This can be useful if your service exposes multiple APIs or versions of the same
 ---
   specifications:
     - type: graphql
-      path: graphql-v1.schema
+      path: schema-v1.graphql
       name: v1
     - type: graphql
-      path: graphql-v2.schema
+      path: schema-v2.graphql
       name: v2
 ---
 ```
 
 This will render a list of schema files on your service page and navigation bar.
-
-
-

package/dist/docs/development/guides/resources/schemas/03-add-specifications-to-services/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Add specifications to services",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/schemas/add-specifications-to-services",
+    "description": "Attach OpenAPI, AsyncAPI, and GraphQL specifications to services."
+  }
+}

package/dist/docs/development/guides/{schemas/02-schema-explorer.md → resources/schemas/04-explore-schemas/01-schema-explorer.md}

@@ -9,15 +9,9 @@ description: Explore your schemas in the Schema Explorer
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
 
-<AddedIn version="2.64.0" />
+The Schema Explorer lets your teams quickly find the schema, understand who owns it, and who is producing or consuming it (see [demo](https://demo.eventcatalog.dev/schemas)).
 
-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)
+![Example](../img/schema-explorer.png)
 
 Using the Schema Explorer, you can:
 
@@ -39,9 +33,7 @@ You need to set the `schemaPath` in your schema frontmatter to the path to your
 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)
+![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.
@@ -57,18 +49,3 @@ For EventCatalog Scale users, you can get API (GET) access to your schemas for m
 ##### 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/06-fields-explorer.md → resources/schemas/04-explore-schemas/02-fields-explorer.md}

@@ -11,9 +11,7 @@ description: Browse, search, and trace schema fields across all messages in your
 ---
 
 import AddedIn from '@site/src/components/MDX/AddedIn';
-import EventCatalogPro from '@site/src/components/MDX/EventCatalogPro';
-
-<AddedIn version="3.26.0" />
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
 :::info SSR required
 The Fields Explorer requires EventCatalog to run in SSR (server-side rendering) mode. It is not available in static builds.
@@ -25,7 +23,7 @@ The Fields Explorer requires EventCatalog to run in SSR (server-side rendering)
 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)
+![Field Explorer](../img/field-search.png)
 
 ## Get started
 
@@ -66,7 +64,7 @@ Each row in the table represents a single field in a specific message schema.
 
 ## Trace field lineage
 
-<EventCatalogPro plan="Scale" />
+<PlanBanner plan="Scale" />
 
 Clicking any field row opens a full-screen **Field Traceability** panel. This panel shows a node graph with three layers:
 
@@ -76,21 +74,21 @@ Clicking any field row opens a full-screen **Field Traceability** panel. This pa
 
 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)
+![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)_
+_[If you want to try this feature you can get a 30-day free trial of EventCatalog Scale](https://eventcatalog.cloud)_
 
 ## Detect type conflicts
 
-<EventCatalogPro plan="Scale" />
+<PlanBanner 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)
+![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)
+![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.
 

package/dist/docs/development/guides/{schemas/05-field-usage.md → resources/schemas/04-explore-schemas/03-consumer-field-usage.md}

@@ -11,13 +11,11 @@ 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)
+![Field Usage](../img/field-usage.png)
 
 ## Declare fields in services
 

package/dist/docs/development/guides/resources/schemas/04-explore-schemas/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Explore schemas",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/schemas/explore-schemas",
+    "description": "Find, inspect, and understand schemas across your catalog."
+  }
+}

package/dist/docs/development/guides/{schemas/03-schema-api.md → resources/schemas/05-schema-api.md}

@@ -1,23 +1,18 @@
 ---
-sidebar_position: 3
+sidebar_position: 6
 keywords:
 - EventCatalog Schemas
-sidebar_label: Get access to your schemas via API
+sidebar_label: Schema 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';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-<AddedIn version="2.64.0" />
-<EventCatalogPro plan="Scale" />
+<PlanBanner 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).
-:::
+EventCatalog provides an API to get access to your schemas and specifications.
 
 ### Message Schemas
 
@@ -56,4 +51,4 @@ GET /api/schemas/services/{serviceId}/{version}/{type}
 | --------- | ----------- |
 | `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. |
+| `type` | The type of specification, currently only `asyncapi`, `openapi` and `graphql` are supported. |

package/dist/docs/development/guides/{schemas/04-schema-mcp.md → resources/schemas/06-schema-mcp.md}

@@ -1,17 +1,16 @@
 ---
-sidebar_position: 3
+sidebar_position: 7
 keywords:
 - EventCatalog Schemas
-sidebar_label: Connect schemas to your LLMs
+sidebar_label: Schema MCP
 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';
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
 
-<AddedIn version="2.64.0" />
-<EventCatalogPro plan="Scale" />
+<PlanBanner 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).
 
@@ -19,4 +18,4 @@ Your documented schemas for your Events, Queries, Commands and Services can be a
 
 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).
+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/resources/schemas/07-reference.md

@@ -0,0 +1,23 @@
+---
+keywords:
+- EventCatalog schemas
+- Schema reference
+sidebar_label: Reference
+sidebar_position: 8
+title: Schemas reference
+description: Fields, sources, and routes for schemas in EventCatalog.
+---
+
+This page lists how schemas are discovered and represented in EventCatalog.
+
+Schemas are generated from:
+
+- Message schema files referenced by events, commands, and queries.
+- Schema sources configured in `eventcatalog.config.js`.
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/schemas/explorer` | Schema Explorer. |
+| `/schemas/fields` | Fields Explorer. |

package/dist/docs/development/guides/{schemas → resources/schemas}/_category_.json

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

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

@@ -0,0 +1,27 @@
+---
+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';
+
+A service is an implementation resource. It might be an API, worker, backend service, frontend application, or other deployable component.
+
+Services can produce or receive messages (e.g [commands](/docs/development/guides/resources/messages/message-types/commands), [events](/docs/development/guides/resources/messages/message-types/events) or [queries](/docs/development/guides/resources/messages/message-types/queries)) and also be implementations of one or more specifications (OpenAPI, AsyncAPI, GraphQL).
+
+Services can be part of a domain, system or independent.
+
+### Internal and external services
+
+Services in EventCatalog fall into two categories:
+
+- **Internal services** — a resource your company owns and operates.
+- **External services** — a third-party resource you integrate with but do not own (e.g Stripe, Twilio, or Snowflake). 
+
+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.
+