Collections Schema Document

The schema document is the one YAML file that holds all the collections of an app. This page is generated from collections-document.schema.json, the JSON Schema the platform checks a document against, so it describes the format as it is checked. App Data explains what the keys do; the routes that save, preview and publish a document are under App collections.

Document

Collection

One entry of collections, under its key. A key matches ^[a-z][a-z0-9_]{0,62}$.

Access

The access of a collection says which roles may do what with its records. A value is a role key or a list of role keys; update and delete also take all and own. A missing key, or a collection without access, grants that action to nobody.

Field types

A field is an object under fields whose type decides which options it accepts. An option a type does not list is refused: the format knows no other keys.

Options of every type

text

One line of text.

long_text

Text with line breaks.

number

A JSON number.

boolean

true or false.

No options of its own.

select

One option value, or a list of them when multiple is set.

date

A date as YYYY-MM-DD.

No options of its own.

datetime

A moment in ISO 8601, in UTC, to the millisecond.

No options of its own.

json

Any JSON value, checked against a template or an inline JSON Schema when schema is set.

reference

The id of a record in another collection.

JSON templates

A json field names one of these in schema. The units are metres and radians, and frame_id is the name of a coordinate frame. Each template is a closed object with every property required.

pose2d

A position and a heading in a plane.

Example:

{
  "x": 12.5,
  "y": -3.2,
  "yaw": 1.5708,
  "frame_id": "map"
}

point2d

A position in a plane.

Example:

{
  "x": 4,
  "y": 0.5,
  "frame_id": "map"
}

polygon2d

A closed outline in a plane, given by its corners in order.

Example:

{
  "points": [
    {
      "x": 0,
      "y": 0
    },
    {
      "x": 4,
      "y": 0
    },
    {
      "x": 4,
      "y": 3
    }
  ],
  "frame_id": "map"
}

range1d

An interval along one axis.

Example:

{
  "from": 2.5,
  "to": 8
}

Keys and limits

• A collection key and a field key match ^[a-z][a-z0-9_]{0,62}$.
• These field keys are reserved: id, robot, robot_id, created_at, created_by, updated_at, updated_by and revision.
• A document has at most 50 collections, and a collection at most 100 fields.
• A select has 1 to 500 options.
• The document as text is at most 1,000,000 bytes of UTF-8.

Validity

A document is refused with 400 validation_error when it is not YAML or JSON, when it does not match this schema, or when it has an error below. A key the format does not know counts: it is nearly always a typo. Each finding is { path, code, message, severity }, where path points into the document, as in collections.chargers.fields.location.to.

Only an error makes a document invalid; a warning or information leaves it valid. Nothing about the stored data does, see Publishing a schema. The findings reach a caller in the issues of a preview.