AEP Schema Design Best Practices

Why Schema Design Matters

In Adobe Experience Platform, schemas are immutable after data ingestion. You can add fields, but you can't:

• Rename existing fields
• Change field data types
• Delete fields with data
• Restructure nested objects

This means mistakes made during initial schema design follow you forever—or require expensive data migration projects.

Understanding XDM Architecture

Schema Building Blocks

Every AEP schema is built from these components:

Component	Description	Can Modify?
Class	Base behavior (Profile, ExperienceEvent, Record)	No (after creation)
Field Group	Reusable collection of related fields	Can add fields only
Data Type	Reusable complex structure (address, consent)	Can add fields only
Field	Individual data element with type	Cannot change type

Choosing the Right Class

• XDM Individual Profile: Person-level attributes (preferences, demographics)
• XDM ExperienceEvent: Time-series behavioral data (clicks, purchases)
• XDM Record: Non-person entities (products, locations, accounts)

Field Group Strategy

Use Adobe Field Groups First

Adobe provides pre-built field groups for common use cases. Always check these before creating custom ones:

• Demographic Details: Name, birth date, gender
• Personal Contact Details: Email, phone, address
• Commerce Details: Cart, purchases, product views
• Web Details: Page views, referrer, browser
• Consent and Preference Details: GDPR/CCPA compliance

When to Create Custom Field Groups

Create custom field groups for:

• Industry-specific data (healthcare, finance, retail)
• Proprietary business attributes
• Integration-specific fields
• Computed/derived attributes

Field Group Design Principles

1. Single Responsibility: Each field group should represent one concept
2. Reusability: Design for use across multiple schemas
3. Namespace Properly: Use your tenant namespace for custom fields
4. Document Everything: Add descriptions to every field

Naming Conventions

Schema Names

// Good naming pattern
[Tenant]_[EntityType]_[Purpose]_Schema

// Examples
Acme_Profile_Loyalty_Schema
Acme_Event_WebBehavior_Schema
Acme_Record_Product_Schema

Field Names

// Use camelCase for field names
loyaltyTier
purchaseCount
lastActivityDate

// NOT
loyalty_tier    // Snake case
LoyaltyTier     // PascalCase
LOYALTYTIER     // All caps

Field Group Names

// Pattern
[Tenant] [Domain] [Entity] Details

// Examples
Acme Loyalty Member Details
Acme Commerce Purchase Details
Acme Healthcare Patient Details

Data Type Selection

Choose Types Carefully

You cannot change a field's data type after creation. Choose wisely:

Use Case	Recommended Type	Why
IDs, codes	String	Flexible, handles leading zeros
Counts, quantities	Integer	Efficient for whole numbers
Prices, scores	Number (Double)	Handles decimals
Dates	DateTime	ISO 8601 format required
Yes/No flags	Boolean	True/false only
Categories	String + Enum	Enforces valid values

Identity Design

Primary vs Secondary Identities

• Primary Identity: The main identifier for the record (one per schema)
• Secondary Identities: Additional identifiers for matching

Identity Best Practices

1. Use stable, persistent IDs as primary (CRM ID, loyalty ID)
2. Mark email and phone as identities with correct namespace
3. Never use PII directly—hash or use namespaced identifiers
4. Plan your identity graph before implementation

// Good identity structure
{
  "identityMap": {
    "CRMID": [{"id": "ABC123", "primary": true}],
    "Email": [{"id": "hash_abc...", "primary": false}],
    "Phone": [{"id": "hash_123...", "primary": false}]
  }
}

Common Schema Mistakes

Mistake #1: Flat Schemas

Problem: Putting all fields at the root level

// Bad: Flat structure
{
  "firstName": "...",
  "lastName": "...",
  "email": "...",
  "phone": "...",
  "addressLine1": "...",
  "addressCity": "..."
}

Solution: Use proper nesting with field groups

// Good: Structured with field groups
{
  "person": {
    "name": {"firstName": "...", "lastName": "..."}
  },
  "personalEmail": {"address": "..."},
  "homeAddress": {
    "street1": "...",
    "city": "..."
  }
}

Mistake #2: Over-Engineering

Problem: Creating overly complex nested structures for simple data

Solution: Keep nesting to 3-4 levels maximum. If deeper, reconsider your data model.

Mistake #3: Ignoring Cardinality

Problem: Using arrays when single values needed, or vice versa

// Ask: Can a person have multiple?
email: single value? or array?
// Usually array - people have work/personal emails

loyaltyTier: single value? or array?
// Usually single - one tier at a time

Mistake #4: Missing Timestamps

Problem: Not tracking when attributes changed

Solution: Add timestamp fields for important attributes

{
  "loyaltyTier": "Gold",
  "loyaltyTierUpdatedAt": "2025-01-15T10:30:00Z",
  "loyaltyTierPreviousValue": "Silver"
}

Schema Evolution Strategy

What You Can Change

• ✅ Add new fields to existing field groups
• ✅ Add new field groups to schemas
• ✅ Update field descriptions
• ✅ Add enum values (not remove)

What You Cannot Change

• ❌ Rename fields
• ❌ Change data types
• ❌ Delete fields with data
• ❌ Change cardinality (single ↔ array)
• ❌ Change schema class

Versioning Approach

When major changes needed:

1. Create new schema version: Acme_Profile_Loyalty_v2_Schema
2. Set up parallel data flows during transition
3. Migrate historical data if needed
4. Deprecate old schema after cutover

Pre-Launch Checklist

Before enabling schemas for Profile or going to production:

• ☐ All field names follow naming conventions
• ☐ Every field has a description
• ☐ Data types are appropriate for the data
• ☐ Identity fields are properly configured
• ☐ Consent fields are included (GDPR/CCPA)
• ☐ Adobe field groups used where applicable
• ☐ Schema tested with sample data
• ☐ Downstream dependencies documented
• ☐ Stakeholders have reviewed and approved