Customize the schema

Every attribute in the SCV schema is customizable.

However, while you can add and modify attributes, some system attributes are always present to ensure the integrity and functionality of the schema.

For example, attributes such as

  • firstName;

  • lastName;

  • countryCode;

  • gpa;

  • interests;

  • profileImageURL; and

  • hasRequestedFinancialAid

(as shown in the sample schema) can be modified or extended with additional attributes.

Supported attribute types

The schema supports the following data types to help store information about customers:

String

Textual data.

Number

Numeric data, including floating-point numbers.

Integer

Whole numbers.

Boolean

True/false values.

Array

A list of values, where each value can be of the types listed.

System default property x-scv-source

The system default properties are predefined attributes integral to the SCV schema. The schema can reference other custom attributes to share the same value. The following default properties are available:

x-scv-source

The source identifier for an attribute.

$customerid

The unique identifier for a customer.

$createDatetime

The timestamp when the customer record was created.

$updatedDatetime

The timestamp when the customer record was last updated.

$verifiedEmail

The verified email of the customer.

$username

A username of the customer.

$tertiaryid

Any tertiary ID for the customer, such as a student ID or staff ID.

Example 1. x-scv-source

By assigning the x-scv-source value to customer.$customerid, a user-defined customerid is mapped to the value from the system property $customerid

"customerid": {
  "title": "Customer ID",
  "description": "The SCV customer id for the data, this value can not be set by the user.",
  "x-scv-source": "customer.$customerid"
}

Searchable property x-scv-searchable

Assign the x-scv-searchable property in the attribute definition to make an attribute searchable.

Example 2. x-scv-searchable
"firstName": {
  "title": "First name",
  "description": "The first name of the user.",
  "type": "string",
  "example": "Bilbo",
  "x-scv-searchable": "firstName"
}

Customers can be searched by attributes $customerid, $verifiedEmail, $username, and $tertiaryid by default. In the case of searching by a customer’s name, this is the only time we need to be explicitly told in the schema which attribute represents a first name and last name to make those attributes searchable.

The attribute that represents a customer’s first name should be marked with x-scv-searchable: firstName`, and the attribute that represents a customer’s last name should be marked with x-scv-searchable: lastName.

Attribute level permissions property x-scv-permissions

The Single Customer View (SCV) schema includes attribute-level security permissions, enabling fine-grained access control over customer data.

This field ensures that attributes are properly validated and that the SCV API consistently enforces rules to manage attribute viewing and editing.

This property allows CDP users to:

  • Use the scv:customer role to control attribute permissions (read, or read and write) for a customer’s signed-in experience.

  • Ensure security and compliance by restricting access to sensitive attributes.

Example 3. x-scv-permissions
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",

  "x-scv-permissions": {
    "scv:customer": {
      "scv:property:username": ["read"],
      "scv:property:phoneNo": ["read", "write"],
      "scv:property:gpa": []
    }
  },
  "properties": {
    ...
  }
}

Validation rules

Required role

The x-scv-permissions field must include the scv:customer role even if it is empty.

"x-scv-permissions": {
   "scv:customer": []
}
Attribute existence

All attributes listed in x-scv-permissions must exist in the properties list.

You cannot configure permissions for an attribute that does not exist.

Naming and structure

Children attributes of the scv:customer role must start with scv:property.

Example of an invalid name:

"scv:firstName": []

Example of a valid name:

"scv:property:firstName": []
Permission dependency

If an attribute has write permission, it must also have read permission.

Example of an invalid configuration:

"scv:property:firstName": ["write"]

Example of a valid configuration:

"scv:property:firstName": ["read", "write"]
Allowed actions for permissions

The permissions array can only contain read, or read and write. Other actions, like view or delete, are prohibited.

System attribute restrictions

Certain system-generated attributes have inherent restrictions and cannot be edited or read by a customer:

Attributes that cannot be readable by a customer
  • customer.$customerid

Attributes that cannot be writable by a customer
  • customer.$customerid

  • customer.$verifiedEmail

  • customer.$username

  • customer.$tertiaryid

  • customer.$createdDatetime

  • customer.$updatedDatetime

  • customer.$consented

  • customer.$consentDocumentVersion

Deploying schema changes

To deploy schema changes, use the DXP CLI. Read the DXP CLI documentation for detailed instructions on the deploy command.