@eventcatalog/core 3.35.0 → 3.35.1

package/dist/docs/development/guides/data-products/02-adding-data-products.md

@@ -0,0 +1,157 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog data products
+sidebar_label: Creating a data product
+title: Creating data products
+description: Creating and managing data products
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Data products document analytical datasets that transform operational (e.g databases, messages, channels) data into insights. Adding a data product helps teams understand data lineage, contracts, and consumption patterns.
+
+### What do data products look like?
+
+![Example](./img/data-product.png)
+
+## Creating a data product
+
+Create a new folder called `data-products` and add your data product files to it.
+
+- `**/data-products/{DataProduct Name}/index.mdx`
+  - (example `**/data-products/OrderAnalytics/index.mdx`)
+  - (example `**/data-products/PaymentMetrics/index.mdx`)
+
+Data products can be defined in any folder. This lets you group data products by domains, teams, or business areas.
+
+### Creating the data product file
+
+Within your data product folder create an `index.mdx` file.
+
+The `index.mdx` contents split into two sections: **frontmatter** and **markdown content**.
+
+Here is an example data product markdown file. [You can read the API docs for the data product frontmatter API](/docs/api/data-product-api).
+
+```md title="/data-products/OrderAnalytics/index.mdx (example)"
+---
+# Unique identifier for your data product
+id: order-analytics
+
+# Display name rendered in EventCatalog
+name: Order Analytics
+
+# Version of the data product
+version: 1.0.0
+
+# Brief summary of what this data product provides
+summary: Aggregated order metrics and KPIs for business intelligence
+
+# Optional owners (references teams or users)
+owners:
+  - dboyne
+
+# Optional badges for categorization
+badges:
+  - content: Analytics
+    backgroundColor: purple
+    textColor: purple
+  - content: dbt
+    backgroundColor: orange
+    textColor: orange
+
+# Input dependencies (events, services, data stores)
+inputs:
+  - id: OrderConfirmed
+    # version is optional for all inputs
+    version: 1.0.0
+  - id: PaymentProcessed
+  - id: payment-cache
+
+# Output data products (events, services, data stores)
+outputs:
+  - id: OrderMetricsCalculated
+    # version is optional for all outputs
+    version: 1.0.0
+  - id: NotificationService
+  - id: orders-db
+    contract:
+      path: fact-orders-contract.json
+      name: Fact Orders Contract
+      type: json-schema
+---
+
+## Overview
+
+The Order Analytics data product transforms raw order and payment events into aggregated metrics optimized for reporting and business intelligence.
+
+<NodeGraph />
+
+Rest of your markdown....
+```
+
+**That's it!**
+
+Once you add your data product to EventCatalog, it will appear in the catalog.
+
+With **data products** you can write any Markdown and it will render on your page. Every data product gets its own page.
+
+Within your markdown content you can use [components](/docs/development/components/using-components) to add interactive elements.
+
+You can [see examples on GitHub](https://github.com/event-catalog/eventcatalog/tree/main/examples/default).
+
+## Directory structure
+
+Data products can be placed anywhere in your catalog:
+
+```
+/data-products
+  /OrderAnalytics
+    index.mdx
+    fact-orders-contract.json
+  /PaymentMetrics
+    index.mdx
+    payment-contract.json
+
+/domains
+  /E-Commerce
+    /data-products
+      /CustomerSegmentation
+        index.mdx
+```
+
+## Using the NodeGraph component
+
+The `<NodeGraph />` component visualizes relationships between your data product and its inputs/outputs.
+
+```md
+<NodeGraph />
+```
+
+This component automatically renders based on the `inputs` and `outputs` defined in your frontmatter.
+
+## Custom icon
+
+<AddedIn version="3.28.1" />
+
+Set `styles.icon` in your frontmatter to display a custom icon on the data product. The icon appears in the visualiser node, sidebar navigation, page header, and search results.
+
+```md title="/data-products/OrderAnalytics/index.mdx (example)"
+---
+id: order-analytics
+name: Order Analytics
+version: 1.0.0
+styles:
+  icon: /icons/analytics/clickhouse.svg
+---
+```
+
+The value can be a path to a file in your catalog's `public/` folder (e.g. `/icons/analytics/clickhouse.svg`) or an absolute URL (e.g. `https://cdn.simpleicons.org/snowflake`).
+
+## Next steps
+
+- [Define inputs and outputs](/docs/development/guides/data-products/inputs-and-outputs)
+- [Add schema contracts](/docs/development/guides/data-products/contracts)
+- [Add data products to domains](/docs/development/guides/data-products/adding-to-domains)

package/dist/docs/development/guides/data-products/03-inputs-and-outputs.md

@@ -0,0 +1,128 @@
+---
+sidebar_position: 3
+keywords:
+- EventCatalog data products
+sidebar_label: Inputs and outputs
+title: Inputs and outputs
+description: Define dependencies and consumers
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Data products consume inputs (e.g events, services, data stores, channels) and produce outputs (e.g events, services, data stores, channels). Defining these relationships helps teams understand data lineage and dependencies.
+
+## Defining inputs (input ports)
+
+Inputs represent the source dependencies your data product consumes. In EventCatalog these can be [events](/docs/development/guides/messages/events/introduction), commands, queries, [services](/docs/development/guides/services/introduction), [data stores](/docs/development/guides/data/introduction), or [channels](/docs/development/guides/channels/introduction).
+
+You need to specify the `id` of the input and optionally the `version` of the input. If no version is provided the latest version will be used.
+
+```md
+---
+id: order-analytics
+name: Order Analytics
+version: 1.0.0
+
+# Define input dependencies
+inputs:
+  - id: OrderConfirmed
+  - id: PaymentProcessed
+  - id: FraudDetectionService
+  - id: payment-cache
+  - id: payment-domain-eventbus
+---
+```
+
+## Defining outputs
+
+Outputs represent what your data product produces. These can be events, commands, queries, services, data stores, or channels.
+
+You need to specify the `id` of the output and optionally the `version` of the output. If no version is provided the latest version will be used.
+
+```md
+---
+id: order-analytics
+name: Order Analytics
+version: 1.0.0
+
+# Define what this data product produces
+outputs:
+  - id: OrderMetricsCalculated
+  - id: NotificationService
+  - id: orders-db
+  - id: orders-domain-eventbus
+---
+```
+
+## Visualizing relationships
+
+The `<NodeGraph />` component automatically visualizes inputs and outputs.
+
+```md
+<NodeGraph />
+```
+
+![Example](./img/data-product-node-graph.png)
+
+This graph shows:
+- Input events flowing into the data product
+- Output events or data stores produced
+- Services that interact with the data product
+- Contract relationships for data stores
+
+## Complete example
+
+```md title="/data-products/PaymentAnalytics/index.mdx"
+---
+id: payment-analytics
+name: Payment Analytics
+version: 1.0.0
+summary: Payment performance metrics and fraud insights
+
+inputs:
+  - id: PaymentInitiated
+  - id: PaymentProcessed
+  - id: PaymentFailed
+  - id: FraudCheckCompleted
+  - id: PaymentService
+  - id: payments-db
+
+outputs:
+  - id: NotificationService
+  - id: payment-domain-eventbus
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+---
+
+## Overview
+
+Payment Analytics transforms payment lifecycle events into comprehensive metrics.
+
+<NodeGraph />
+
+## Input Events
+
+- **PaymentInitiated** - Start of payment flow (~60k/day)
+- **PaymentProcessed** - Successful payments (~55k/day)
+- **PaymentFailed** - Failed transactions (~5k/day)
+- **FraudCheckCompleted** - Fraud detection results (~60k/day)
+
+## Output Tables
+
+### fact_payments
+
+Transaction-level payment data with fraud scores.
+
+<SchemaViewer file="payment-metrics-contract.json" />
+```
+
+## Next steps
+
+- [Add schema contracts](/docs/development/guides/data-products/contracts)
+- [Version data products](/docs/development/guides/data-products/versioning)
+- [Add to domains](/docs/development/guides/data-products/adding-to-domains)

package/dist/docs/development/guides/data-products/04-contracts.md

@@ -0,0 +1,102 @@
+---
+sidebar_position: 4
+keywords:
+- EventCatalog data products
+sidebar_label: Data Contracts
+title: Data Contracts
+description: Define schema contracts for outputs
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Contracts define the schema structure for data product outputs. They provide clear expectations for downstream consumers and enable schema validation.
+
+Your contracts can be any format you want (e.g JSON Schema, ODCS YAML, etc).
+
+## What are contracts?
+
+Contracts are schema specifications attached to data product outputs. They document the structure, types, and constraints of the data your product produces.
+
+Contracts help teams:
+
+- Understand output data structures without inspecting code
+- Validate data against expected schemas
+- Catch breaking changes before deployment
+- Enable self-service data consumption
+
+## Supported formats
+
+EventCatalog supports any schema or specification format.
+
+## Adding contracts
+
+Contracts are defined in the `outputs` array of your data product frontmatter.
+
+```md title="/data-products/PaymentAnalytics/index.mdx"
+---
+id: payment-analytics
+name: Payment Analytics
+version: 1.0.0
+
+outputs:
+  - id: payment-analytics-db
+    contract:
+      path: payment-metrics-contract.json
+      name: Payment Metrics Contract
+      type: json-schema
+---
+```
+
+Contract properties:
+
+- **path** is the file path relative to the data product directory
+- **name** is the display name shown in EventCatalog
+- **type** specifies the format (`json-schema` or `odcs`)
+
+## Viewing contracts
+
+EventCatalog provides a schema explorer for viewing contracts.
+
+Use the `<SchemaViewer />` component to display contracts in your documentation:
+
+```md
+## Output Schema
+
+<SchemaViewer file="payment-metrics-contract.json" />
+```
+
+![Example](./img/data-schema-viewer.png)
+
+The schema explorer renders:
+
+- Interactive field navigation
+- Type information and constraints
+- Field descriptions
+- Required field indicators
+
+## Multiple contracts
+
+A single output can have multiple contracts for different tables or datasets.
+
+```md
+outputs:
+  - id: analytics-warehouse
+    contract:
+      path: fact-orders.json
+      name: Fact Orders
+      type: json-schema
+  - id: analytics-warehouse
+    contract:
+      path: dim-customers.json
+      name: Customer Dimension
+      type: json-schema
+```
+
+
+## Next steps
+
+- [Version data products](/docs/development/guides/data-products/versioning)
+- [Add to domains](/docs/development/guides/data-products/adding-to-domains)
+- [Schema explorer component](/docs/development/components/using-components)

package/dist/docs/development/guides/data-products/05-versioning.md

@@ -0,0 +1,240 @@
+---
+sidebar_position: 5
+keywords:
+- EventCatalog data products
+sidebar_label: Versioning
+title: Versioning
+description: Version data products and track changes
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Data products follow semantic versioning to track schema changes, input/output modifications, and business logic updates.
+
+## Why version data products?
+
+Versioning helps teams:
+
+- Track schema evolution over time
+- Identify breaking changes before deployment
+- Support multiple versions simultaneously
+- Communicate changes to consumers
+- Maintain historical documentation
+
+## Semantic versioning
+
+Data products use semantic versioning with the format `MAJOR.MINOR.PATCH`.
+
+**MAJOR** version changes indicate breaking changes to outputs, schemas, or contracts.
+
+**MINOR** version changes add new outputs or non-breaking enhancements.
+
+**PATCH** version changes fix bugs or update documentation without affecting outputs.
+
+```md
+---
+id: payment-analytics
+name: Payment Analytics
+version: 1.0.0  # MAJOR.MINOR.PATCH
+---
+```
+
+## Creating versions
+
+Create a `versioned` folder within your data product directory to store previous versions.
+
+```
+/data-products
+  /PaymentAnalytics
+    index.mdx                    # Current version (1.2.0)
+    payment-contract.json
+    /versioned
+      /1.0.0
+        index.mdx
+        payment-contract.json
+      /1.1.0
+        index.mdx
+        payment-contract.json
+```
+
+The root `index.mdx` always represents the latest version.
+
+## Versioning workflow
+
+When making changes to a data product:
+
+1. Copy the current `index.mdx` and related files to a new versioned folder
+2. Update the version number in the root `index.mdx`
+3. Make your changes to the root files
+4. Document changes in the changelog
+
+```bash
+# Create new version folder
+mkdir -p data-products/PaymentAnalytics/versioned/1.1.0
+
+# Copy current files
+cp data-products/PaymentAnalytics/index.mdx data-products/PaymentAnalytics/versioned/1.1.0/
+cp data-products/PaymentAnalytics/payment-contract.json data-products/PaymentAnalytics/versioned/1.1.0/
+
+# Update root version
+# Edit index.mdx: version: 1.2.0
+```
+
+## Breaking changes
+
+Breaking changes require a major version bump and clear communication to consumers.
+
+Examples of breaking changes:
+
+- Removing or renaming output fields
+- Changing field types
+- Removing outputs
+- Modifying contract requirements
+- Changing input dependencies significantly
+
+```md title="Breaking change example"
+---
+id: payment-analytics
+version: 2.0.0  # Major version bump
+summary: Breaking change - renamed fraud_score to risk_score
+---
+
+## Breaking Changes in v2.0.0
+
+- **Renamed field**: `fraud_score` → `risk_score`
+- **Removed field**: `legacy_status` (deprecated in v1.5.0)
+- **Type change**: `transaction_date` now returns ISO 8601 format
+```
+
+## Non-breaking changes
+
+Minor versions add functionality without breaking existing consumers.
+
+Examples of non-breaking changes:
+
+- Adding new output fields
+- Adding new outputs
+- Adding new inputs
+- Enhancing documentation
+- Adding optional filters or parameters
+
+```md title="Non-breaking change example"
+---
+id: payment-analytics
+version: 1.3.0  # Minor version bump
+summary: Added chargeback metrics to output schema
+---
+
+## What's New in v1.3.0
+
+- **New field**: `chargeback_rate` added to output schema
+- **New output**: `ChargebackAlert` event for high-risk transactions
+```
+
+## Version references
+
+When referencing data products from other resources, you can pin to specific versions or use `latest`.
+
+```md title="Service referencing data product"
+---
+id: reporting-service
+name: Reporting Service
+version: 1.0.0
+
+# Pin to specific version
+inputs:
+  - id: payment-analytics
+    version: 1.2.0
+
+# Use latest version (default)
+inputs:
+  - id: order-analytics
+    version: latest
+---
+```
+
+Omitting the version defaults to `latest`:
+
+```md
+inputs:
+  - id: payment-analytics  # Defaults to latest
+```
+
+## Changelog
+
+Document version changes in a `changelog.mdx` file within your data product directory.
+
+```
+/data-products
+  /PaymentAnalytics
+    index.mdx
+    changelog.mdx
+    payment-contract.json
+```
+
+```md title="changelog.mdx"
+---
+createdAt: 2026-01-15
+---
+
+## 1.3.0
+
+### Added
+- Chargeback metrics to output schema
+- ChargebackAlert event for high-risk transactions
+
+### Changed
+- Improved fraud detection model accuracy
+
+## 1.2.0
+
+### Added
+- Revenue attribution by channel
+- Gateway performance metrics
+
+### Fixed
+- Currency conversion edge cases
+
+## 1.1.0
+
+### Added
+- Real-time payment success rate
+- Authorization rate metrics
+
+## 1.0.0
+
+Initial release of Payment Analytics data product.
+```
+
+EventCatalog automatically links changelogs to data product pages.
+
+## Deprecation
+
+Mark data products as deprecated when planning to sunset them.
+
+```md
+---
+id: payment-analytics-v1
+version: 1.0.0
+deprecated:
+  message: Migrate to PaymentAnalyticsV2 for improved performance
+  date: 2026-06-01
+badges:
+  - content: Deprecated
+    backgroundColor: red
+    textColor: red
+---
+
+:::warning Deprecation Notice
+
+This data product will be sunset on June 1, 2026. Migrate to PaymentAnalyticsV2.
+
+:::
+```
+## Next steps
+
+- [Add to domains](/docs/development/guides/data-products/adding-to-domains)
+- [Changelog documentation](/docs/development/guides/changelogs/introduction)
+- [Data product API reference](/docs/api/data-product-api)

package/dist/docs/development/guides/data-products/06-adding-to-domains.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+keywords:
+  - EventCatalog data products
+sidebar_label: Adding to domains
+title: Adding to domains
+description: Organize data products within domains
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.8.0" />
+
+Data products can be placed anywhere in your catalog, but we recommend organizing them within domain folders for better clarity and ownership.
+
+## Adding data products to domains
+
+You can create data products in any directory structure you prefer. We recommend placing them in your domain folder:
+
+```
+/domains
+  /E-Commerce
+    index.mdx
+    /data-products
+      /OrderAnalytics
+        index.mdx
+      /PaymentAnalytics
+        index.mdx
+```
+
+Then reference them in your domain's frontmatter:
+
+```md title="/domains/E-Commerce/index.mdx"
+---
+id: e-commerce
+name: E-Commerce
+version: 1.0.0
+
+data-products:
+  - id: order-analytics
+  - id: payment-analytics
+    # version is optional for all data products
+    version: 1.0.0
+---
+```
+
+This associates the data products with your domain and displays them on the domain page.
+
+## Next steps
+
+- [Domain documentation](/docs/development/guides/domains/introduction)
+- [Data product API reference](/docs/api/data-product-api)

package/dist/docs/development/guides/data-products/_category_.json

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