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 name | Description |
---|---|
GET Get full schema | Retrieves the full profile schema, including default and custom fields. |
GET Get custom fields | Retrieves custom fields in the profile schema. |
PUT Create or delete custom fields | Allows 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:
- Adding custom fields
- Defining PII and sensitive custom fields
- Configuring Unique Alternate Keys
- Configuring TTL
- Deleting custom fields
- Restrictions
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 includecustomField1
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,
ornot
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 inv-unique
.