Skip to main content
Version: 1.1beta2

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.

FieldCategoriesDescription
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:

FieldCategoriesDescription
id
string
identifier, ordered, sortA 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
identifierA string identifying the plural name of the resource type.
createdAt
Date/Time
meta, ordered, sortA timestamp for when the resource was created.
updatedAt
Date/Time
meta, ordered, sortA timestamp for when the resource was last updated.
attributesHash
string
metaA SHA1 hash generated from all attribute fields. The hash is not stored, and can not be queried.
relationshipsHash
string
metaA SHA1 hash generated from all relationship fields. The hash is not stored, and can not be queried.
annotations
Annotations
meta, textA 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:

FieldCategoriesDescription
name
string(len:1-128)
attribute, text, sortA human-readable name for the resource.
description
string(len:0-1000)
attribute, textA free-form description of the resource.
labels
Labels
attribute, textA map of custom classification attributes. Filtering is done on label keys (labels.<key>).
sourceType
string(enum)
attribute, comparableClassification of the data source. The value must be "aggregation", "measurement" or "prediction".
valueType
string(enum)
attribute, comparableHow to interpret time-series data points. The value must be "enum" or "numeric".
engUnit
string
attribute, text, sortEngineering unit for time-series data in numeric representations.
enumValues
map(string => string(len:1-128))
attribute, text, sortMap 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, sortThe expected distance between data points.
gapDetection
Fixed Duration, null
attribute, ordered, sortThe 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:

FieldCategoriesDescription
name
string(len:1-128)
attribute, text, sortA human-readable name for the resource.
description
string(len:0-1000)
attribute, textA free-form description of the resource.
labels
Labels
attribute, textA map of custom classification attributes. Filtering is done on label keys (labels.<key>).
sourceType
string(enum)
attribute, comparableClassification of the data source. The value must be "aggregation", "measurement" or "prediction".
valueType
string(enum)
attribute, comparableHow to interpret time-series data points. The value must be "enum" or "numeric".
engUnit
string
attribute, text, sortEngineering unit for time-series data in numeric representations.
enumValues
map(string => string(len:1-128))
attribute, text, sortMap 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, sortThe expected distance between data points.
gapDetection
Fixed Duration, null
attribute, ordered, sortThe maximum distance between two data-points before considering it to be a gap.
input
string
attribute, comparableA 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)
relationshipThe parent integration for the signal. Current methods force filtering signals on this field.
item
string(Item ID),null
relationship, orderedLink to an item that expose the signal within the organization or null.