Skip to main content

Data Types

Below is a list of all the types of object a connector might encounter.

Item​

An Item represents a syncable entity. It has fields of its own as well as relations to other items.

type Item = {
  // The fields and values of the item.
  fields: Record<string, unknown>;

  // The relations of the item.
  relations: Relation[];
};

Relation​

A Relation points to a Collection and describes the shape of the items it contains.

type Relation = {
  // The main identifier of the relation.
  // Can only contain numbers, letters, hyphens and underscores.
  name: string;

  // The relative path at which the relation data is available.
  path: string;

  // Optional list of parameters to be included in the request.
  requestSchema?: { parameters: FieldSchema[] };

  // The publicly visible label of the relation.
  // e.g. "people"
  label: string;

  // Indicates whether or not we can search the collection to narrow down the returned data. Defaults to false.
  searchable?: boolean;

  // The shape of the items in this relation.
  schema: {
    // The publicly visible label of one item in this relation.
    // e.g. "person"
    label: string;

    // Can we create items?
    canCreateItem?: boolean;

    // Can we update items?
    canUpdateItem?: boolean;

    // Can we delete items?
    canDeleteItem?: boolean?

    // Can we add fields to the schema?
    canAddFields?: boolean?

    // The shape of the fields.
    fields: FieldSchema[],

    // The meaning of the relation.
    semantic?: RelationSemantic;

    // Summaries of the relations expected to be found on these items.
    relations?: RelationSummary[];
  },
};

RelationSummary​

A RelationSummary describes the common properties of a relation expected to be found on each item of a relation.

type RelationSummary = {
  /**
   * The main identifier of the relation.
   */
  name: string;
  /**
   * The publicly visible label of the relation.
   */
  label: string;
  /**
   * The semantic of the relation.
   */
  semantic?: RelationSemantic;
  /**
   * The shape of the relation.
   */
  schema: RelationSchema | "__self";
}

FieldSchema​

A FieldSchema describes the shape of a field.

type FieldSchema = {
  // The main identifier of the field.
  // Can only contain numbers, letters, hyphens and underscores.
  name: string;

  // The type of the value field.
  type: FieldValueType;

  // The publicly visible label of the field.
  label: string;

  // Description of the field. For information purposes only.
  info?: string;

  // Category of the field. Used to group fields together when displayed.
  category?: string;

  // Whether the field returns an array. Defaults to false.
  // An array is a non-paginated list of same-type values.
  // For pagination, use a relation instead.
  isArray?: boolean;

  // Whether the field is read only.
  readOnly?: boolean;

  // Whether the field can be empty. Default to true.
  nullable?: boolean;

  // The meaning of the field.
  semantic?: Semantic;

  // The following properties are type specific. Each FieldValueType is free to
  // ask for additional data depending on their needs. While they're flagged as
  // being optional (?) in this shared interface, they could be required for the
  // type to operate properly.

  // When the type is "object", describe its schema.
  fields?: FieldSchema[];

  // When the type is "reference", describes the referenced relation.
  reference?: Relation;

  // When used within a request schema, some fields may decide to provide
  // a list of potential options whose values are considered valid input.
  // As an example, for a field of type "dateRange", such options may
  // include points in time relative to today's date.
  // e.g. "[{ label: "Last 30 days", value: "last_30_days" }, ... ]"
  optionalValues?: { label: string; value: unknown }[];
};

FieldValueType​

A FieldValueType determines the type of an item's value. The type represents a unique scalar value such as a string or an integer. For more complex types, use an Item instead.

enum FieldValueType {
  // A complex field with fields and values of its own. The schema
  // of these fields should be defined in the field's schema.
  // e.g. { name: "foo" }
  OBJECT = 'object',

  // A reference to another existing item. The schema of this object
  // should be defined in the field's schema. The value is represented
  // as an ItemSummary.
  // e.g. { path: "/users/1" }
  REFERENCE = 'reference',

  // A sequence of characters.
  // e.g. "foo"
  STRING = 'string',

  // A valid email address, as described by IETF RFC 5321.
  // e.g. "[email protected]"
  EMAIL = 'email',

  // A valid URL, including the scheme, the domain, and the TLD.
  // e.g. "https://foo.bar/path?a=b
  URL = 'url',

  // Any non-floating point number between -9,007,199,254,740,991 and 9,007,199,254,740,991.
  // e.g. 1234
  INTEGER = 'integer',

  // Any number between -9,007,199,254,740,991 and 9,007,199,254,740,991, including floating points.
  // e.g. 1234.56
  NUMBER = 'number',

