Structure and contents of a compass.yml file

Compass uses a YAML configuration file, compass.yml to manage a component’s details via configuration as code (config as code). Let’s take a look at the file’s structure and contents.

Filename

The configuration file should be named compass.yml.

Association with a component

Each component can have only one compass.yml file associated with it. The file contains a component’s unique identifier, which associates each file with its corresponding component.

To declare multiple components within the same repository, use multiple compass.yml files in separate subfolders.

Structure of a compass.yml file

The compass.yml file contains key-value pairs that describe a component’s details. The key represents the component’s attribute, whereas the value represents the actual value of that attribute in Compass.

Here’s an example of a compass.yml file that declares only a few details of a Service-type component:

1
2
configVersion: 1
name: my-service
id: 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
description: This is a sample component in Compass.
typeId: SERVICE
ownerId: null
fields: {}
labels: []
links: []
customFields: []
relationships: {}

Here’s another sample structure of the file that declares more details of the same component:

1
2
configVersion: 1
name: my-service
id: 'ari:cloud:compass:a0000000-b000-c000-d000-e00000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
description: This is a sample component in Compass.
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'
typeId: SERVICE
fields:
  tier: 1
  lifecycle: Active
links:
  - name: My Jira project
    type: PROJECT
    url: 'https://www.example.com/projects/myproject'
  - name: How to use my-service
    type: DOCUMENT
    url: 'https://www.example.com/user-guide/how+to+use+my+service'
  - name: null
    type: OTHER_LINK
    url: 'https://www.example.com/resources/'
  - name: Service dashboard
    type: DASHBOARD
    url: 'https://www.example.com/dashboards/service-dashboard'
  - name: Service repository
    type: REPOSITORY
    url: 'https://www.example.com/repos/my-service-repo'
labels:
  - foo:bar
  - baz
customFields:
  - name: platform
    type: text
    value: web
  - name: reviewed
    type: boolean
    value: true
relationships:
  DEPENDS_ON:
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-00000000000'

Contents of a compass.yml file

Here’s a description of each attribute in the compass.yml file:

configVersion (optional)

The only supported version right now is 1.
```
1
2
configVersion: 1
```
name (required)

The display name of the component in Compass, in plain text. The name is not required to be unique, but we recommend using a unique name to prevent confusion among components.
```
1
2
name: Your component name goes here
```

id (required)

An unique, unchangeable identifier of the component in Compass. The id must match an existing component in your Compass catalog. The Bitbucket integration uses the id to determine which component your compass.yml file refers to. Learn how to find a component's ID

The id has the following format:

1
2
id: 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'

Enclose the entire value of the id in single quotes.

description (optional)

The description of the component, in plain text.

1
2
description: Your component description goes here.

To specify a multi-line description, begin the value with |- and indent each line of the description:

1
2
description: |-
  This is a multi-line description.
  Here's the second line.
  And the third.

If the component does not have a description, set the value to null:

1
2
description: null

typeId (optional)

Set the component's type by using the typeId field. Acceptable values are:
- APPLICATION
- SERVICE
- CAPABILITY
- CLOUD_RESOURCE
- DATA_PIPELINE
- LIBRARY
- MACHINE_LEARNING_MODEL
- OTHER
- UI_ELEMENT
- WEBSITE
Learn more about component types.
ownerId (optional)

An unique identifier of the team that owns the component. If specified, the ownerId must match a team in your Atlassian organization. Learn how to find a team's owner ID

The ownerId has the following format:
```
1
2
ownerId: 'ari:cloud:teams::team/00000000-0000-0000-0000-000000000000'
```
Enclose the entire value of the ownerId in single quotes.

If the component does not have an owner team, set the value to null:
```
1
2
ownerId: null
```
fields: tier (required for components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE, invalid for components of type APPLICATION, LIBRARY, OTHER)

The Service tier of the component. The accepted values are:
- 1 (highest importance)
- 2
- 3
- 4 (lowest importance)
For components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE, nest tier under fields, as follows:
```
1
2
fields:
  tier: 3
```
For components of type APPLICATION, LIBRARY, OTHER, leave fields empty.
```
1
2
fields: {}
```
The tier field is only valid for components of type SERVICE, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE. For other component types, if you add a tier field, the update fails.
fields: lifecycle (optional)

The current lifecycle status of the component. The accepted values are:
- Pre-release
- Active
- Deprecated
```
1
2
fields:
  lifecycle: Active
```
links (optional)

A list of the links to a component’s resources such as a Jira project, dashboards, documentation, and more. Learn more about the available link types

Specify each link by using the following parameters:
- type (required): The type of link. The acceptable values are:
  - CHAT_CHANNEL
  - DOCUMENT
  - DASHBOARD
  - ON_CALL
  - PROJECT
  - REPOSITORY
  - OTHER_LINK
- url (required): The actual URL of the link, beginning with http:// or https://.
- name (optional): The display name of the link, in plain text, that Compass will show instead of the url. If you omit this or set it to null, Compass attempts to resolve the url and display its title.
You can add multiple links in the compass.yml file. See the following sample format:
```
1
2
links:
  - name: 'My documentation'
    type: DOCUMENT
    url: 'https://www.example.com/document/'
  - name: 'My respository'
    type: REPOSITORY
    url: 'https://www.example.com/repo/'
```
If a component does not have any links, leave the links list empty.
```
1
2
links: []
```

relationships : DEPENDS_ON (optional)

A list of the other components that a component depends on. Learn more about the available dependency types

List the components under DEPENDS_ON. Each item in the list must match a component's id in your Compass catalog. Learn how to find a component's ID

Here’s a sample that shows a component’s relationship with two other components:

1
2
relationships:
  DEPENDS_ON:
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'
    - 'ari:cloud:compass:00000000-0000-0000-0000-000000000000:component/11111111-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000'

If the component does not depend on any other components, leave relationships empty.

1
2
relationships: {}

customFields (optional) A list of the custom fields to set values for. The custom fields must already exist in your Compass site and you need the case-sensitive name and type of each field. Learn more about custom fields Specify each custom field value to set by using the following parameters:
- type (required): The type of custom field. The acceptable values are:
  - text
  - boolean
  - number
  - user
- value (required): The value you'd like to set for the custom field. Acceptable values for each type are:
  - text: A string.
  - boolean: true or false.
  - number: A number.
  - user: An ARI of a Compass user.
- name (required): The name of the custom field (case sensitive).
You can add multiple custom fields in the compass.yml file. See the following sample format:
```
1
2
customFields:
  - name: 'Date of last security review'
    type: text
    url: '2023-03-09'
  - name: 'Requires audit?'
    type: boolean
    value: false
```
If a component does not have any custom fields, leave the list empty.
```
1
2
customFields: []
```
labels (optional) A list of labels to apply to the component. Each label is a string.

You can add multiple labels in the compass.yml file. See the following sample format:
```
1
2
labels:
  - "foo:bar"
  - "baz"
```
If a component does not have any labels, leave the list empty.
```
1
2
labels: []
```

File validation

After you commit the compass.yml file to your repository, Compass validates the file before processing any updates.

If the compass.yml file is invalid, Compass rejects the update and does not make any changes to the component. You’ll know there is a problem if the component details aren’t updated in Compass within a few seconds.
If your updates to compass.yml file aren’t being processed, verify the following:
The YAML syntax is valid. You can check the syntax using an online tool such as YAML Validator.
You've provided all the required fields, and have spelled all the field names correctly.
You specify a valid value for fields accepting a limited set of values, such as tier.
The id and any relationships match existing components in your Compass catalog.
The ownerId matches an existing team in your Atlassian organization.