Validates RT Personalization Entity payloads before creation to prevent common API errors. MUST be invoked proactively during rt-setup-personalization workflow at Step 9c before making the entity creation API call. Also use when encountering "Attribute payload can't be blank" errors or when reviewing personalization entity JSON.
81%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Validates personalization entity payloads and provides error-free templates.
During rt-setup-personalization workflow at Step 9c:
After encountering API errors:
The #1 cause of "Attribute payload can't be blank" errors:
// ❌ FAILS - Empty arrays trigger validation errors
"stringBuilder": []
"attributePayload": []
// ✅ WORKS - Use null instead
"stringBuilder": null
"attributePayload": null| Value | Result |
|---|---|
null or omitted | ✅ OK - skips validation |
[] (empty array) | ❌ ERROR - "can't be blank" |
Section definition must include at least ONE of:
attributePayload (with content)stringBuilder (with content)catalogPayload (with content, feature-flagged)All three cannot be null/empty simultaneously.
The API reports errors incorrectly:
Error: "sections[0].payload.node_id.definition.attribute_payload": ["Attribute payload can't be blank"]Actual cause: stringBuilder: [] (empty array)
Reported cause: attribute_payload (misleading)
Always check stringBuilder first when seeing "can't be blank" errors.
| Field | Validation |
|---|---|
outputName | Required, max 256 chars, unique across all payload types |
realtimeAttributeId | Required, must exist in CDP cache |
subAttributeIdentifier | Required for ListAttribute/SlidingCounterAttribute only |
subAttributeIdentifier rules:
ListAttribute → must match aggregation identifierSlidingCounterAttribute → must match sub_duration identifier| Field | Validation |
|---|---|
outputName | Required, max 256 chars, unique |
values | Required array of {type: "String", value: "..."} |
values | Cannot contain {{ or }} (template brackets forbidden) |
{
"segmentPayload": {
"batchSegments": [
{"id": "segment_id_1"},
{"id": "segment_id_2"}
]
}
}batchSegments required arrayid required and unique| Field | Validation |
|---|---|
catalogName | Required |
lookupAttributeId | Required, must be SingleAttribute or ListAttribute |
lookupColumn | Required |
outputName | Required, max 256 chars, unique |
Unsupported attribute types: ImportedAttribute, CounterAttribute
Error: unsupported_attribute_type_for_lookup_catalog
| Error Message | Root Cause | Solution |
|---|---|---|
attribute_payload: can't be blank | stringBuilder: [] or attributePayload: [] | Change [] to null |
sub_attribute_identifier: invalid_attribute | Missing for ListAttribute or wrong identifier | Add correct aggregation identifier |
output_name: duplicated | Same name in multiple payloads | Use unique names across all payload types |
unsupported_attribute_type_for_lookup_catalog | Counter/Imported in catalog lookup | Use SingleAttribute or ListAttribute |
personalization_invalid_string_builder | {{ or }} in string values | Remove template brackets |
Name has already been taken | Duplicate personalization name | Use unique name or update existing |
{
"attributes": {
"audienceId": "PARENT_SEGMENT_ID",
"name": "personalization_name",
"description": "Description of use case",
"sections": [{
"name": "section_name",
"entryCriteria": {
"name": "trigger_name",
"keyEventCriteria": {
"keyEventId": "KEY_EVENT_ID",
"keyEventFilters": null
}
},
"payload": {
"UNIQUE_NODE_ID": {
"type": "ResponseNode",
"name": "response_name",
"definition": {
"attributePayload": [{
"realtimeAttributeId": "RT_ATTR_ID",
"outputName": "output_name"
}],
"segmentPayload": null,
"stringBuilder": null
}
}
},
"includeSensitive": false
}]
},
"relationships": {
"parentFolder": {
"data": {
"id": "FOLDER_ID",
"type": "folder-segment"
}
}
}
}{
"attributes": {
"audienceId": "PARENT_SEGMENT_ID",
"name": "personalization_with_message",
"description": "Personalization with welcome message",
"sections": [{
"name": "all_visitors",
"entryCriteria": {
"name": "pageview",
"keyEventCriteria": {
"keyEventId": "KEY_EVENT_ID",
"keyEventFilters": null
}
},
"payload": {
"UNIQUE_NODE_ID": {
"type": "ResponseNode",
"name": "visitor_data",
"definition": {
"attributePayload": [
{"realtimeAttributeId": "RT_ATTR_1", "outputName": "last_product"},
{"realtimeAttributeId": "RT_ATTR_2", "outputName": "page_views"}
],
"segmentPayload": null,
"stringBuilder": [{
"values": [{"value": "Welcome to our website!", "type": "String"}],
"outputName": "welcome_message"
}]
}
}
},
"includeSensitive": false
}]
},
"relationships": {
"parentFolder": {
"data": {"id": "FOLDER_ID", "type": "folder-segment"}
}
}
}{
"definition": {
"attributePayload": [
{
"realtimeAttributeId": "LIST_ATTR_ID",
"subAttributeIdentifier": "items",
"outputName": "browsed_items"
},
{
"realtimeAttributeId": "SINGLE_ATTR_ID",
"outputName": "last_item"
}
],
"segmentPayload": null,
"stringBuilder": null
}
}validate_personalization_payload() {
local payload_json="$1"
# Check for empty arrays (common mistake)
if echo "$payload_json" | grep -q '"stringBuilder":\s*\[\s*\]'; then
echo "❌ ERROR: stringBuilder is empty array. Change to null."
return 1
fi
if echo "$payload_json" | grep -q '"attributePayload":\s*\[\s*\]'; then
echo "❌ ERROR: attributePayload is empty array. Change to null."
return 1
fi
# Check for template brackets in stringBuilder values
if echo "$payload_json" | grep -q '{{.*}}'; then
echo "❌ ERROR: stringBuilder values cannot contain {{ or }}"
return 1
fi
# Verify at least one payload type has content
local has_attrs=$(echo "$payload_json" | jq '.attributes.sections[0].payload | .. | .attributePayload? | select(. != null and . != []) | length')
local has_strings=$(echo "$payload_json" | jq '.attributes.sections[0].payload | .. | .stringBuilder? | select(. != null and . != []) | length')
if [ -z "$has_attrs" ] && [ -z "$has_strings" ]; then
echo "❌ ERROR: Must include at least one: attributePayload or stringBuilder with content"
return 1
fi
echo "✅ Payload validation passed"
return 0
}
# Usage:
# validate_personalization_payload "$PAYLOAD_JSON" || exit 1Before creating a personalization entity:
uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')null not []outputName fields are unique across the sectionrealtimeAttributeId values exist in CDPsubAttributeIdentifier{{ or }} in stringBuilder valuesCheck stringBuilder first:
# Find the problem
echo "$PAYLOAD" | grep -o '"stringBuilder":\s*\[.*\]'
# If empty [], change to null
PAYLOAD=$(echo "$PAYLOAD" | sed 's/"stringBuilder":\s*\[\]/"stringBuilder": null/g')Check attributePayload:
# If empty [], change to null
PAYLOAD=$(echo "$PAYLOAD" | sed 's/"attributePayload":\s*\[\]/"attributePayload": null/g')Verify at least one has content:
# List existing personalizations
tdx api "/entities/realtime_personalizations?filter[audience_id]=<ps_id>" --type cdp | jq '.data[] | {id, name}'
# Either use a different name or update the existing entityThese examples successfully created personalization entities in production:
Common pattern: Both include populated stringBuilder (not empty array)
crypto.randomUUID() for payload node IDstreasure-data/td-skills
d0e1a9d
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.