Skip to main content

Interface

This schema describes how an Data Orchestrator interface should be declared.

Properties Summary​

PropertyTypeDescriptionRequired
interface_namestringThe name of the interface. This has to be an unique, alphanumeric reverse internet domain name, shorter than 128 characters.✔ Yes
version_majorintegerA Major version qualifier for this interface. Interfaces with the same id and different version_major number are deemed incompatible. It is then acceptable to redefine any property of the interface when changing the major version number.✔ Yes
version_minorintegerA Minor version qualifier for this interface. Interfaces with the same id and major version number and different version_minor number are deemed compatible between each other. When changing the minor number, it is then only possible to insert further mappings. Any other modification might lead to incompatibilities and undefined behavior.✔ Yes
typestringIdentifies the type of this Interface. Currently two types are supported: datastream and properties. datastream should be used when dealing with streams of non-persistent data, where a single path receives updates and there's no concept of state. properties, instead, are meant to be an actual state and as such they have only a change history, and are retained.✔ Yes
ownershipstringIdentifies the quality of the interface. Interfaces are meant to be unidirectional, and this property defines who's sending or receiving data. device means the device/gateway is sending data to Data Orchestrator, consumer means the device/gateway is receiving data from Data Orchestrator. Bidirectional mode is not supported, you should instantiate another interface for that.✔ Yes
aggregationstringIdentifies the aggregation of the mappings of the interface. Individual means every mapping changes state or streams data independently, whereas an object aggregation treats the interface as an object, making all the mappings changes interdependent. Choosing the right aggregation might drastically improve performances.No, default: "individual"
descriptionstringAn optional description of the interface.No
docstringA string containing documentation that will be injected in the generated client code.No
mappingsData Orchestrator Mapping Schema [1-1024]Mappings define the endpoint of the interface, where actual data is stored/streamed. They are defined as relative URLs (e.g. /my/path) and can be parametrized (e.g.: /%{myparam}/path). A valid interface must have no mappings clash, which means that every mapping must resolve to a unique path or collection of paths (including parametrization). Every mapping acquires type, quality and aggregation of the interface.✔ Yes

Property Details​

astarte.interface.schema.interface_name ✔​

The name of the interface. This has to be an unique, alphanumeric reverse internet domain name, shorter than 128 characters.

  • Type: string
  • Required: Yes
  • Minimum Length: >= 1
  • Allowed Pattern: ^([a-zA-Z][a-zA-Z0-9]*.([a-zA-Z0-9][a-zA-Z0-9-]*.)*)?[a-zA-Z][a-zA-Z0-9]*$

astarte.interface.schema.version_major ✔​

A Major version qualifier for this interface. Interfaces with the same id and different version_major number are deemed incompatible. It is then acceptable to redefine any property of the interface when changing the major version number.

  • Type: integer
  • Required: Yes

astarte.interface.schema.version_minor ✔​

A Minor version qualifier for this interface. Interfaces with the same id and major version number and different version_minor number are deemed compatible between each other. When changing the minor number, it is then only possible to insert further mappings. Any other modification might lead to incompatibilities and undefined behavior.

  • Type: integer
  • Required: Yes

astarte.interface.schema.type ✔​

Identifies the type of this Interface. Currently two types are supported: datastream and properties. datastream should be used when dealing with streams of non-persistent data, where a single path receives updates and there's no concept of state. properties, instead, are meant to be an actual state and as such they have only a change history, and are retained.

  • Type: string
  • Required: Yes
  • Allowed values:
    • "datastream"
    • "properties"

astarte.interface.schema.ownership ✔​

Identifies the quality of the interface. Interfaces are meant to be unidirectional, and this property defines who's sending or receiving data. device means the device/gateway is sending data to Data Orchestrator, server means the server is sending data. Bidirectional mode is not supported, you should instantiate another interface for that.

  • Type: string
  • Required: Yes
  • Allowed values:
    • "device"
    • "server"

astarte.interface.schema.aggregation​

Identifies the aggregation of the mappings of the interface. individual means every mapping changes state or streams data independently, whereas an object aggregation treats the interface as an object, making all the mappings changes interdependent. Choosing the right aggregation might drastically improve performances.

  • Type: string
  • Required: No, default: "individual"
  • Allowed values:
    • "individual"
    • "object"

astarte.interface.schema.description​

An optional description of the interface.

  • Type: string
  • Required: No

astarte.interface.schema.doc​

A string containing documentation that will be injected in the generated client code.

  • Type: string
  • Required: No

astarte.interface.schema.mappings ✔​

Mappings define the endpoint of the interface, where actual data is stored/streamed. They are defined as relative URLs (e.g. /my/path) and can be parametrized (e.g.: /%{myparam}/path). A valid interface must have no mappings clash, which means that every mapping must resolve to a unique path or collection of paths (including parametrization). Every mapping acquires type, quality and aggregation of the interface.