  // True or False.
  // e.g. true
  BOOLEAN = 'boolean',

  // Rich-text with Markdown syntax.
  RICH_TEXT_MARKDOWN = 'markdown',

  // Rich-text with HTML syntax.
  RICH_TEXT_HTML = 'html',

  // ISO 8601 date format.
  // e.g. "2023-11-05"
  DATE = 'date',

  // An object containing the start and the end of a date range, in ISO 8601 date format.
  // When one of the two values is left empty, it is considered an open ended range.
  // e.g. "2023-11-01/2023-11-05", or "2023-11-01/"
  DATE_RANGE = 'dateRange',

  // ISO 8601 date and time format.
  // e.g. "2023-11-05T08:15:30.000-05:00".
  DATETIME = 'datetime',

  // An object containing the start and the end of a datetime range, in ISO 8601 date and time format.
  // When one of the two values is left empty, it is considered an open ended range.
  // e.g. "2023-11-01T08:00:00.000-05:00/2023-11-05T08:00:00.000-05:00", or "2023-11-01T08:00:00.000-05:00/"
  DATETIME_RANGE = 'datetimeRange',

  // Any type of binary data.
  BLOB = 'blob',

  // A duration, expressed as a number of seconds.
  // It assumes 24 hours a day, 7 days a week.
  // e.g. 180
  DURATION = 'duration',
}

Semantic​

A Semantic gives meaning to a Field in the Unito platform. A field with a specified semantic is expected to hold a certain type of value that can later be used by the consumers of the spec to better understand what that value means.

enum Semantic {
  // Represents the desired display name of the item.
  // Expected field value to be of type FieldValueType.STRING
  DISPLAY_NAME = 'displayName',

  // Represents the canonical path at which this item is available.
  // Optional. Only useful for items that can have multiple parents.
  // When present, it tells us that the same item exists elsewhere.
  // Expected field value to be of type FieldValueType.STRING
  CANONICAL_PATH = 'canonicalPath',

  // Represents the date at which the item has been created.
  // Required for items to be synced.
  // Expected field value to be of type FieldValueType.DATETIME
  CREATED_AT = 'createdAt',

  // Represents the date at which the item has last been updated.
  // Required for items to be synced.
  // Expected field value to be of type FieldValueType.DATETIME
  UPDATED_AT = 'updatedAt',

  // Represents the Provider URL at which the item is accessible.
  // Expected field value to be of type FieldValueType.STRING
  PROVIDER_URL = 'providerURL',

  // Represents the textual description of the item. Could be used by
  // syncing tools to append additional information, such a link to
  // the other items with which this item is synchronized.
  // Expected field value of type FieldValueType.STRING, RICH_TEXT_HTML, or RICH_TEXT_MARKDOWN
  DESCRIPTION = 'description',

  // Represents a user.
  USER = 'user',

  // Represents the parent of the item.
  // Expected field value to be of type FieldValueType.REFERENCE
  // When present, it tells us the list of parents of the item.
  PARENT = 'parent',
}

Relation Semantic​

A Relation Semantic gives meaning to a Relation in the Unito platform. A relation with a specified semantic is expected to hold a certain type of item that can later be used by the consumers of the spec for specific usage.

enum RelationSemantic {
  // Represents a relation containing items that have the shape of comments.
  // Comments are expected to comply with the following schema;
  //   - Exactly one field with a `DESCRIPTION` semantic
  COMMENTS = 'comments',

  // Represents a relation containing items that have the shape of users.
  // Users are expected to comply with the following schema;
  //   - Exactly one field with a `DISPLAY_NAME` semantic
  //   - Zero or more fields of type `EMAIL`
  USERS = 'users',

  // Represents a relation containing items that have the shape of attachments.
  // Attachments are expected to comply with the following schema;
  //   - Exactly one field of type `BLOB`
  ATTACHMENTS = 'attachments',

  // Represents a relation containing items that have the shape of subtasks.
  // Subtasks are expected to use a self referencing schema through the use of the `__self` keyword.
  SUBTASKS = 'subtasks',
}

OperatorType​

An OperatorType represents an operator used in a filter.

enum OperatorType {
  // Equality operator returns results for which the field is stricly equal to the provided value.
  // e.g. status=active
  EQUAL = '=',

  // Non equality operator returns results for which the field is not stricly equal to the provided value.
  // e.g. role!=admin
  NOT_EQUAL = '!=',

  // Greater than operator returns results for which the field is greater than the provided value.
  // e.g. date>2022-01-01
  GREATER_THAN = '>',

