Skip to main content

Event frontmatter API

Overview​

Events are just markdown files, with this comes the use of Content, MDX components and also front-matter.

Here is an example of the event frontmatter you will find in your /events folder.

/events/InventoryOutOfStock/index.mdx (example)
---
# id of your event, used for slugs and references in EventCatalog.
id: InventoryOutOfStock

# Display name of the event, rendered in EventCatalog
name: Out of stock

# Version of the event
version: 0.0.3

# Short summary of your event
summary: |
  Event that is raised when an inventory item goes out of stock.

# Optional owners, references teams or users
owners:
    - dboyne

repository:
  language: JavaScript
  url: https://github.com/event-catalog/pretend-shipping-service

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New event
      backgroundColor: blue
      textColor: blue
      # Optional link to display (optional)
      link: https://github.com/event-catalog/pretend-shipping-service
---

## Overview

Event is published when the inventory is out of stock.

<NodeGraph />

Required fields​

id​

  • Type: string

Unqiue id of the event. EventCatalog uses this for references and slugs.

Example
---
  id: InventoryOutOfStock
---

name​

  • Type: string

Name of the event this is used to display the name on the UI.

Example
---
  name: Out of stock
---

version​

  • Type: string

Version of the event.

Example
---
  version: 0.0.1
---

Optional fields​

summary​

Short summary of your event, shown on event summary pages.

Example
---
  summary: |
    Event that is raised when an inventory item goes out of stock.
---

owners​

An array of user ids that own the event.

Example
---
  owners:
    - dboyne
    - mSmith
---

badges​

An array of badges that get rendered on the page.

Example
---
  badges:
    - content: My badge
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

specifications​

Added in eventcatalog@2.39.1

You can assign one or more specifications to a event.

Example
---
  specifications:
    - type: asyncapi
      path: order-service-asyncapi.yaml
      name: AsyncAPI Specification
    - type: openapi
      path: openapi.yml
      name: OpenAPI Specification
---
PropertyTypeRequiredDescription
typestringYesThe type of specification, currently only asyncapi and openapi are supported
pathstringYesThe path to the specification file
namestringNoOptional friendly name of the specification, rendered in the UI

Older versions of EventCatalog (< 2.39.0)

If you are using an older version of EventCatalog you will need to use the following syntax.

Example
---
  specifications:
    asyncapiPath: order-service-asyncapi.yaml
    openapiPath: openapi.yml
---

repository​

Added in eventcatalog@2.11.2

Repository language and code url for the event.

Example
---
  repository:
    language: JavaScript
    url: https://github.com/event-catalog/pretend-shipping-service
---
Added in eventcatalog@2.29.3

Configure the event label and message in the docs sidebar.

Example
---
  sidebar:
    badge: Event
    label: Inventory Adjusted
---

visualiser​

Added in eventcatalog@2.39.2

Turn off the visualiser for this resource. This means the resource will not be included in the visualiser or the navigation bar for the visualiser.

Default: true

Example
---
  visualiser: false
---

draft​

Added in eventcatalog@2.48.4

Mark the event as a draft. This will show the event as a draft in the UI.

You can also specify a title and summary for your draft to help you communicate the status of the draft.

/commands/UpdateInventoryStock/index.mdx (example)
---
# Uses the default title and summary to mark things as draft in the UI
draft: true

# Or you can specify a title and summary for your draft
draft: 
  title: "Update Inventory Stock 1.0.1 is in draft"
  # Supports markdown
  message: |
    ### New version of Update Inventory Stock command is in draft

    This is a new version of the Update Inventory Stock command. It is not yet ready for production. We are still working on it and collecting feedback from the team.
    You can use this version in lower environments, **but please be aware that it is still in draft and may change.**
    You can still use a previous version of the command, [Update Inventory Stock 1.0.0](/docs/commands/UpdateInventoryStock/1.0.0), until that version is deprecated.
    _If you would like to provide feedback, please contact us at [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack channel [Order Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000)_

---