Schemas

Schemas are used by multiple endpoints to define the structure of profiles, events, and the source and destination schemas for applications, databases, and files.

Below is an example of a profile schema with the properties: email, date_of_birth, and ip_addresses.

{
  "kind": "object",
  "properties": [
    {
      "name": "email",
      "type": {
        "kind": "string",
        "maxLength": 120
      },
      "readOptional": true
    },
    {
      "name": "date_of_birth",
      "type": { "kind": "date" },
      "readOptional": true
    },
    {
      "name": "ip_addresses",
      "type": {
        "kind": "array",
        "elementType": { "kind": "ip" }
      },
      "readOptional": true
    }
  ]
}

Note that a schema has the same representation as an object type.

Data types

Below are the data types and their representations in JSON format:

• string - string
• boolean - boolean
• int - signed integer
• float - floating point number
• decimal - decimal number
• datetime - date and time
• date - date
• time - time
• year - year
• uuid - UUID
• json - JSON
• ip - IP4 or IP6 address
• array - array
• object - object
• map - map

string

Represents UTF-8 encoded string.

{
  "kind": "string"
}

String can be limited by allowed values, a format, or maximum lengths in characters and bytes.

For example a string limited to specific values:

{
  "kind": "string",
  "values": [ "Hearts", "Diamonds", "Clubs", "Spades" ] 
}

If "values" is present:

• it must contain at least one value
• the empty string is allowed
• values must not include the NUL character

For example a string matching a pattern:

{
  "kind": "string",
  "pattern": "\\d+" 
}

Pattern syntax is the same as the Go syntax.

For example a string with a maximum length of 2 characters:

{
  "kind": "string",
  "maxLength": 2 
}

For example a string with a maximum length of 1000 bytes:

{
  "kind": "string",
  "maxByteLength": 1000 
}

You can combine maximum character and bytes lengths. For example a string with a maximum of 20 characters and 25 bytes:

{
  "kind": "string",
  "maxLength": 20,
  "maxByteLength": 25
}

Examples of values are "Everett Hayes", "(555) 123-4567".

boolean

Represents a boolean value.

{
  "kind": "boolean"
}

Values are true and false.

int

An integer with a specific bit size. The size can be 8, 16, 24, 32, or 64

{
  "kind": "int",
  "bitSize": 32
}

You can limit integers to a minimum and maximum range, for example the following defines an 8-bit integer with range [-20, 20]:

{
  "kind": "int",
  "bitSize": 8,
  "minimum": -20,
  "maximum": 20
}

You can also mark the integer as unsigned, which limits it to non-negative values. The example below defines a 32-bit unsigned integer:

{
  "kind": "int",
  "bitSize": 32,
  "unsigned": true
}

Examples of values are 12, -470, 7308561.

float

A floating-point number with a specific bit size, according to the IEEE 754 standard. The available sizes are 32 or 64 bits.

{
  "kind": "float",
  "bitSize": 64
}

Floats can have a minimum and maximum value and exclude special values such as NaN, Infinity, and -Infinity. For example a 32-bit float with range [-20.5, 8]:

{
  "kind": "float",
  "bitSize": 32,
  "minimum": -20.5,
  "maximum": 8
}

For example a 64-bit float with range [-0, 56.481782]:

{
  "kind": "float",
  "bitSize": 64,
  "minimum": 0,
  "maximum": 56.481782
}

For example, a 64-bit float excluding special values such as NaN, Infinity, and -Infinity:

{
  "kind": "float",
  "bitSize": 64,
  "real": true
}

Examples of values are 1.6892, -0.002516, 441.015, "NaN", "Infinity", "-Infinity".

decimal

A decimal number with a precision and a scale, where precision ranges from 1 to 76, scale from 0 to 37, and scale is less than or equal to precision.

{
  "kind": "decimal",
  "precision": 10,
  "scale": 2
}

Decimals can also have a minimum and maximum value range, for example the following is a decimal with precision 5 and scale 2, range [-10.5, 8.25].

{
  "kind": "decimal",
  "precision": 5,
  "scale": 2,
  "minimum": -10.5,
  "maximum": 8.25
}

Examples of values are 5.12, 893, 1258.068.

datetime

Represents a date and time within the range of years [1, 9999] with nanosecond precision and UTC timezone.

{
  "kind": "datetime"
}

Values are presented in ISO 8601 format. When passing a datetime value to the API endpoints, you can use any ISO 8601 format with any timezone; it will be automatically converted to UTC.

Examples include "2024-12-23T09:05:47Z", "2025-02-11T16:19:14.3392Z", "1975-12-05T09:55:12.048522068Z".

date

Represents a date within the range of years [1, 9999].

{
  "kind": "date"
}

