@eventcatalog/core 4.1.3 → 4.1.5

package/dist/docs/development/guides/resources/messages/10-reference.md

@@ -0,0 +1,439 @@
+---
+keywords:
+- EventCatalog messages
+- Message frontmatter
+sidebar_label: Reference
+sidebar_position: 8
+title: Messages reference
+description: Frontmatter fields, paths, and routes for events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+This page lists the fields, paths, and routes supported by messages.
+
+Messages are modeled as three collections:
+
+- `events`
+- `commands`
+- `queries`
+
+## Paths
+
+Messages can be created at the root of their collection:
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Event Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'commands',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Command Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+    {
+      name: 'queries',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Query Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Messages can also be created inside domains, systems, and services:
+
+<ProjectTree
+  items={[
+    {
+      name: 'domains',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Domain Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'events',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{Event Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+            {
+              name: 'systems',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{System Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'services',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: '{Service Name}',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [
+                            {
+                              name: 'commands',
+                              type: 'folder',
+                              defaultOpen: true,
+                              children: [
+                                {
+                                  name: '{Command Name}',
+                                  type: 'folder',
+                                  defaultOpen: true,
+                                  children: [{ name: 'index.mdx', highlight: true }],
+                                },
+                              ],
+                            },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'systems',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{System Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'services',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{Service Name}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [
+                    {
+                      name: 'events',
+                      type: 'folder',
+                      defaultOpen: true,
+                      children: [
+                        {
+                          name: '{Event Name}',
+                          type: 'folder',
+                          defaultOpen: true,
+                          children: [{ name: 'index.mdx', highlight: true }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+Versioned messages use:
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: '{Message Name}',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            {
+              name: 'versioned',
+              type: 'folder',
+              defaultOpen: true,
+              children: [
+                {
+                  name: '{version}',
+                  type: 'folder',
+                  defaultOpen: true,
+                  children: [{ name: 'index.mdx', highlight: true }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Routes
+
+| Route | Description |
+|-------|-------------|
+| `/docs/events/{event-id}/{version}` | Event documentation page. |
+| `/docs/commands/{command-id}/{version}` | Command documentation page. |
+| `/docs/queries/{query-id}/{version}` | Query documentation page. |
+| `/visualiser/events/{event-id}/{version}` | Event resource diagram. |
+| `/visualiser/commands/{command-id}/{version}` | Command resource diagram. |
+| `/visualiser/queries/{query-id}/{version}` | Query resource diagram. |
+
+## Required fields
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the message. EventCatalog uses this for URLs and resource references.
+
+```md title="Example"
+---
+id: OrderCreated
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Display name of the message.
+
+```md title="Example"
+---
+name: Order Created
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the message documentation.
+
+```md title="Example"
+---
+version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary` {#summary}
+
+- Type: `string`
+
+Short summary of what the message represents.
+
+```md title="Example"
+---
+summary: Published when an order has been accepted.
+---
+```
+
+### `owners` {#owners}
+
+- Type: `array`
+
+An array of team or user ids that own the message.
+
+```md title="Example"
+---
+owners:
+  - ordering-platform
+---
+```
+
+### `schemaPath` {#schemaPath}
+
+- Type: `string`
+
+Path to the message schema.
+
+```md title="Example"
+---
+schemaPath: schema.json
+---
+```
+
+### `schemas` {#schemas}
+
+- Type: `array`
+
+Schema references associated with the message.
+
+```md title="Example"
+---
+schemas:
+  - path: schema.json
+    name: JSON schema
+    format: jsonschema
+---
+```
+
+### `channels` {#channels}
+
+- Type: `array`
+
+Inline channel references for the message.
+
+```md title="Example"
+---
+channels:
+  - id: orders-topic
+    address: orders.events
+    protocol: kafka
+---
+```
+
+### `operation` {#operation}
+
+- Type: `object`
+
+HTTP operation metadata shown on the visualizer node.
+
+```md title="Example"
+---
+operation:
+  method: POST
+  path: /orders
+  statusCodes:
+    - "201"
+    - "400"
+---
+```
+
+
+### `badges` {#badges}
+
+- Type: `array`
+
+Badges rendered on the message page.
+
+```md title="Example"
+---
+badges:
+  - content: Public event
+    backgroundColor: green
+    textColor: green
+---
+```
+
+### `repository` {#repository}
+
+- Type: `object`
+
+Repository metadata for the message.
+
+```md title="Example"
+---
+repository:
+  language: TypeScript
+  url: https://github.com/acme/orders
+---
+```
+
+### `attachments` {#attachments}
+
+- Type: `array`
+
+External links or supporting documents attached to the message.
+
+```md title="Example"
+---
+attachments:
+  - title: Event contract review
+    url: https://docs.example.com/order-created-review
+    type: document
+---
+```
+
+## Operation fields
+
+Use `operation` to document HTTP metadata for an event, command, or query.
+
+```md
+---
+operation:
+  method: POST
+  path: /orders
+  statusCodes:
+    - "201"
+    - "400"
+---
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `method` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` | HTTP method for the operation. |
+| `path` | `string` | API path for the operation. |
+| `statusCodes` | `array` | HTTP status codes the operation may return. |
+
+## Schema examples
+
+Use `schemaPath` to attach a schema to the message.
+
+```md
+---
+schemaPath: schema.json
+---
+```
+
+You can also use schema references when a message has multiple schemas or named schemas.
+
+```md
+---
+schemas:
+  - path: schema.json
+    name: JSON schema
+    format: jsonschema
+---
+```

package/dist/docs/development/guides/resources/messages/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Messages",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/resources/messages",
+    "description": "Understand, create, connect, and manage events, commands, and queries in EventCatalog."
+  }
+}

package/dist/docs/development/guides/resources/schemas/01-what-are-schemas-and-specifications.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+keywords:
+- EventCatalog Schemas
+sidebar_label: What are schemas and specifications?
+title: What are schemas and specifications?
+description: Understand how schemas and specifications fit into EventCatalog.
+---
+
+EventCatalog supports **any schema or specification format**, including (but not limited to) JSON / YAML, Avro, Protobuf, GraphQL, OpenAPI, AsyncAPI.
+
+Schemas can be stored in EventCatalog or synced from remote registries/locations.
+
+Schemas are **optional**, but they add valuable context to your resources (e.g messages, services and domains).
+
+### Why add schemas?
+
+By adding schemas to your catalog you unlock several benefits:
+
+- **Schema Explorer** – Your teams can quickly find and browse schemas across your architecture [(see demo)](https://demo.eventcatalog.dev/schemas/explorer)
+- **Fields Explorer** – Drill down into properties of every schema, find duplications and mismatches [(see guide)](/docs/development/guides/resources/schemas/explore-schemas/fields-explorer)
+- **API access** – Programatic access to your schemas through your Catalog API. [(see guide)](/docs/development/guides/resources/schemas/schema-api)
+- **AI Context** – Give LLMs context of your schemas with 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)
+

package/dist/docs/development/guides/resources/schemas/02-add-schemas-to-messages.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog Schemas
+sidebar_label: Add schemas to messages
+title: Add schemas to messages
+description: Attach schemas to events, commands, and queries in EventCatalog.
+---
+
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+Schemas can be added to any message type (Event, Command or Query).
+
+## Adding a schema to a message
+
+Add the schema file next to the message and reference it with `schemaPath` in the message frontmatter.
+
+```md title="/events/InventoryAdjusted/index.mdx"
+---
+id: InventoryAdjusted
+version: 0.0.4
+schemaPath: schema.avro
+---
+```
+
+<ProjectTree
+  items={[
+    {
+      name: 'events',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'InventoryAdjusted',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.avro', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Rendering schemas
+
+You can render schema files inside the message page with the [schema components](/docs/development/components/components/schema-viewer).
+
+```md title="/events/InventoryAdjusted/index.mdx"
+<!-- Raw codeblock for your schema -->
+<Schema file="schema.avro" />
+
+<!-- Richer UI experinece for your schemas -->
+<SchemaViewer file="schema.avro" />
+```
+
+Use `<Schema />` when you want to render the raw schema as a code block. Use `<SchemaViewer />` when you want a richer schema viewer for supported formats.
+
+## Next steps
+
+Once schemas are attached to your messages, you can use the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer), [Fields Explorer](/docs/development/guides/resources/schemas/explore-schemas/fields-explorer), and [Schema API](/docs/development/guides/resources/schemas/schema-api) to make them easier to find and use.

package/dist/docs/development/guides/resources/schemas/03-add-schemas-to-data-stores.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog schemas
+- EventCatalog data stores
+sidebar_label: Add schemas to data stores
+title: Add schemas to data stores
+description: Attach schemas, queries, and data files to data stores in EventCatalog.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+import ProjectTree from '@site/src/components/MDX/ProjectTree';
+
+<AddedIn version="2.59.0" />
+
+EventCatalog supports any schema format.
+
+When you document your [data stores](/docs/development/guides/resources/data/introduction), you may want to include schemas, queries, or other files that explain the data store.
+
+You can attach this information in two ways:
+
+- [Use codeblocks to render your schema](#using-codeblocks-to-render-your-schema)
+- [Use the `<Schema/>` component to render your schema from a file](#using-the-schema-component-to-render-your-schema-from-a-file)
+
+## Using codeblocks to render your schema
+
+You can use codeblocks to render your schema directly in your Markdown files.
+
+Here is an example of a SQL codeblock:
+
+````md
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY,
+  name VARCHAR(255),
+  email VARCHAR(255)
+);
+```
+````
+
+You can learn more about codeblocks and configuring them in the [codeblocks documentation](/docs/api/code-blocks).
+
+## Using the `<Schema/>` component to render your schema from a file
+
+If you prefer to keep your schemas or queries in separate files, add them to the data store folder and render them with the `<Schema/>` component.
+
+<ProjectTree
+  items={[
+    {
+      name: 'containers',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        {
+          name: 'OrdersDatabase',
+          type: 'folder',
+          defaultOpen: true,
+          children: [
+            { name: 'index.mdx' },
+            { name: 'schema.sql', highlight: true },
+            { name: 'queries.sql', highlight: true },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+```md title="/containers/OrdersDatabase/index.mdx"
+<!-- Render the file into your page -->
+<Schema file="schema.sql" lang="sql" title="Users Table" />
+
+<!-- Render the schemas separately in an AccordionGroup -->
+<AccordionGroup>
+  <Accordion title="Users Table">
+    <!-- Load the schema from the file -->
+    <Schema file="schema.sql" lang="sql" title="Users Table" />
+  </Accordion>
+  <Accordion title="Common Queries">
+    <!-- Load the queries from the file -->
+    <Schema file="queries.sql" lang="sql" title="Common Queries" />
+  </Accordion>
+</AccordionGroup>
+```
+
+You can see an example of this in the [EventCatalog Demo](https://demo.eventcatalog.dev/docs/containers/orders-db/0.0.1).
+
+:::tip Versioning information
+Everything in EventCatalog can be versioned. When your data store changes, keep older documentation in a `versioned` folder and add a `changelog.mdx` file to explain what changed.
+:::