Schemas and Role Policies (legacy)

📘

Enterprise Feature

Schemas and role policies allow developers to increase control and improve the quality of their integrations by implementing controlled access to other resources, such as Thng properties and actions. A schema enables input validation as well as output filtering to ensure Application Users can only read/write what they are permitted to by the account Operator.

The process of setting up an implementation of schema and role policy resources requires appropriate use of roles and permissions as well, and is summarized in the image below.

Schemas

The schema resource allows developers to associate a JSON Schema with a resource type, such as Thngs, for the purposes of data validation on input requests and filtering on output payloads. The schema is applied only when a request is made to a resource of the specified type by an Application User given the role in an associated policy.

For input requests (e.g. POST and PUT), the applied schema will restrict which fields can be written to. For output (GET) responses, the applied schema will filter out any fields that are not in the schema.

Current Applications

Currently, schemas are applied to limit requests made by Application Users in the context of an Application User role, and to restrict read and write requests for the following endpoints, dictated by the schema's resourceType:

• thngs - /thngs/:thngId - Validate property names when a Thng is created.
• thng_properties - /thngs/:thngId/properties - Validate updates to Thng properties.
• actions - /actions/:type - Validate actions are created with the correct action type.

Role Policies

A role policy resource creates an association between a schema and a role. For any Application Users assigned that role, the schema in the role policy will be applied to the requests they make to the Platform.

For example, if the schema associated with the role policy specifies that Thngs may only contain the power_watts property, any Application User to whom that role policy applies will see only that property when reading a Thng, and will be able to write only that property when creating or updating Thng properties.

Filtering and Validation

To apply a schema to a given Application User, you must associate it via a role policy. See Roles and Role Policies sections for more information on these resources.

The validation/filtering process of a request is summarized in the diagram below. Each request must satisfy the following requirements:

• The Application User's role contains permissions that include the resource type they are trying to access/modify.
• The Application User's role is included in a role policy that associates it with an appropriate schema.
• The schema in that role policy must include the fields they are trying to access or modify.

Below is an example thngs schema that limits the properties on newly created Thngs to only the ‘power_watts’ and ‘firmware_version’ properties.

Note that the properties keyword is part of JSON Schema object syntax, as well as being a property of a ThngDocument, which can initially be confusing. In the example below, the first and third instances of properties are JSON Schema keywords to describe object properties, and the second instance is the ThngDocument field for the Thng's properties.

{
  "type": "object",
  "properties": {
    "properties": {
      "type": "object",
      "properties": {
        "power_watts": {
          "type": "integer",
          "description": "The device's current power output",
          "minimum": 0,
          "maximum": 120
        },
        "firmware_version": {
          "type": "string",
          "description": "The device's current firmware version",
          "readOnly": true
        }
      }
    }
  }
}

In this example, the Application User can read and write the power_watts property, and read (but not write) the firmware_version property, as it has a ”readOnly”:true property.

By embedding the JSON Schema description into a Platform schema resource, it will be applied according to the schema resource's resourceType field:

{
  "name": "Power and Firmware Schema",
  "resourceType": "thngs",
  "product": "VHFLbNsngduI0uSbSl5Avs8b",
  "jsonSchema": {
    "type": "object",
    "properties": {
      "properties": {
        "type": "object",
        "properties": {
          "power_watts": {
            "type": "integer",
            "description": "The device's current power output",
            "minimum": 0,
            "maximum": 120
          },
          "firmware_version": {
            "type": "string",
            "description": "The device's current firmware version",
            "readOnly": true
          }
        }
      }
    }
  }
}

For Application User role filtering and validation, schemas are applied pessimistically. This means that if the property name in a request or response is not explicitly referenced in the schema, the system assumes that the Application User does not have access to that property. For writes specifically, any attempt to write a property that the Application User does not have access to will result in a 403 Forbidden response being returned.