Values are presented in ISO 8601 format. When passing a date value to the API endpoints, you can use the ISO 8601 format yyyy-mm-dd.

Examples of values are "2025-02-11", "1975-12-05".

time

Represents a time of day with nanosecond precision and no timezone. Values are presented in ISO 8601 format.

{
  "kind": "time"
}

Values are presented in ISO 8601 format. When passing a time value to the API endpoints, you can use the ISO 8601 formats HH:mm:ss and HH:mm:ss.sssssssss, with up to 9 decimal digits.

Examples of values are "16:19:14", "20:06:58.921", "09:55:12.048522068".

year

Represents a year within the range [1, 9999].

{
  "kind": "year"
}

Examples of values are 2025, 1975.

uuid

Represents a UUID.

{
  "kind": "uuid"
}

Examples of values are "ae3a0552-eff9-4456-8a2e-b94c64d03359", "bbe0eda7-b672-4cfb-9285-1128681e00cd".

json

Represents a JSON value.

{
  "kind": "json"
}

Examples of values are "null", "5" "\"hello"\", "{\"name\":\"John\"}", "true", "[34,12,0,6]".

ip

Represents an IP4 or IP6 address.

{
  "kind": "ip"
}

Examples of values are "192.0.2.1", "2001:db8::1".

array

Represents an array of elements of the same type. For example an array of string:

{
  "kind": "array",
  "elementType": { "kind": "string" }
}

Arrays can be limited in the minimum and maximum number of elements. For example an array of 32-bit unsigned integers with at least 1 element:

{
  "kind": "array",
  "elementType": {
    "kind": "int",
    "bitSize": 32
  },
  "minElements": 1
}

For example an array with a maximum of 10 decimal values:

{
  "kind": "array",
  "elementType": {
    "kind": "decimal",
    "precision": 10,
    "scale": 2
  },
  "maxElements": 10
}

For example an array with 5 to 15 string values.

{
  "kind": "array",
  "elementType": { "kind": "string" },
  "minElements": 5,
  "maxElements": 15
}

Arrays can also be constrained to have unique values for their elements, except for arrays of json, array, map, and object.

For example an array of 64-bit unsigned integers with unique values:

{
  "kind": "array",
  "elementType": {
    "kind": "int",
    "bitSize": 64,
    "unsigned": true
  },
  "uniqueElements": true
}

For example an array of UUIDs with unique values:

{
  "kind": "array",
  "elementType": { "kind": "uuid" },
  "uniqueElements": true
}

Examples of values are [8498, 204, 7531], [{"name": "John"}, {"name": "Emily"}].

object

Represents an object with specified properties. For example:

{
  "kind": "object",
  "properties": [
    {
      "name": "first_name",
      "type": {
        "kind": "string",
        "maxLength": 30
      }
    },
    {
      "name": "last_name",
      "type": {
        "kind": "string",
        "maxLength": 30
      }
    },
    {
      "name": "birth_date",
      "type": { "kind": "date" }
    }
  ]
}

Examples of values are {"first_name": "John", "last_name": "Hollis", "age": 34, active: true}, {"city": "New York", "street": "5th Avenue", "zip": 10001}.

Properties

An object property has the following keys:

Key	Type	Required	Default	Description
name	String	✓		The name of the property. It must start with a letter [A-Za-z_] and can only contain alphanumeric characters and underscores [A-Za-z0-9_] after that.
prefilled	Number		""	This is the value that appears pre-filled when a destination pipeline is configured on events. It suggests the expression linked to the property, so it doesn't have to be entered manually. It must not include the NUL character.
type	Object	✓		The type of the property, which can be any data type.
createRequired	Boolean		false	Indicates whether the property is required during creation, i.e., whether a value for the property is required at the time of creation.
updateRequired	Boolean		false	Indicates whether the property is required for updating, i.e., whether a value for the property is mandatory when updating an existing record.
readOptional	Boolean		false	Indicates whether the property may not be present when reading, i.e., whether the property is optional and may not be included in the data when retrieved.
nullable	Boolean		false	Indicates whether the property can be null.
description	String		""	A description providing additional information about the property's usage. It must not include the NUL character.

map

Represents a map with string keys and values of the same type. For example a map of string:

{
  "kind": "map",
  "elementType": { "kind": "string" }
}

For example a map with 64-bit signed integers as values:

{
  "kind": "map",
  "elementType": {
    "kind": "int",
    "bitSize": 64
  }
}

For example a map with arrays of strings as values:

{
  "kind": "map",
  "elementType": {
    "kind": "array",
    "elementType": { "kind": "string" }
  }
}

Examples of values are {"score": "6205", "player": "Everett Hayes"}, {"width": 1920, "height": 1080}.