# Data

> Data collections and tracked interactions, and the payloads between a component and the data API.

> Esta página ainda não tem tradução para o português; este é o texto em inglês. (This page is not translated yet: the English text follows.)

> Generated from the contract schemas of `@taggor/contract` 1.10.0 by `pnpm docs:contract`; do not edit.

A component that collects data declares it under `data` in the manifest. At run time it talks to the platform with the payloads of the data API, listed after the declarations.

## DataDeclaration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `collections` | map to [CollectionDeclaration](#collectiondeclaration) (keys: [MemberName](../manifest/#named-types)), at most 10 entries | no | The collections the component submits to, by name. Each is stored per site and belongs to the customer. |
| `track` | map to [TrackEventDeclaration](#trackeventdeclaration) (keys: [MemberName](../manifest/#named-types)), at most 30 entries | no | The interactions the component may report, by name. They carry no personal data. |
| `personal` | `boolean` | no | True when the collections hold personal data: every submit then carries the visitor's consent. Defaults to false. |
| `privacyPolicyUrl` | [PropName](../manifest/#named-types) | no | Name of the prop of type "url" that links the privacy policy, set per site. Required when personal is true. |

## CollectionDeclaration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `fields` | map to [CollectionField](#collectionfield) (keys: [SnakeName](../manifest/#named-types)), 1 to 50 entries | yes | The fields of one submission, by name. A field is a scalar or an array of scalars. |
| `required` | array of [SnakeName](../manifest/#named-types), 1 to 50 items, no repeats | no | The names of the fields every submission must carry. Each is one of `fields`. |
| `visibility` | one of `"private"`, `"public"` | no | Defaults to "private". |

## CollectionField

Exactly one of:

- [StringValueSchema](../props/#stringvalueschema)
- [NumberValueSchema](../props/#numbervalueschema)
- [BooleanValueSchema](../props/#booleanvalueschema)
- [EnumValueSchema](../props/#enumvalueschema)
- type `"array"`, fields below

### CollectionField, type "array"

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | the constant `"array"` | yes | The field type: `string`, `number`, `boolean`, `enum` or `array`. |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `items` | [ScalarValueSchema](../props/#scalarvalueschema) | yes | The schema of every item of an array field; items are scalars. |
| `minItems` | `integer`, 0 to 1000 | no | Fewest items accepted. |
| `maxItems` | `integer`, 1 to 1000 | no | Defaults to 1000. |

## TrackEventDeclaration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string`, 1 to 300 characters, a fixed pattern (see the JSON Schema) | no | What this member is for; shown in docs, the portal and to agents. |
| `props` | map to [TrackProp](#trackprop) (keys: [SnakeName](../manifest/#named-types)), at most 8 entries | no | Extra values reported with the interaction, by name. Only numbers, booleans and enums, so no free text and no personal data. |

## TrackProp

Exactly one of:

- [NumberValueSchema](../props/#numbervalueschema)
- [BooleanValueSchema](../props/#booleanvalueschema)
- [EnumValueSchema](../props/#enumvalueschema)

## SubmitRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | map to any JSON value (keys: `string`, at most 40 characters), at most 50 entries | yes | The submitted values by field name. The edge checks them against the collection the manifest declares and drops undeclared fields. |
| `idempotency_key` | `string`, 16 to 64 characters, pattern `^[A-Za-z0-9_-]+$` | yes | A key the client invents for this submission, so that a retry stores it once. |
| `turnstile_token` | `string`, 1 to 2048 characters | no | The Cloudflare Turnstile answer, when the site requires one. |
| `_hp` | `string`, at most 256 characters | no | The honeypot: a field humans leave empty. A filled value marks the submission `suspect` (it is kept, never dropped). |
| `_t` | `integer`, 0 to 9007199254740991 | no | Milliseconds between rendering the form and submitting it; a submission that is too fast is dropped as a bot's. |
| `consent` | object | no | The visitor's consent proof. Required for a component whose manifest sets `data.personal`. |
| `consent.given` | the constant `true` | yes | Always `true`: the visitor ticked the consent box. |
| `consent.text_hash` | `string`, 64 to 64 characters, pattern `^[0-9a-f]+$` | yes | SHA-256, in lowercase hex, of the exact consent text the visitor accepted. |
| `consent.locale` | `string`, at most 35 characters, pattern `^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$` | yes | The language tag the consent text was shown in. |

## SubmitAccepted

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | the constant `"accepted"` | yes | Always `accepted`: the submission was queued; it is stored a moment later. |

## ReadRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer`, 1 to 100 | no | Defaults to 20. |
| `cursor` | `string`, 1 to 512 characters, pattern `^[A-Za-z0-9_-]+$` | no | The opaque `next_cursor` of the previous page; leave it out for the first page. |

## ReadResponse

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of object, at most 100 items | yes | One page of submissions, newest first. |
| `data[].id` | `string`, pattern `^sub_[0-9A-HJKMNP-TV-Z]{26}$` | yes | The submission's public id (`sub_` and a ULID). |
| `data[].created_at` | `string`, a fixed pattern (see the JSON Schema) | yes | When the submission was stored, as an ISO 8601 date and time. |
| `data[].data` | map to any JSON value (keys: `string`, at most 40 characters), at most 50 entries | yes | The stored values by field name. |
| `next_cursor` | `string`, 1 to 512 characters, pattern `^[A-Za-z0-9_-]+$` or `null` | yes | Pass it as `cursor` to get the next page; `null` on the last page. |
| `has_more` | `boolean` | yes | True when there is another page after this one. |

## TrackRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `component` | [TagName](#named-types-of-the-data-api) | yes | The tag of the component that reports the interaction. |
| `name` | [MemberName](#named-types-of-the-data-api) | yes | The name of an interaction declared under `data.track`. |
| `props` | map to `number` or `boolean` or [EnumValue](#named-types-of-the-data-api) (keys: [SnakeName](#named-types-of-the-data-api)), at most 8 entries | no | The values declared for the interaction, by name. |

## DataError

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | one of `"validation_failed"`, `"collection_not_found"`, `"read_not_allowed"`, `"event_not_declared"`, `"origin_not_allowed"`, `"rate_limited"`, `"captcha_failed"`, `"payload_too_large"`, `"consent_required"`, `"daily_cap_reached"` | yes | Which problem it is. The SDK turns each code into a translated message. |
| `message` | `string`, at most 500 characters | yes | An English explanation, for logs. Not meant for the visitor. |
| `fields` | array of object, at most 50 items | no | The problems per field, for `validation_failed`. |
| `fields[].path` | `string`, at most 160 characters | yes | The field the problem is about. |
| `fields[].message` | `string`, at most 500 characters | yes | What is wrong with that field. |

## Named types of the data API

| Name | Type | Limits |
| --- | --- | --- |
| `TagName` | `string` | 1 to 64 characters, a fixed pattern (see the JSON Schema) |
| `MemberName` | `string` | 1 to 40 characters, pattern `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$` |
| `SnakeName` | `string` | 1 to 40 characters, a fixed pattern (see the JSON Schema) |
| `EnumValue` | `string` | 1 to 64 characters, pattern `^[^\u0000-\u001f\u007f]+$` |