General Conventions

Certain conventions are used throughout the API, which are summarized here to avoid having to repeat them in each document where they apply.

Requirement levels

Regarding requirement levels, the usual conventions apply:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Coordinate system

The coordinate system used is a right handed cartesian coordinate system. Therefore the vector (1,0) points to the right hand side of the vector (0,1).

For consistent visualizations, the x-axis should point to the right and the y-axis should point upwards.

Units in the API

For quantities with units, this API uses metric values if not specified otherwise.

In particular:

  • Lengths are specified in millimeters.

  • Angles are specified in degrees counterclockwise.

Required and optional values

Unless stated otherwise, all properties of objects are optional. In that case, strings default to "", numbers to 0 and lists and object shall be considered empty.

Attributes marked as "required" MUST be included. Otherwise implementations are free to reject the whole document as invalid.

Sometimes attributes are explicitly marked as "optional". This is only to emphasize that leaving out this property is explicitly supported, typically if a certain use case would require or at least strongly suggest omitting the property.