Skip to main content

Query frontmatter API

Overview​

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

Here is an example of the query frontmatter you will find in your /queries folder.

/queries/GetOrder/index.mdx (example)
---
# id of your query, used for slugs and references in EventCatalog.
id: GetOrder

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

# Version of the query
version: 0.0.3

# Short summary of your query
summary: |
  Query 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 query
      backgroundColor: blue
      textColor: blue
---

## Overview

Query is published when the inventory is out of stock.

<NodeGraph />

Required fields​

id​

  • Type: string

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

Example
---
  id: GetOrder
---

name​

  • Type: string

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

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

version​

  • Type: string

Version of the query.

Example
---
  version: 0.0.1
---

Optional fields​

summary​

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

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

owners​

An array of user ids that own the query.

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

Specifications to include on the page

Current supports AsyncAPI and OpenAPI files. When including the specifications the page will render badges and buttons for the specifications.

specifications​

Added in eventcatalog@2.39.1

You can assign one or more specifications to a query.

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

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: GET
    label: List Inventory Items
---

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 query as a draft. This will show the query 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.

/queries/GetInventoryStock/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: "Get Inventory Stock 1.0.1 is in draft"
  # Supports markdown
  message: |
    ### New version of Get Inventory Stock query is in draft

    This is a new version of the Get Inventory Stock query. 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 query, [Get Inventory Stock 1.0.0](/docs/queries/GetInventoryStock/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)_

---