Profile Format

The Profile format is designed to:

  • Be flexible for insertion of data from different sources and in different formats
  • Work well with behavioral data
  • Simple to parse and use in any client
  • Structured enough to be able to query it in a way that is not specific for each implementation

 
Data on different levels

The profile doesn't make any particular assumptions about what data is added to it, but any data must be added into one of these "levels":

  • Profile attributes: data related to the profile (think of it as "user is something") in key/value format. Example: age, email address, current customer status, number of purchases
  • Event data: an event that the profile has initiated, meaning it has a timestamp ("createdAt"), something identifying the type of the event ("definitionId") and an arbitrary list of values ("data," see definition for values below)
  • Session data: every event must belong to a session, and a session must have at least one event. So in one sense a session is just a container of events, but it can also have data of its own, "session data". Good candidates for session data is data that doesn't vary inside a session, such as the device the user connected from in the session or the geographical location

Grouping per "app" and section

"Apps" or "collect apps" are the channels such as "web", "android", "salesforce crm", "facebook".

Within each app there can by any number of sections, which is just a logical separation of data within an app. For instance for "web" the section is typically the website, so that data from multiple websites can be added to the profile while keeping the possibility to separate the data from them.

Each piece of data (session and therefore event, and user data) must belong to an app and a section


About data values

A data value (user data, session data, event data) can be of any JSON type (http://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example) i.e. number, string, boolean, array or an object.


About sessions

A session is a container of events, with the possibility to add some data to the session (session-level data, see above). It is up to the client to decide what constitute a session. Clients should either use explicit definitions of when a session starts/ends (for instance for an app, reopening the app, for a physical store, leaving the store and coming back), or a time-based approach (if no activity within 30 minutes, start a new session), in which case 30 minutes is the standard inactivity time that should lead to a new session.

Detailed spec

Profile JSON structure
{
   "id":"<profileId>",
   "version":"1.0",
   "createdAt":<timestamp milliseconds>,
   "modifiedAt":<timestamp milliseconds>, // deprecated!
   "sessions":[
	{
            "id":"<sessionId>",
            "createdAt":<timestamp milliseconds>,
            "modifiedAt":<timestamp milliseconds>, // deprecated!
            "collectApp":"<collect app name>",
            "section":"<section name>",
            "data":{
				"key":"value"
	            "countryCode":0,
                "countryName":"<a country>",
                "region":"<a region>",
                "city":"<a city>",
                "postalCode":null,
                "latitude":0.0,
                "longitude":0.0,
                "dmaCode":0,
                "areaCode":0,
                "metroCode":0
            },
            "events":[
               {
                  "id":"<eventId>",
                  "createdAt":<Timestamp milliseconds>,
                  "definitionId":"<definitionId>",
                  "data":{
					"key":"value"
                  }
               }
            ]
         }
   ],
   "attributes":[
	  {
        "collectApp": "<collect app name>",
        "section": "<section name>",
        "modifiedAt": <timestamp milliseconds>, // deprecated!
        "data": {
          "key": "value"
        }
      }
   ]
}

JSON Schema 

JSON Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Incoming Profile Schema",
  "description": "Documentation and schema for incoming profile",
  "type": "object",
  "definitions": {
    "idString": {
      "title": "Id String",
      "description": "Definition of an id string",
      "type": "string",
      "minLength": 1,
      "pattern": "^\\S+$"
    },
    "profileId": {
      "title": "Profile Id",
      "description": "The profile id",
      "allOf": [
        {"$ref": "#/definitions/idString"},
        {"maxLength": 128}
      ]
    },
    "creationTimestamp": {
      "title": "Creation timestamp",
      "description": "Definition of a creation timestamp",
      "type": "number",
      "multipleOf": 1,
      "minimum": 0
    }
  },
  "properties": {
    "id": {
      "title": "Profile Id",
      "description": "The profile id",
      "$ref": "#/definitions/profileId"
    },
    "sessions": {
      "title": "Sessions",
      "description": "Sessions array",
      "type": "array",
      "minItems": 0,
      "items": {
        "title": "Session",
        "description": "Session object",
        "type": "object",
        "properties": {
          "id": {
            "title": "Session id",
            "description": "Unique id for session in this profile. If id doesn't exist in the session array for the current section and collect app, a new session is created",
            "$ref": "#/definitions/idString"
          },
          "createdAt": {
            "title": "Created at",
            "description": "Creation time of session in milliseconds since epoch. Default is current timestamp. Cannot be overriden once set",
            "$ref": "#/definitions/creationTimestamp"
          },
          "section": {
            "title": "Session section",
            "description": "The section used for this session",
            "$ref": "#/definitions/idString"
          },
          "data": {
            "title": "Session data",
            "description": "Session data provided with this request",
            "type": "object"
          },
          "events": {
            "title": "Events",
            "description": "Array containing events for this session",
            "type": "array",
            "minItems": 0,
            "items": {
              "title": "Event",
              "description": "The event object",
              "type": "object",
              "properties": {
                "id": {
                  "title": "Event id",
                  "description": "Unique id for the event in this session",
                  "$ref": "#/definitions/idString"
                },
                "createdAt": {
                  "title": "Created at",
                  "description": "Creation in milliseconds since epoch. Default is current timestamp. Cannot be overriden once set",
                  "$ref": "#/definitions/creationTimestamp"
                },
                "definitionId": {
                  "title": "Event Definition id",
                  "description": "The defined type of event. Cannot be overriden once set",
                  "$ref": "#/definitions/idString"
                },
                "data": {
                  "title": "Event data",
                  "description": "The attached event data",
                  "type": "object"
                }
              },
              "required": ["id", "definitionId"]
            }
          }
        },
        "required": ["id", "section"]
      }
    },
    "attributes": {
      "title": "Attributes",
      "description": "Attributes added or modified",
      "type": "array",
      "minItems": 0,
      "items": {
        "title": "Attribute",
        "description": "Attribute objects",
        "type": "object",
        "properties": {
          "section": {
            "title": "Attribute section",
            "description": "Section for this attribute",
            "$ref": "#/definitions/idString"
          },
          "data": {
            "title": "Attribute data",
            "description": "attribute data",
            "type": "object"
          }
        },
        "required": ["section"]
      }
    },
    "mergedProfiles": {
      "title": "Merged profiles",
      "description": "Provied a list of profiles which should be merged into this profile",
      "type": "array",
      "items": {
        "$ref": "#/definitions/profileId"
      },
      "maxItems": 200
    }
  },
  "required": ["id"]
}