Data Product frontmatter API

Added in eventcatalog@3.8.0

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 are markdown files with Content, MDX components and front-matter.

Here is an example of a basic data product.

/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.

Example
---
  id: payment-analytics
---

`name`

Type: string

Name of the data product used to display on the UI.

Example
---
  name: Payment Analytics
---

`version`

Type: string

Version of the data product.

Example
---
  version: 1.0.0
---

Optional fields

`summary`

Short summary of your data product, shown on summary pages.

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.

Example
---
inputs:
  - id: PaymentProcessed
  - id: OrderConfirmed
  - id: PaymentService
  - id: payments-db
---

Each input can optionally specify a version:

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.

Example
---
outputs:
  - id: OrderMetricsCalculated
  - id: NotificationService
  - id: orders-analytics-db
---

Outputs can include contracts to define schema specifications:

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.

Example
---
owners:
  - analytics-team
  - dboyne
---

`badges`

Added in eventcatalog@3.39.4

Type: array

Array of badges to display on the data product page.

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 (named token or CSS value)
`textColor`	`string`	Yes	Text color (named token or CSS value)
`url`	`string`	No	When set, the badge renders as a clickable link with an external-link icon

Use named colors

Set backgroundColor or textColor to a named palette token for automatic light/dark mode adaptation.

Supported names: slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Use any CSS color

You can also pass any valid CSS color value directly: hex (#ff0000), rgb(), hsl(), oklch(), or a CSS variable (var(--my-color)).

Link to external URLs

Added in eventcatalog@3.39.6

Add a url to a badge to make it render as a clickable link with an external-link icon. When url is omitted, the badge renders as a plain label.

Link badge example
---
badges:
  - content: View Runbook
    url: https://runbooks.example.com/my-data-product
    backgroundColor: blue
    textColor: white
---

`repository`

Type: object

Repository information for the data product.

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.

Example
---
schemaPath: ./payment-schema.json
---

`sidebar`

Type: object

Customize sidebar appearance for the data product.

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).

Example
---
specifications:
  - type: openapi
    path: ./api-spec.yaml
    name: Payment Analytics API
---

`hidden`

Type: boolean

Hide the data product from the catalog UI.

Example
---
hidden: true
---

`editUrl`

Type: string

Custom edit URL for the data product documentation.

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.

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.

Example
---
styles:
  icon: DatabaseIcon
  node:
    color: "#4F46E5"
    label: Payment Analytics
---

`deprecated`

Type: boolean | object

Mark the data product as deprecated.

Example (boolean)
---
deprecated: true
---

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.

Example
---
visualiser: false
---

`attachments`

Type: array

Array of attachments for the data product.

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

Overview​

Required fields​

id​

name​

version​

Optional fields​

summary​

inputs​

outputs​

owners​

badges​

Use named colors​

Use any CSS color​

Link to external URLs​

repository​

schemaPath​

sidebar​

specifications​

hidden​

editUrl​

resourceGroups​

styles​

deprecated​

visualiser​

attachments​