Customer Database · Schema

Customer Identity Link

An assertion that an external identifier belongs to a customer, carrying the method and confidence that produced it. These are the edges of the identity graph. No open standard models identity resolution, which is why identity graphs are proprietary and do not port between vendors; this schema is a neutral shape for describing one.

AccountConsentContactsCRMCustomer DataCustomer Data PlatformCustomersDatabaseGDPRIdentityProfilesSchema

Properties

Name	Type	Description
id	string
customerId	string
namespace	string	The system or identifier space the value belongs to. Without a namespace an identifier is not resolvable.
identifier	string	The value itself. Hash rather than store raw identifiers where the namespace implies it.
method	string	How the link was established. deterministic = exact agreement on a strong key; probabilistic = weighted similarity across weak attributes; declared = the customer told us.
confidence	number	Match score. REQUIRED and meaningful for probabilistic links; meaningless for deterministic ones, where its presence usually signals a modeling error.
matchedOn	array	Which attributes contributed to the match. Makes a probabilistic link reviewable instead of opaque.
linkedAt	string
expiresAt	string	Pseudonymous identifiers decay. A cookie link that never expires overstates what is known.
active	boolean	Set false to break a link without losing the record that it was once asserted.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/customer-database/refs/heads/main/json-schema/customer-identity-link.json",
  "title": "Customer Identity Link",
  "description": "An assertion that an external identifier belongs to a customer, carrying the method and confidence that produced it. These are the edges of the identity graph. No open standard models identity resolution, which is why identity graphs are proprietary and do not port between vendors; this schema is a neutral shape for describing one.",
  "type": "object",
  "required": ["namespace", "identifier", "method"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string" },
    "customerId": { "type": "string" },
    "namespace": {
      "type": "string",
      "description": "The system or identifier space the value belongs to. Without a namespace an identifier is not resolvable.",
      "examples": ["crm", "cookie", "device-idfa", "device-gaid", "email-sha256", "phone-e164", "loyalty", "billing"]
    },
    "identifier": { "type": "string", "description": "The value itself. Hash rather than store raw identifiers where the namespace implies it." },
    "method": {
      "type": "string",
      "enum": ["deterministic", "probabilistic", "declared"],
      "description": "How the link was established. deterministic = exact agreement on a strong key; probabilistic = weighted similarity across weak attributes; declared = the customer told us."
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Match score. REQUIRED and meaningful for probabilistic links; meaningless for deterministic ones, where its presence usually signals a modeling error."
    },
    "matchedOn": {
      "type": "array",
      "description": "Which attributes contributed to the match. Makes a probabilistic link reviewable instead of opaque.",
      "items": { "type": "string" }
    },
    "linkedAt": { "type": "string", "format": "date-time" },
    "expiresAt": { "type": "string", "format": "date-time", "description": "Pseudonymous identifiers decay. A cookie link that never expires overstates what is known." },
    "active": { "type": "boolean", "default": true, "description": "Set false to break a link without losing the record that it was once asserted." }
  }
}