@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/api/11-data-api.md

@@ -0,0 +1,268 @@
+---
+sidebar_position: 5
+sidebar_label: Data API
+title: Data frontmatter API
+description: Understanding the API for data.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.59.0" />
+
+## Overview {#overview}
+
+[Data stores](/docs/development/guides/data/introduction) are just markdown files, with this comes the use of Content, MDX components and also [front-matter](https://jekyllrb.com/docs/front-matter/).
+
+Here is an example of of a basic data store.
+
+```md title="/services/OrdersService/containers/OrdersDatabase/index.mdx (example)"
+---
+# id of your data store, used for slugs and references in EventCatalog.
+id: orders-db
+# Display name of the data store, rendered in EventCatalog.
+name: Orders DB
+# Version of the data store
+version: 1.0.0
+# Type of the data store (e.g. database, cache, objectStore, searchIndex)
+container_type: database
+# Technology of the data store (e.g. postgres@14, redis@7, etc)
+technology: postgres@14
+# Classification of the data store (e.g. internal, external, etc)
+classification: internal
+# Retention of the data store (e.g. 7y, 10y, etc)
+retention: 7y
+# Residency of the data store (e.g. eu-west-1, us-east-1, etc)
+residency: eu-west-1
+# Badges to display
+badges:
+  - content: "Core Data Store"
+    backgroundColor: "blue"
+    textColor: "white"
+---
+
+The orders database is a core data store for the orders domain.
+
+<!-- Add any markdown you want, the data store will render in its own page /docs/containers/{Data Store}/{version} -->
+```
+
+## Required fields {#required-fields}
+
+### `id` {#id}
+
+- Type: `string`
+
+Unique id of the data store. EventCatalog uses this for references and slugs.
+
+```mdx title="Example"
+---
+  id: orders-db
+---
+```
+
+### `name` {#name}
+
+- Type: `string`
+
+Name of the data store this is used to display the name on the UI.
+
+```mdx title="Example"
+---
+  name: Orders DB
+---
+```
+
+### `version` {#version}
+
+- Type: `string`
+
+Version of the data store. 
+
+```mdx title="Example"
+---
+  version: 0.0.1
+---
+```
+
+<!-- // 1) Put this near your other enums/utilities
+const containerTypeEnum = z.enum([
+  // Core
+  'database',
+  'cache',
+  'objectStore',
+  'searchIndex',
+  'dataWarehouse',
+  'dataLake',
+  'externalSaaS',
+  // Fallback
+  'other',
+]); -->
+
+<!-- const accessModeEnum = z.enum(['read', 'write', 'readWrite', 'appendOnly']);
+const dataClassificationEnum = z.enum(['public', 'internal', 'confidential', 'regulated']);
+
+const containers = defineCollection({
+  loader: glob({
+    pattern: ['**/containers/*/index.(md|mdx)', '**/containers/*/versioned/*/index.(md|mdx)'],
+    base: projectDirBase,
+    generateId: ({ data }) => {
+      return `${data.id}-${data.version}`;
+    },
+  }),
+  schema: z
+    .object({
+      container_type: containerTypeEnum, // <— the important discriminator inside DataContainer
+      technology: z.string().optional(), // e.g. "postgres@14", "kafka", "s3"
+      authoritative: z.boolean().optional().default(false),
+      access_mode: accessModeEnum.optional(), // read/write/readWrite/appendOnly
+      classification: dataClassificationEnum.optional(),
+      residency: z.string().optional(),
+      retention: z.string().optional(),
+      // details panel toggles (aligns with your pattern)
+      detailsPanel: z
+        .object({
+          versions: detailPanelPropertySchema.optional(),
+          repository: detailPanelPropertySchema.optional(),
+          owners: detailPanelPropertySchema.optional(),
+          changelog: detailPanelPropertySchema.optional(),
+          attachments: detailPanelPropertySchema.optional(),
+        })
+        .optional(),
+      services: z.array(reference('services')).optional(),
+
+      servicesThatWriteToContainer: z.array(reference('services')).optional(),
+      servicesThatReadFromContainer: z.array(reference('services')).optional(),
+    })
+    .merge(baseSchema),
+}); -->
+
+
+### `container_type` {#container_type}
+
+- Type: `string`
+
+Type of the data store.
+
+```mdx title="Example"
+---
+  container_type: database
+---
+```
+
+Options: `database`, `cache`, `objectStore`, `searchIndex`, `dataWarehouse`, `dataLake`, `other`
+
+## Optional fields {#optional-fields}
+
+### `summary` {#summary}
+
+Short summary of your data store, shown on data store summary pages.
+
+```mdx title="Example"
+---
+  summary: |
+    Orders database is a core data store for the orders domain.
+---
+```
+
+### `technology` {#technology}
+
+- Type: `string`
+
+Technology of the data store.
+```mdx title="Example"
+---
+  technology: postgres@14
+---
+```
+
+### `classification` {#classification}
+
+- Type: `string`
+
+Classification of the data store.
+```mdx title="Example"
+---
+  classification: internal
+---
+```
+
+Options: `internal`, `external`, `confidential`, `regulated`
+
+### `retention` {#retention}
+
+- Type: `string`
+
+Retention of the data store.
+```mdx title="Example"
+---
+  retention: 7y
+---
+```
+
+### `residency` {#residency}
+
+- Type: `string`
+
+Residency of the data store.
+```mdx title="Example"
+---
+  residency: eu-west-1
+---
+```
+
+### `detailsPanel` {#detailsPanel}
+
+<AddedIn version="2.53.0" />
+
+Override the default details panel for the page. You can use this show/hide areas of the details panel.
+
+![Details panel](./img/domain-details-panel.png)
+
+```mdx title="Example"
+---
+  detailsPanel:
+    versions:
+      visible: false
+    owners:
+      visible: false
+---
+```
+
+Options:
+
+| Property | Type | Required | Description |
+| -------- | -------- | -------- | -------- |
+| `versions` | `object` | No | An object with a `visible` property to show/hide the versions section |  
+| `changelog` | `object` | No | An object with a `visible` property to show/hide the changelog button |  
+| `owners` | `object` | No | An object with a `visible` property to show/hide the owners section |  
+| `attachments` | `object` | No | An object with a `visible` property to show/hide the attachments section |  
+| `repository` | `object` | No | An object with a `visible` property to show/hide the repository section |  
+
+### `attachments` {#attachments}
+
+An array of attachments for this resource type.
+
+```mdx title="Example"
+---
+  attachments:
+    - url: https://example.com/erd/orders-database.png
+      title: ERD for Orders Database
+      description: Learn more about the ERD for the Orders Database.
+      type: 'architecture-decisions'
+      icon: FileTextIcon
+---
+
+```
+
+Options:
+
+The attachments can be a url (string) or an object with additional properties.
+
+Object properties:
+
+| Property | Type | Required | Description |
+| -------- | -------- | -------- | -------- |
+| `url` | `string` | Yes | The url of the attachment |
+| `title` | `string` | optional | The title of the attachment |
+| `description` | `string` | optional | The description of the attachment |
+| `type` | `string` | optional | The type of the attachment, this will be used to group attachments together in the UI |
+| `icon` | `string` | optional | The icon of the attachment, you can pick from the [lucide icons](https://lucide.dev/icons/) library. |

package/dist/docs/api/12-data-product-api.md

@@ -0,0 +1,416 @@
+---
+sidebar_position: 12
+sidebar_label: Data Product API
+title: Data Product frontmatter API
+description: Understanding the API for data products
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+:::warning Beta Feature
+
+Data Products are currently in **beta** and accepting feedback. The frontmatter API and supported fields may change based on community input.
+
+:::
+
+## Overview
+
+[Data products](/docs/development/guides/data-products/introduction) are markdown files with Content, MDX components and [front-matter](https://jekyllrb.com/docs/front-matter/).
+
+Here is an example of a basic data product.
+
+```md title="/data-products/PaymentAnalytics/index.mdx (example)"
+---
+# Unique identifier for your data product
+id: payment-analytics
+
+# Display name rendered in EventCatalog
+name: Payment Analytics
+
+# Version of the data product
+version: 1.0.0
+
+# Brief summary of what this data product provides
+summary: Payment performance metrics and fraud detection insights
+
+# Optional owners (references teams or users)
+owners:
+  - analytics-team
+
+# Optional badges for categorization
+badges:
+  - content: Analytics
+    backgroundColor: purple
+    textColor: purple
+
+# Input dependencies (events, services, data stores)
+inputs:
+  - id: PaymentProcessed
+  - id: FraudCheckCompleted
+  - id: PaymentService
+
+# Output data products (events, services, data stores with optional contracts)
+outputs:
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+---
+
+## Overview
+
+The Payment Analytics data product transforms payment events into actionable insights.
+
+<NodeGraph />
+```
+
+## Required fields
+
+### `id`
+
+- Type: `string`
+
+Unique id of the data product. EventCatalog uses this for references and slugs.
+
+```mdx title="Example"
+---
+  id: payment-analytics
+---
+```
+
+### `name`
+
+- Type: `string`
+
+Name of the data product used to display on the UI.
+
+```mdx title="Example"
+---
+  name: Payment Analytics
+---
+```
+
+### `version`
+
+- Type: `string`
+
+Version of the data product.
+
+```mdx title="Example"
+---
+  version: 1.0.0
+---
+```
+
+## Optional fields
+
+### `summary`
+
+Short summary of your data product, shown on summary pages.
+
+```mdx title="Example"
+---
+  summary: |
+    Comprehensive payment performance metrics including success rates,
+    failure analysis, and fraud detection insights.
+---
+```
+
+### `inputs`
+
+- Type: `array`
+
+Array of input dependencies that feed the data product. Inputs can be events, commands, queries, services, data stores, or channels.
+
+```mdx title="Example"
+---
+inputs:
+  - id: PaymentProcessed
+  - id: OrderConfirmed
+  - id: PaymentService
+  - id: payments-db
+---
+```
+
+Each input can optionally specify a version:
+
+```mdx title="Example with versions"
+---
+inputs:
+  - id: PaymentProcessed
+    version: 2.1.0
+  - id: OrderConfirmed
+    version: latest  # Default if not specified
+---
+```
+
+### `outputs`
+
+- Type: `array`
+
+Array of outputs produced by the data product. Outputs can be events, commands, queries, services, or data stores.
+
+```mdx title="Example"
+---
+outputs:
+  - id: OrderMetricsCalculated
+  - id: NotificationService
+  - id: orders-analytics-db
+---
+```
+
+Outputs can include contracts to define schema specifications:
+
+```mdx title="Example with contracts"
+---
+outputs:
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+  - id: daily-sales-db
+    contract:
+      path: daily-sales-odcs.yaml
+      name: Daily Sales ODCS
+      type: odcs
+---
+```
+
+Contract properties:
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `path` | `string` | Yes | File path relative to data product directory |
+| `name` | `string` | Yes | Display name for the contract |
+| `type` | `string` | Yes | Contract format: `json-schema` or `odcs` |
+
+### `owners`
+
+- Type: `array`
+
+Array of owners for the data product. Owners reference teams or users defined in your catalog.
+
+```mdx title="Example"
+---
+owners:
+  - analytics-team
+  - dboyne
+---
+```
+
+### `badges`
+
+- Type: `array`
+
+Array of badges to display on the data product page.
+
+```mdx title="Example"
+---
+badges:
+  - content: Analytics
+    backgroundColor: purple
+    textColor: purple
+  - content: dbt
+    backgroundColor: orange
+    textColor: orange
+---
+```
+
+Badge properties:
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `content` | `string` | Yes | Text content of the badge |
+| `backgroundColor` | `string` | Yes | Background color |
+| `textColor` | `string` | Yes | Text color |
+
+### `repository`
+
+- Type: `object`
+
+Repository information for the data product.
+
+```mdx title="Example"
+---
+repository:
+  language: Python
+  url: https://github.com/example/payment-analytics
+---
+```
+
+Properties:
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `language` | `string` | No | Programming language |
+| `url` | `string` | No | Repository URL |
+
+### `schemaPath`
+
+- Type: `string`
+
+Path to the main schema file for the data product.
+
+```mdx title="Example"
+---
+schemaPath: ./payment-schema.json
+---
+```
+
+### `sidebar`
+
+- Type: `object`
+
+Customize sidebar appearance for the data product.
+
+```mdx title="Example"
+---
+sidebar:
+  label: Payment Analytics
+  badge: New
+  color: "#4F46E5"
+  backgroundColor: "#EEF2FF"
+---
+```
+
+### `specifications`
+
+- Type: `array`
+
+Array of specification files for the data product (OpenAPI, AsyncAPI, GraphQL).
+
+```mdx title="Example"
+---
+specifications:
+  - type: openapi
+    path: ./api-spec.yaml
+    name: Payment Analytics API
+---
+```
+
+### `hidden`
+
+- Type: `boolean`
+
+Hide the data product from the catalog UI.
+
+```mdx title="Example"
+---
+hidden: true
+---
+```
+
+### `editUrl`
+
+- Type: `string`
+
+Custom edit URL for the data product documentation.
+
+```mdx title="Example"
+---
+editUrl: https://github.com/example/docs/edit/main/data-products/PaymentAnalytics/index.mdx
+---
+```
+
+### `resourceGroups`
+
+- Type: `array`
+
+Define groups of related resources to display on the data product page.
+
+```mdx title="Example"
+---
+resourceGroups:
+  - id: input-events
+    title: Input Events
+    items:
+      - id: PaymentProcessed
+        type: event
+      - id: FraudCheckCompleted
+        type: event
+    limit: 10
+    sidebar: true
+---
+```
+
+### `styles`
+
+- Type: `object`
+
+Custom styling for the data product.
+
+```mdx title="Example"
+---
+styles:
+  icon: DatabaseIcon
+  node:
+    color: "#4F46E5"
+    label: Payment Analytics
+---
+```
+
+### `deprecated`
+
+- Type: `boolean | object`
+
+Mark the data product as deprecated.
+
+```mdx title="Example (boolean)"
+---
+deprecated: true
+---
+```
+
+```mdx title="Example (object)"
+---
+deprecated:
+  message: Migrate to PaymentAnalyticsV2
+  date: 2026-06-01
+---
+```
+
+### `visualiser`
+
+- Type: `boolean`
+
+Enable or disable the visualizer for the data product. Defaults to `true`.
+
+```mdx title="Example"
+---
+visualiser: false
+---
+```
+
+### `attachments`
+
+- Type: `array`
+
+Array of attachments for the data product.
+
+```mdx title="Example"
+---
+attachments:
+  - url: https://example.com/pipeline-diagram.png
+    title: Pipeline Architecture
+    description: Data flow diagram for Payment Analytics
+    type: architecture-diagram
+    icon: FileTextIcon
+---
+```
+
+Attachments can be URLs (strings) or objects with additional properties.
+
+Object properties:
+
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `url` | `string` | Yes | URL of the attachment |
+| `title` | `string` | No | Title of the attachment |
+| `description` | `string` | No | Description |
+| `type` | `string` | No | Type for grouping attachments |
+| `icon` | `string` | No | Icon from [lucide icons](https://lucide.dev/icons/) |
+

package/dist/docs/api/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Development",
+  "position": 2,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "api",
+    "title": "EventCatalog API Documentation",
+    "description": "EventCatalog API Documentation"
+  }
+}