> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md).

# Definitions

Keep values that several resources share in one place, and insert them with !ref, !sub, or !merge.

The definitions section holds values that several resources reuse. When such a value changes, you change it in one place. Definitions are similar to parameters, but they are for internal use only. Unlike [parameters](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md), definitions are fixed in the service commissioning file, so nobody enters them at installation.

* **Optional**
* Type: `object`, with one entry per definition

A definition can hold any YAML value, such as a number, a string, a list, or an object. You insert it with the following tags:

* `!ref` inserts the value of a definition, for example `interval: !ref pollingInterval`.
* `!sub` inserts the value into a string, for example `!sub 'Line ${lineName}'`.
* `!merge` combines the properties of an object definition with properties that you add.

One definition name has a special meaning. A definition named `CYBUS_MQTT_ROOT` replaces the default topic prefix of the service, which the global parameter `Cybus::MqttRoot` holds. See [Custom Topic Prefix](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#custom-topic-prefix).

## Merging Definitions

To merge a definition, write its name as a key with an empty value inside a `!merge` object. Connectware replaces that key with the properties of the definition. You can merge several definitions and add your own properties.

When a property appears more than once, the last one wins. The merge is shallow, so a property that you add replaces a nested object of the definition as a whole.

## Example

The following excerpt reads two values from the same Modbus/TCP device. The connection inserts the object definition `modbusDevice` with `!ref`. Both endpoints merge the shared endpoint settings and use the shared polling interval:

{% code title="modbus-device.yml" lineNumbers="true" %}

```yaml
definitions:
  pollingInterval: 1000
  modbusDevice:
    host: 192.168.1.100
    port: 502
  modbusEndpointDefaults:
    protocol: Modbus
    connection: !ref modbusConnection

resources:
  modbusConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      connection: !ref modbusDevice # inserts the whole object

  temperature:
    type: Cybus::Endpoint
    properties: !merge
      modbusEndpointDefaults: # protocol and connection from the definition
      subscribe:
        fc: 3
        address: 1
        length: 2
        interval: !ref pollingInterval
        dataType: floatBE

  pressure:
    type: Cybus::Endpoint
    properties: !merge
      modbusEndpointDefaults:
      subscribe:
        fc: 3
        address: 3
        length: 2
        interval: !ref pollingInterval
        dataType: floatBE
```

{% endcode %}

For the `temperature` endpoint, the merge results in the following properties. They are the same as if you wrote them out in full:

{% code title="Merged properties of temperature" lineNumbers="true" %}

```yaml
protocol: Modbus
connection: !ref modbusConnection
subscribe:
  fc: 3
  address: 1
  length: 2
  interval: 1000
  dataType: floatBE
```

{% endcode %}

Each endpoint keeps its own `subscribe` settings, because the merge is shallow. If `modbusEndpointDefaults` also held a `subscribe` object, the `subscribe` of the endpoint would replace it as a whole. Write the definition first in a `!merge` object, so that the properties you add override it.

To read the device every 500 milliseconds instead, you change only `pollingInterval`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
