Create Event Schemas

Event schemas are the foundation of data quality in DataBridge. They define the structure, types and validation rules for your events using the industry-standard JSON Schema format.

Why Event Schemas Matter

Event schemas serve as data contracts between your applications and data warehouse:

• Prevent bad data - Invalid events are blocked before reaching your warehouse
• Document your data - Auto-generated documentation from schemas
• Version control - Track schema evolution over time
• Team alignment - Ensure engineering, analytics and business teams agree on data structure
• Debugging - Trace data quality issues back to their source

Schema Identity: Namespace, Name, Version

Each schema is uniquely identified by three components:

1. Namespace

Your organization or domain identifier. Examples:

• com.yourcompany (reversed domain)
• yourcompany.com (domain)
• analytics (simple identifier)

Best practice: Use a consistent namespace across all your schemas (e.g., com.acme for all Acme Corp events).

2. Name

The event name describing what happened. Examples:

• page_view - User viewed a page
• purchase_completed - Purchase transaction completed
• user_signed_up - New user registration
• button_clicked - UI interaction event

Best practice: Use descriptive, snake_case names that clearly indicate the event's purpose.

3. Version

Semantic versioning in the format MAJOR-MINOR-PATCH:

• MAJOR (1-0-0): Breaking changes that are incompatible with previous versions
• MINOR (1-1-0): New fields added (backward compatible)
• PATCH (1-1-1): Bug fixes or documentation updates

Example: com.acme/purchase_completed/1-0-0

Creating Your First Schema

Step 1: Navigate to Events Section

Go to the Events section in DataBridge Cloud and click Create new schema.

Step 2: Define Schema Identity

Provide the schema identity:

• Namespace: com.yourcompany
• Name: purchase_completed
• Version: 1-0-0 (default)

Step 3: Write JSON Schema

Define your event structure using JSON Schema. Here's a complete example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Tracks successful purchase transactions",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user",
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "order_id": {
      "type": "string",
      "description": "Unique order identifier",
      "pattern": "^ORD-[0-9]+$"
    },
    "amount": {
      "type": "number",
      "description": "Purchase amount",
      "minimum": 0,
      "maximum": 1000000
    },
    "currency": {
      "type": "string",
      "description": "Three-letter currency code",
      "enum": ["USD", "EUR", "GBP", "JPY"]
    },
    "items": {
      "type": "array",
      "description": "List of purchased items",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {"type": "string"},
          "quantity": {"type": "integer", "minimum": 1},
          "price": {"type": "number", "minimum": 0}
        },
        "required": ["product_id", "quantity", "price"]
      },
      "minItems": 1
    },
    "timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp",
      "format": "date-time"
    }
  },
  "required": ["user_id", "order_id", "amount", "currency", "timestamp"]
}

Step 4: Review in Viewer Tab

Switch to the Viewer tab to see how DataBridge interprets your schema:

• Field names and data types
• Validation rules (required fields, formats, ranges)
• Descriptions and constraints
• Nested object structures

Step 5: Save Schema

Click Save to store your schema in the DataBridge Schema Registry.

Step 6: Test with Validation Tab

Use the Validate tab to test JSON payloads against your schema:

Valid event example:

{
  "user_id": "user_12345",
  "order_id": "ORD-98765",
  "amount": 149.99,
  "currency": "USD",
  "items": [
    {"product_id": "PROD-001", "quantity": 2, "price": 49.99},
    {"product_id": "PROD-002", "quantity": 1, "price": 50.01}
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Invalid event example (will be rejected):

{
  "user_id": "user_12345",
  "order_id": "ORD-98765",
  "amount": -10,  // ❌ Negative amount not allowed
  "currency": "XXX",  // ❌ Invalid currency code
  "timestamp": "invalid-date"  // ❌ Invalid date format
}

The Validate tab will show detailed error messages for any validation failures.

JSON Schema Best Practices

1. Always Include Descriptions

{
  "user_id": {
    "type": "string",
    "description": "Unique identifier for the user from Auth0"  // Clear context
  }
}

2. Use Validation Constraints

{
  "email": {
    "type": "string",
    "format": "email"  // Built-in email validation
  },
  "age": {
    "type": "integer",
    "minimum": 0,
    "maximum": 120
  }
}

3. Mark Required Fields

{
  "required": ["user_id", "event_type", "timestamp"]
}

4. Use Enums for Fixed Values

{
  "event_type": {
    "type": "string",
    "enum": ["click", "view", "scroll", "submit"]
  }
}

5. Define Array Items

{
  "tags": {
    "type": "array",
    "items": {"type": "string"},
    "minItems": 1,
    "maxItems": 10
  }
}

Schema Versioning

When you need to change a schema, create a new version:

Backward Compatible (Minor Version)

Adding optional fields → 1-0-0 → 1-1-0

{
  "properties": {
    "user_id": {"type": "string"},
    "email": {"type": "string"}  // New optional field
  },
  "required": ["user_id"]  // Only user_id required
}

Breaking Changes (Major Version)

Changing required fields, types, or removing fields → 1-0-0 → 2-0-0

{
  "properties": {
    "user_id": {"type": "string"},
    "user_email": {"type": "string"}  // Renamed field
  },
  "required": ["user_id", "user_email"]  // Now required
}

Common Validation Rules

Rule	Example	Use Case
pattern	"pattern": "^[A-Z]{2}[0-9]{4}$"	Format validation (e.g., country code + digits)
minLength / maxLength	"minLength": 8, "maxLength": 50	String length constraints
minimum / maximum	"minimum": 0, "maximum": 100	Numeric range validation
format	"format": "email" or "format": "uri"	Built-in format validators
enum	"enum": ["active", "inactive"]	Allowed values
minItems / maxItems	"minItems": 1, "maxItems": 10	Array size constraints

Schemas and Destination Tables

Beyond validation, your JSON Schemas also control how DataBridge creates tables in your data stores. Each top-level property becomes a properly-typed column in the destination table, enabling efficient SQL queries and indexing without any extra configuration.

For example, a string property becomes a TEXT column in PostgreSQL, an integer becomes BIGINT and a string with format: "date-time" becomes TIMESTAMPTZ. See the type mapping overview for all supported types.

Next Steps

Now that you've created your first event schema, you can:

1. Create a Data Source to start sending events
2. Create additional schemas for other event types
3. Version your schemas as requirements evolve

Your schemas are now stored in the DataBridge Schema Registry and ready to validate incoming events!