Resources

A specific instance of a given resource type, is called a "resource". A resource instance is recongized by it's identity fields (id and type). In Clarify, all resources extend the same Base resource.

Resource schemas

Resource schemas describe all available fields or properties for a a specific resource type. These fields are again exposed by resource views for either read or write purposes. Any operation relying on field paths, such as a resource resource query, will be using the schema more directly in order to validate the query.

Field	Categories	Description
field-name type-expression	field-category, query-categories...	Short description.

Each field can have exactly one field-category, and 0-2 query categories. When two query categories are present, then the final category is "sort".

Valid field-category values are:

• identifier: fields (type and id). This field set is the same for all resources. Identify fields can never be changed for any resource.
• meta: Non-standard fields such as annotations, as well as a set of generated read-only fields. This field set is the same for all resources in Clarify.
• attribute: Fields that doesn't directly reference other resources.
• relationship: Fields that reference other resources by referring to their identifier fields.

Valid query-category values are:

• comparable: Allows equality based comparisons against the stored values.
• ordered: Allows comparable as well as order based comparisons against the stored values.
• string: Allows comparable, ordered as well as text matching comparisons.
• sort: Declares the field as sortable.

Field paths

A field path, is the path of a field joined with dots (.). The field-category (used in select view projections), is not considered a part of the field path. Be aware of special semantics regarding set types such as the Labels field, or relationship fields.

Example

// Resource selection with field paths as comments.
{
  "type": "signals",            // "type"
  "id": "capggajtaf7dgmpf7g3g", // "id"
  "meta": {
    "annotations": {
      "docs-clarify-io/example/development": "arrested"  // "annotations.docs-clarify-io/example/development"
    },
    ...
    "createdAt": "2022-06-22T12:16:42.193Z", // "createdAt"
    "updatedAt": "2022-06-22T12:18:34.423Z"  // "updatedAt"
  },
  "attributes": {
    "name": "Building status", // "name"
    ...
    "labels": {
      "data-source": [
        "environmental sensors"  // query path: "labels.data-source"
      ],
      "location": [
        "banana stand",  // query path: "labels.location"
        "pier"           // query path: "labels.location"
      ]
    }
  },
  "relationships": {
    "item": {
      "data": {
        "type": "items",
        "id": "capggebtaf7dgmpf7g4g" // query path: "item"
      }
    }
  }
}

Resource view

A resource view allow access to certain resource fields, either for read or write purposes. Read more on the views page.

Resource types

A resource type is a group of resources that hold the same type property. Within Clarify, that all resource type names are plural. I.e. the type property if an item instance is "items" not "item".

Resources that are of the same type, must comply to a given schema. Note that this schema is not used directly for payload validation as all resource access is done through views.

Base resource

The identity and meta fiels are the same for all resources:

Field	Categories	Description
id string	identifier, ordered, sort	A unique ID generated by the server. Queries may be considered invalid if trying to use an invalid ID format according to the target resource type.
type string	identifier	A string identifying the plural name of the resource type.
createdAt Date/Time	meta, ordered, sort	A timestamp for when the resource was created.
updatedAt Date/Time	meta, ordered, sort	A timestamp for when the resource was last updated.
attributesHash string	meta	A SHA1 hash generated from all attribute fields. The hash is not stored, and can not be queried.
relationshipsHash string	meta	A SHA1 hash generated from all relationship fields. The hash is not stored, and can not be queried.
annotations Annotations	meta, text	A key-value store where integrations can store programmatic meta-data about the resource instance. Filtering is done one member fields.

Integrations

ID regex: "^[a-v0-9]{20}$"

The integrations resource type is not currently made available for selection, but is documented as other resources contain references to it. An integration is an object that represents your code. Integrations are used to manage credentials and control access to the different API namespaces in the Clarify API.

Items

ID regex: "^[a-v0-9]{20}$"

The items resource type hold the sanitized meta-data set for a time-series instance and allows reading associated data within the scope of a single organization. The data can come from different sources, such as signals, data sets or other items. This relationship details is currently not exposed through the API, except signals that are exposed through items, include a link to the item that expose it.

Items extends the Base resource with the following fields:

Field	Categories	Description
name string(len:1-128)	attribute, text, sort	A human-readable name for the resource.
description string(len:0-1000)	attribute, text	A free-form description of the resource.
labels Labels	attribute, text	A map of custom classification attributes. Filtering is done on label keys (labels.<key>).
sourceType string(enum)	attribute, comparable	Classification of the data source. The value must be "aggregation", "measurement" or "prediction".
valueType string(enum)	attribute, comparable	How to interpret time-series data points. The value must be "enum" or "numeric".
engUnit string	attribute, text, sort	Engineering unit for time-series data in numeric representations.
enumValues map(string => string(len:1-128))	attribute, text, sort	Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999.
sampleInterval Fixed Duration, null	attribute, ordered, sort	The expected distance between data points.
gapDetection Fixed Duration, null	attribute, ordered, sort	The maximum distance between two data-points before considering it to be a gap.

Signals

ID regex: "^[a-v0-9]{20}$"

Signals is a resource type that holds meta-data associated with an integration time-series input. Integrations write time-series data or meta-data by referring to a signals input attribute.

Note that signals describe time-series input only. Thus to retrieve time-series data written to a signal, you must first expose the signal as an Item.

Signals extends the Base resource with the following fields:

Field	Categories	Description
name string(len:1-128)	attribute, text, sort	A human-readable name for the resource.
description string(len:0-1000)	attribute, text	A free-form description of the resource.
labels Labels	attribute, text	A map of custom classification attributes. Filtering is done on label keys (labels.<key>).
sourceType string(enum)	attribute, comparable	Classification of the data source. The value must be "aggregation", "measurement" or "prediction".
valueType string(enum)	attribute, comparable	How to interpret time-series data points. The value must be "enum" or "numeric".
engUnit string	attribute, text, sort	Engineering unit for time-series data in numeric representations.
enumValues map(string => string(len:1-128))	attribute, text, sort	Map of numeric values to display text in enum representations. The key must represent an integer in range 0-9999.
sampleInterval Fixed Duration, null	attribute, ordered, sort	The expected distance between data points.
gapDetection Fixed Duration, null	attribute, ordered, sort	The maximum distance between two data-points before considering it to be a gap.
input string	attribute, comparable	A unique key used to reference signals within an integration namespace. Values must satisfy regular expression "^[a-zA-Z0-9-_:.#+/]{1,128}$".
integration string(Integration ID)	relationship	The parent integration for the signal. Current methods force filtering signals on this field.
item string(Item ID),null	relationship, ordered	Link to an item that expose the signal within the organization or null.