Schemas allow the Platform to perform validation and filtering of other resources. For example, ensuring that an Application User can only view certain properties on a Thng. Schemas themselves are valid JSON Schema objects. See the Schema Types section below for some example schema resources.
Applying schemas to requests into the Platform is achieved by associating it with a role policy. See the Role Policies section for more information.
Notes
- Schema resources are shared across an entire account, and so are applied to resources that match them in all projects.\n\n* In order to use the
readOnlykeyword, thejsonSchemamust specify thehttps://evrythng.com/jsonSchema#namespace as its$schemaproperty (see the examples below).
API Status
Beta:
/schemas
/schemas/:schemaId
SchemaDocument Data Model
Schema Types
Below are some example schemas for each supported resourceType in the Platform for which a schema resource can be applied.
- Thngs Schema - filters Thng properties upon Thng creation.
- Thng Properties Schema - filters Thng properties directly.
- Thng Property Key Schema - filters value updates for a particular Thng property by key name.
- Thng Actions Schema - filters action types for a given Thng.
Thngs Schema
The thngs schema resource limits access and visibility of a Thng's properties by name when a new Thng is being created with properties using the /thngs endpoint.
When a schema is being used to filter a POST, PUT, or GET request to Thng properties, the inclusion of any given property depends on its inclusion in the schema, and whether or not it is writable. This is summarized in the table below.
The SchemaDocument below is an example of the Thngs schema type.
Thng Properties Schema
Whereas a Thngs schema validates and filters Thng properties when a Thng is created with properties, a Thng properties schema is applied when a Thng's properties are created/updated with the /thngs/:thngId/properties endpoint. This is due the the fact that from this endpoint, the list of properties takes on a different format.
Like the other schema types, it is applied according to the product ID rules.
The SchemaDocument below is an example of the Thng properties schema type.
Read-only in Thng Properties Schemas
In order to apply a readOnly rule in a Thng properties schema, it is required to use the JSON Schema oneOf keyword. This allows the developer to specify multiple possible enums for the key property being validated in each case readOnly is required.
An example is shown below, and has been collapsed for brevity.
Thng Property Key Schema
Similar to the Thng properties schema type, the Thng property key schema allows validation of the value updates to a particular key on the thngs/:thngId/properties/:key endpoint. As a result, the format of this type of schema is also quite similar.
NoteAlthough the data returned by
/thngs/:thngId/properties/:keydoes not include thekeyproperty, it must be included here for this type of schema to correctly apply to a particularkey.
An example allowing only a particular range of integer values allowed is shown below:
Read-only in Thng Properties Schemas
In order to apply a readOnly rule in a Thng property key schema, remember to include the correct $schema namespace value as detailed at the top of this page.
readOnly rule in a Thng property key schema, remember to include the correct $schema namespace value as detailed at the top of this page.Thng Actions Schema
The Thng actions schema type allows read/write filtering by the action's type property. It is applied to newly created actions on a particular Thng via the /thngs/:thngId/actions/:type endpoint.
Like the other schema types, it is applied according to the product ID rules, where the product ID in question is that of the Thng the action is created on.
The following example allows only actions of the _Activated type to be created and read by any Application User associated with it through a role policy:
Read-only in Action Schemas
The readOnly behavior and requirements for action schemas is the same as for Thng properties schemas.
readOnly behavior and requirements for action schemas is the same as for Thng properties schemas.Use of Product IDs
When a resource that may include the product property is involved in schema validation, the behavior depends largely on the particular product ID included in the resource itself, according to the following rule:
The authenticating Application User's role must have a policy associating them with a schema that matches the product of the concerned resource, otherwise the request will be forbidden.
The same is true if no product is specified in the payload resource - only schemas associated with the Application User's role that similarly have no product specified will be applied.
The decision making process for a given request is shown below:
Create a Schema
Create a new schema resource and include the JSON Schema model it will use to validate read/write requests to Platform resources.
Read all Schemas
Read all schemas in an account. The result may be paginated if there are more than 30 items.