Services reference

View as Markdown

---

This page lists the fields, paths, and routes supported by services.

Paths

Services can be created at the root of your catalog:

/services/{Service Name}/index.mdx

Services can also be created inside domains or systems:

/domains/{Domain Name}/services/{Service Name}/index.mdx
/systems/{System Name}/services/{Service Name}/index.mdx
/domains/{Domain Name}/systems/{System Name}/services/{Service Name}/index.mdx

Versioned services use:

/services/{Service Name}/versioned/{version}/index.mdx

Routes

Route	Description
/docs/services/{service-id}/{version}	Service documentation page.
/visualiser/services/{service-id}/{version}	Service resource diagram.

Required fields

id

• Type: string

Unique id of the service. EventCatalog uses this for URLs and resource references.

Example

---
id: payment-service
---

name

• Type: string

Display name of the service.

Example

---
name: Payment Service
---

version

• Type: string

Version of the service documentation.

Example

---
version: 1.0.0
---

Optional fields

summary

• Type: string

Short summary of what the service does.

Example

---
summary: Authorizes payments and emits payment lifecycle events.
---

owners

• Type: array

An array of team or user ids that own the service.

Example

---
owners:
  - payments-platform
---

sends

• Type: array

Messages the service sends or publishes.

Example

---
sends:
  - id: PaymentAuthorized
    version: 1.0.0
---

receives

• Type: array

Messages the service receives or consumes.

Example

---
receives:
  - id: AuthorizePayment
    version: 1.0.0
---

entities

• Type: array

Entities associated with the service.

Example

---
entities:
  - id: payment
    version: 1.0.0
---

writesTo

• Type: array

Data stores the service writes to.

Example

---
writesTo:
  - id: payments-database
    version: 1.0.0
---

readsFrom

• Type: array

Data stores the service reads from.

Example

---
readsFrom:
  - id: customer-database
    version: 1.0.0
---

flows

• Type: array

Flows associated with the service.

Example

---
flows:
  - id: payment-authorization
    version: 1.0.0
---

externalSystem

• Type: boolean

Marks the service as an external service or integration.

Example

---
externalSystem: true
---

specifications

• Type: object or array

OpenAPI, AsyncAPI, or GraphQL specifications for the service.

Example

---
specifications:
  - type: openapi
    path: openapi.yml
    name: Public API
  - type: asyncapi
    path: asyncapi.yml
---

badges

• Type: array

Badges rendered on the service page.

Example

---
badges:
  - content: Critical
    backgroundColor: red
    textColor: red
---

repository

• Type: object

Repository metadata for the service.

Example

---
repository:
  language: TypeScript
  url: https://github.com/acme/payment-service
---

diagrams

• Type: array

Diagrams associated with the service.

Example

---
diagrams:
  - id: payment-service-sequence
    version: 1.0.0
---

attachments

• Type: array

External links or supporting documents attached to the service.

Example

---
attachments:
  - url: https://runbooks.example.com/payment-service
    title: Payment Service runbook
    type: runbook
---

Resource pointers

Services reference related resources using id and optional version.

---
sends:
  - id: OrderCreated
receives:
  - id: CreateOrder
writesTo:
  - id: orders-database
flows:
  - id: checkout-flow
---

If version is omitted, EventCatalog uses the latest version.