  // Greater than or equal operator returns results for which the field is greater than or equal to provided value.
  // e.g. date>=2022-01-01
  GREATER_THAN_OR_EQUAL = '>=',

  // Lesser than operator returns results for which the field is lesser than the provided value.
  // e.g. date<2022-01-01
  LESSER_THAN = '<',

  // Lesser than or equal operator returns results for which the field is lesser or equal to the provided value.
  // e.g. date<=2022-01-01
  LESSER_THAN_OR_EQUAL = '<=',

  // Include operator returns results for which the provided value is included in the field.
  // e.g. description*=cat
  INCLUDE = '*=',

  // Exclude operator returns results for which the provided value is not included in the field.
  // e.g. description!*=cat
  EXCLUDE = '!*=',

  // Start with operator returns results for which the field starts with the provided value.
  // e.g. name^=A
  START_WITH = '^=',

  // End with operator returns results for which the field ends with the provided value.
  // e.g. name$=Z
  END_WITH = '$=',

  // Is null operator returns results for which the field has a null value.
  // e.g. filter=name!!
  IS_NULL = '!!',

  // Is not null operator returns results for which the field has a non null value.
  // e.g. filter=name!
  IS_NOT_NULL = '!',
}

Collection​

A Collection represents a paginated list of ItemSummary available through a Relation. See Pagination's recipe page for more information.

type Collection = {
  // Contextual information.
  info: {
    // Link to the next page.
    nextPage?: string;
  };

  // List of item summaries.
  data: ItemSummary[];
};

ItemSummary​

An ItemSummary is a constituent of a collection. It links to an item, and can contain additional item information upon request — see the Select and Filters section for more details. Due to the dynamic nature of items, a path can optionally define additional parameters that will help define the items it links to — see the "Dynamic Items" section for more details.

type ItemSummary = {
  // Link to this specific item.
  path: string;

  // Optional list of requested fields and their values.
  fields?: Record<string, unknown>;

  // Optional list of parameters to be included in the request.
  requestSchema?: { parameters: FieldSchema[] };
};

CredentialAccount​

A CredentialAccount describes the provider account associated to a credential (See X-Unito-Credentials).

type CredentialAccount = {
  // The native id of the provider account.
  id: string;

  // The display name of the provider account.
  displayName: string;

  // The emails associated with the provider account.
  emails: string[];

  // Partition can be used to divide data into different buckets.
  partition?: string;
};

WebhookSubscriptionRequestPayload​

A WebhookSubscriptionRequestPayload describes the shape of the request on the "webhook subscription" endpoint.

type WebhookSubscriptionRequestPayload = {
  // The path of the item to which the subscription belongs.
  itemPath: string;

  // The target URL at which events should be sent.
  targetUrl: string;

  // The desired action to be applied to the subscription.
  action: 'start' | 'stop';
};

WebhookParseRequestPayload​

A WebhookParseRequestPayload describes the shape of the request on the "parse webhook" endpoint.

type WebhookParseRequestPayload = {
  // The partition data for which this webhook was received.
  partition?: string;

  // The raw headers sent by the provider.
  headers: Record<string, string>;

  // The raw payload sent by the provider.
  payload: string;

  // The full URL, including query params, on which this webhook was received.
  url: string;
};

WebhookParseResponsePayload​

A WebhookParseResponsePayload describes the shape of the response on the "parse webhook" endpoint.

type WebhookParseResponsePayload = {
  // The path of the item targetted by this event.
  itemPath: string;

  // The date at which the event took place, expressed as an ISO 8601 string.
  // e.g "2023-11-05T08:15:30.000-05:00"
  date: string;

  // The item's relations impacted by this event.
  impactedRelations: {
    // The name of the relation.
    name: string;

    // The list of specific items impacted by this event.
    impactedItems: WebhookParseResponsePayload[];
  }[];
};

WebhookAcknowledgeResponsePayload​

A WebhookAcknowledgeResponsePayload describes the shape of the response on the "acknowledge webhook" endpoint.

type WebhookAcknowledgeResponsePayload = {
  // The status code that should be returned to the provider.
  statusCode: number;

  // The headers that should be returned to the provider.
  headers?: Record<string, string | string[]>;

  // The payload that should be returned to the provider.
  payload?: string;
};

Error​

An error is used when an operation doesn't succeed.

type Error = {
  // Specific error code. Usually the HTTP response code.
  code: string;

  // Raw error message.
  message: string;

  // Free-form key-value store. For logging/debugging purposes.
  details?: Record<string, string>;

  // Original error as returned by the provider.
  originalError?: Error;
};