# Services reference

Copy as Markdown[View as Markdown](/docs/development/guides/resources/services/reference.md)

***

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

## Paths[​](#paths "Direct link to 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[​](#routes "Direct link to Routes")

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

## Required fields[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to id")

* Type: `string`

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

Example

```
---
id: payment-service
---
```

### `name`[​](#name "Direct link to name")

* Type: `string`

Display name of the service.

Example

```
---
name: Payment Service
---
```

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the service documentation.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short summary of what the service does.

Example

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

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

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

Example

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

### `sends`[​](#sends "Direct link to sends")

* Type: `array`

Messages the service sends or publishes.

Example

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

### `receives`[​](#receives "Direct link to receives")

* Type: `array`

Messages the service receives or consumes.

Example

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

### `entities`[​](#entities "Direct link to entities")

* Type: `array`

Entities associated with the service.

Example

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

### `writesTo`[​](#writesTo "Direct link to writesTo")

* Type: `array`

Data stores the service writes to.

Example

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

### `readsFrom`[​](#readsFrom "Direct link to readsFrom")

* Type: `array`

Data stores the service reads from.

Example

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

### `flows`[​](#flows "Direct link to flows")

* Type: `array`

Flows associated with the service.

Example

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

### `externalSystem`[​](#externalSystem "Direct link to externalSystem")

* Type: `boolean`

Marks the service as an external service or integration.

Example

```
---
externalSystem: true
---
```

### `specifications`[​](#specifications "Direct link to 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`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the service page.

Example

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

### `repository`[​](#repository "Direct link to repository")

* Type: `object`

Repository metadata for the service.

Example

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

### `diagrams`[​](#diagrams "Direct link to diagrams")

* Type: `array`

Diagrams associated with the service.

Example

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

### `attachments`[​](#attachments "Direct link to 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[​](#resource-pointers "Direct link to 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.