Documentation
Feedback
Guides
API Reference

Guides
Data Protection Plus
Working with schemas in the Profile System

Data Protection Plus is in closed beta phase, only available in select regions.

This feature is part of VTEX Shield. If you are already a VTEX customer and want to adopt VTEX Shield for your business, please contact Commercial Support. Additional fees may apply. If you are not yet a customer but are interested in this solution, please complete our contact form.

A JSON Schema defines the structure of data stored in the Profile System. It determines, for example, which fields a profile has and their respective formats. To learn more about JSON Schemas, read the JSON Schema external documentation.

The following endpoints in the Profile System API allow you to interact with the profile schema:

Endpoint nameDescription
GET Get full schemaRetrieves the full profile schema, including default and custom fields.
GET Get custom fieldsRetrieves custom fields in the profile schema.
PUT Create or delete custom fieldsAllows you to customize fields. Learn more about possible customizations in Customizing the profile schema.

Customizing the profile schema

Using the PUT Create or delete custom fields endpoint allows you to customize the schema for the profile entity in the Profile System by:

Make sure you check the applicable Restrictions.

Adding custom fields

Extend the profile schema with custom fields by making a request to PUT Create or delete custom fields, with a request body structured as in the following example.

Request body example


_12
{
_12
"customField1": {
_12
"type": ["string", "null"],
_12
"sensitive": true,
_12
"pii": true
_12
},
_12
"customField2": {
_12
"type": ["string", "null"],
_12
"sensitive": false,
_12
"pii": false
_12
}
_12
}

Every time you add new custom properties or edit existing ones, you must pass all custom properties in the request body, or they will be replaced by those present in the most recent request body used. For example, to edit customField2 later on, you need to include customField1 in the request body even if it has not changed.

Defining PII and sensitive custom fields

Properties marked as Personally Identifiable Information (PII) or sensitive are the ones that are masked by default and must be audited when accessed by a user for legal reasons.

Set the sensitive and/or pii properties as true inside the JSON Schema property definition to determine that they must follow this behavior, as exemplified below.

Request body example - PII and sensitive field


_10
{
_10
"document": {
_10
"type": "string",
_10
"sensitive": true,
_10
"pii": true
_10
}
_10
}

Configuring Unique Alternate Keys

Unique Alternate Keys are properties that must be used to identify the profile, such as email, phone number, and document number. When defined, these properties can be used as the key parameter to retrieve and manage information from the Profile System API.

This property must be structured as a string or as an array. The v-unique-alternate-keys array accepts up to three items, meaning three different keys. Once created, alternate keys cannot be removed.

Example


_10
`v-unique-alternate-keys`: [
_10
{
_10
"name": "email",
_10
"fields": ["email"]
_10
},
_10
{
_10
"name": "phone",
_10
"fields": ["phone"]
_10
}
_10
]

Configuring TTL

The TTL (Time To Live) property is a value expressed in days used to schedule the deletion of the document in the future. When this time expires, the document is automatically deleted.

Example


_10
"documentTTL": 1825,

Deleting custom fields

If you want to delete all custom fields, make a request to PUT Create or delete custom fields with an empty JSON as the request body.

To delete only one or more fields, but not all, make this request including every custom field in the request body except the ones to be removed.

Restrictions

The following restrictions apply when working with custom fields in the profile schema:

  • You cannot use oneOf, anyOf, allOf, or not keywords.
  • The schema is valid per account.
  • You cannot remove or edit required fields. Custom fields cannot be mandatory, so the existing documents will still be compatible with the new schema.
  • Default fields cannot be changed.
  • Custom fields cannot be in v-indexed or in v-unique.
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
See also
Profile System integration
Guides
Data Protection Plus
Guides
Contributors
1
Photo of the contributor
+ 1 contributors
On this page