Martini Normalizing Data Models

Overview

Data model normalization in Martini is about creating canonical (standardized) data models that serve as a shared integration target for your business entities. Rather than mapping data directly between different systems (point-to-point integration), normalization establishes a common data shape that all integrations map to and from. This approach uses normalization principles to keep your canonical models clean, reusable, and maintainable across multiple platforms and APIs.

What You Will Learn

• How to design canonical data models that serve as integration targets
• Why canonical models eliminate complex point-to-point mapping scenarios
• Normalization principles for keeping shared models clean and reusable
• Step-by-step process for implementing normalized models in Martini
• How to leverage Negroni for accelerated canonical model development

When To Use This

Use data model normalization to create canonical models that serve as shared integration targets for your business entities.

Use this when you need to:

• Integrate three or more systems that share common entities (customers, orders, products) where each system has different data structures
• Swap or replace systems without rewriting every integration - new systems only need mapping to the canonical model, not to every other system
• Build multiple services and workflows that should work with the same payload shape, eliminating duplicate transformation logic across your application
• Generate consistent reports that require unified definitions and formats across multiple data sources

When not to use this:

• One-off integrations where you're connecting two systems with no expectation of reuse or expansion
• Simple pass-through scenarios where data flows directly from source to destination without transformation, and normalization would add unnecessary overhead

Prerequisites

• Martini Designer installed and running
• A Martini Package in the active workspace
• Basic understanding of data models and data mapping
• Familiarity with HTTP Client for external API integration
• Understanding of services and workflows in Martini
• Knowledge of SQL services for database operations

Understanding Canonical Data Models

Canonical data models serve as the shared integration target for business entities across your system. Instead of creating direct mappings between every system (point-to-point integration), you establish one canonical model that all systems map to and from. This creates a hub-and-spoke integration pattern that's much easier to maintain and extend.

Data Normalization in Practice

Consider integrating customer data from three e-commerce platforms. Each platform structures customer information differently:

Platform X Customer:

{
  "customer_name": "John Doe",
  "email_address": "john@example.com",
  "phone": "+1-555-0123",
  "status": "active"
}

Platform Y Customer:

{
  "fullName": "John Doe",
  "contactEmail": "john@example.com",
  "phoneNumber": "555-0123",
  "accountStatus": "enabled"
}

Platform Z Customer:

{
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "email": "john@example.com",
  "mobile": "5550123",
  "isActive": true
}

Canonical Customer Model:

{
  "id": "unique-identifier",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1-555-0123",
  "status": "active",
  "source": "platform-x",
  "lastUpdated": "2025-01-20T10:30:00Z"
}

The key insight is that instead of creating mappings like:

• Platform X Customer → Platform Y Customer
• Platform X Customer → Platform Z Customer
• Platform Y Customer → Platform Z Customer

You create a single canonical target:

• Platform X Customer → Canonical Customer
• Platform Y Customer → Canonical Customer
• Platform Z Customer → Canonical Customer

Why canonical models scale better

With N systems, point-to-point integration can require up to N × (N − 1) / 2 mappings. With a canonical model, each system only needs a mapping to (and optionally from) the canonical model—typically N to 2N mappings total.

This is why canonical models become increasingly valuable as you add more systems.

This canonical model becomes the shared vocabulary that all your integrations, APIs, and business logic can rely on.

Benefits of Canonical Models

Canonical models provide several key advantages by eliminating point-to-point integration complexity:

Simplified Integration Architecture: Each new system only needs mapping logic to and from the canonical model, not to every other system. Adding a fourth platform requires one integration, not three additional point-to-point mappings.

Shared Business Logic: Services, workflows, and APIs work with canonical models, meaning business logic is written once and reused across all integrated systems rather than duplicated for each platform.

Consistent Data Contracts: APIs return predictable, normalized data structures regardless of the underlying source, providing a stable contract for consumers and eliminating platform-specific response handling.

Centralized Data Quality: Normalization rules and validation logic are applied once at the canonical level, ensuring consistent data quality across all systems rather than handling quality issues separately for each integration.

How Canonical Models Speed Up Development

Standardizing on canonical models reduces rework and increases reuse across your Martini projects.

Reusable services and workflows: Once you normalize data into canonical entities (for example, CanonicalCustomer), downstream workflows and services can operate on that one model. You avoid rebuilding logic for each source system’s payload shape.

Stable API contracts: APIs built on canonical models remain consistent even if upstream systems change. If Shopify adds a new field or WooCommerce renames one, you update the mapping into the canonical model instead of changing every downstream API and workflow.

Faster onboarding and easier maintenance: New team members learn one shared model vocabulary (Customer, Order, Product) rather than having to understand each platform’s unique schema.

Adding new systems becomes predictable: To add a new platform, you implement one new mapping into the canonical model (and optionally from canonical to the target). You do not need to touch the rest of your workflows, services, or APIs.

Designing Canonical Entities

The foundation of effective normalization lies in designing canonical entities that truly represent your business concepts, not just the technical schemas of your source systems.

Starting with Business Definitions

Begin with business meaning rather than technical schemas. The canonical model should reflect what the entity means to your business, not how various systems happen to store it:

Customer Definition Process:

1. Business Meaning: What makes someone a "customer" in our business?
   • Anyone with an email address?
   • Only those who have made purchases?
   • Both leads and paying customers?
2. Identity Fields: What uniquely identifies a customer across all systems?
   • Email address (most common)
   • Customer ID from primary system
   • Phone number (in some contexts)
3. Core Attributes: What information describes the real-world customer?
   • Contact information (email, phone)
   • Basic demographics (name)
   • Business relationship status

The critical insight is that different systems may use the word "customer" loosely or for different purposes:

• CRM systems might include leads, prospects, and churned users as "customers"
• Billing systems might only consider entities with invoices as "customers"
• Marketing platforms might treat anyone with an email as a "customer"

Your canonical Customer model should represent your business's definition, serving as the authoritative representation that other systems map to.

Canonical Entity Design Principles

Apply normalization principles to keep your canonical models clean and reusable:

Principle	Description	Example
Business-Focused	Attributes represent business concepts, not system behaviors	Include email and status, avoid lastSyncTimestamp
Normalized Structure	Eliminate redundancy and maintain consistent data organization	Single address object rather than billing_address and shipping_address
Stable Core	Keep essential attributes minimal to reduce coordination costs	Core customer: id, email, name, status
Universal Semantics	Attributes mean the same thing across all integrations	status always represents business relationship, not system state

Identifying Core vs. Extended Attributes

Structure canonical entities with normalized separation between essential and optional data:

Core Customer Attributes (Normalized essentials):

• id: Unique identifier
• email: Primary contact method
• name: Display name
• status: Business relationship status

Extended Attributes (Optional, context-specific):

• address: Physical location
• phone: Additional contact method
• preferences: User settings
• metadata: System-specific information

This separation follows normalization principles by avoiding mixing required business data with optional system-specific information.

Implementing Normalized Models in Martini

Transform your canonical entity designs into working Martini data models through a systematic implementation process.

Example User Story

To demonstrate canonical model implementation, we'll follow this scenario:

User Story: As a developer, I need to integrate customer data from three e-commerce platforms (Shopify, WooCommerce, and Magento), store them in a unified format, and provide a single API endpoint that returns customer information for reporting systems.

Technical Requirements:

• Fetch customers from each platform's API
• Transform different data structures into a single canonical format
• Store canonical customer data in a database
• Provide a REST API that returns normalized customer information

The following implementation steps will show how to achieve this using Martini's canonical data model approach.

Step 1: Create Canonical Data Models

Start by creating data models in Martini for your canonical entities:

1. Open Martini Designer and navigate to your target package
2. Create a new data model named CanonicalCustomer
3. Define the properties based on your business requirements:

CanonicalCustomer
+-- id            // unique identifier
+-- name          // full display name
+-- email         // primary contact email
+-- phone         // contact phone number
+-- status        // active, inactive
+-- source        // originating platform
+-- lastUpdated   // timestamp of last modification

Step 2: Set Up Source System Integration

For each platform you're integrating, create HTTP requests and export them as services:

1. Use the HTTP Client to create HTTP requests for each platform API
2. Export requests as services to generate platform-specific data models
3. Configure request bodies and response bodies as needed

This process automatically generates source-specific models that match each platform's API structure.

Example: Martini generates ShopifyCustomerOutput, WooCommerceCustomerOutput, and MagentoCustomerOutput models based on each platform's API response structure.

Step 3: Build Data Transformation Logic

Create services or workflows that transform each source system’s output model into your canonical model.

You typically implement this in one of two ways:

• Workflow-based normalization: Use a workflow to call the source API/service, then use a Mapper step to transform the source output model into the canonical model.
• Service-based normalization: Create a dedicated normalization service (for example, TransformShopifyCustomer) that accepts the source model and returns the canonical model.

Mapper setup

Configure your mapping so the source-specific output becomes a canonical entity:

| Source Properties     | Mapping Lines | Target Properties                |
|-----------------------|---------------|----------------------------------|
| shopifyCustomerOutput |               | canonicalCustomer                |
| +-- customer_name     | ------------> | +-- name                         |
| +-- email_address     | ------------> | +-- email                        |
| +-- phone             | ------------> | +-- phone (normalized format)    |
| +-- status            | ------------> | +-- status (standardized values) |
| +-- updated_at        | ------------> | +-- lastUpdated                  |

Normalization rules to apply

• Standardize values: Convert platform-specific enums into a canonical vocabulary (for example, enabled/disabled → active/inactive)
• Normalize formats: Standardize phone numbers, timestamps, and addresses
• Resolve semantic differences: Map equivalent concepts into a single canonical field (for example, fullName or first + last → name)
• Apply business rules: Enforce your business definition at the canonical boundary

Example: Create TransformShopifyCustomer to map ShopifyCustomerOutput into CanonicalCustomer, including Shopify-specific field naming, formats, and value conversions.

Step 4: Database Persistence with SQL Services

Canonical models typically align closely with database entities, making persistence straightforward. Since your canonical model represents the standardized business entity, your database table structure can mirror the canonical model properties.

Benefits of Canonical-Database Alignment:

• Direct mapping between canonical model and database schema
• Simplified SQL services development due to structural similarity
• Consistent data storage regardless of source system
• Easier reporting queries using standardized column names

Database Table Example:

CREATE TABLE canonical_customers (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    phone VARCHAR(20),
    status VARCHAR(20) NOT NULL,
    source VARCHAR(50) NOT NULL,
    last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Implementation:

1. Create SQL services for CRUD operations on canonical_customers table
2. Create services that use these SQL services to handle the persistence process

Example: Create SaveCanonicalCustomer SQL service for database operations, then create a PersistCustomerData service that uses this SQL service to handle the complete persistence process, including validation and error handling.

Reporting and Analytics on Canonical Data

Canonical models do more than simplify integrations—they also create a consistent foundation for reporting and analytics.

When you store data in canonical tables (for example, canonical_customers), reporting queries no longer need to account for Shopify fields vs. WooCommerce fields vs. CRM fields. Every record shares the same schema and semantics.

Recommended reporting pattern

1. Persist canonical entities into dedicated canonical tables (for example, canonical_customers, canonical_orders).
2. Include lightweight lineage fields such as:
   • source (which system the record came from)
   • lastUpdated (when it was last synchronized into the canonical store)
3. Build reporting views on top of canonical tables for business-friendly dashboards and exports.

Example query

The following query returns customer counts by platform and status, without needing platform-specific joins or transformations:

SELECT
  source,
  status,
  COUNT(*) AS customer_count
FROM canonical_customers
GROUP BY source, status
ORDER BY source, status;

Because the canonical model standardizes fields such as status (for example, mapping enabled/disabled or active/inactive into a single vocabulary), reporting becomes consistent across all integrated systems.

Step 5: API Development with Canonical Models

Use canonical models as the foundation for APIs that provide consistent, normalized responses.

API Endpoint Example:

GET /api/customers

API Response Structure:

{
  "customers": [
    {
      "id": "cust-001",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1-555-0123",
      "status": "active",
      "source": "shopify",
      "lastUpdated": "2025-01-20T10:30:00Z"
    }
  ],
  "metadata": {
    "total": 1,
    "sources": ["shopify", "woocommerce", "magento"],
    "lastSync": "2025-01-20T10:30:00Z"
  }
}

Implementation:

1. Create REST API with customer endpoints
2. Set canonical model as part of the response body for consistent API contracts
3. Build operation handler services that query canonical customer data
4. Return normalized data regardless of underlying source platforms

The API returns normalized data regardless of whether the underlying customer data came from Shopify, WooCommerce, or Magento. API consumers don't need to handle platform-specific variations because the canonical model abstracts those differences.

Example: Create GetCustomers service as the operation handler that queries the canonical_customers table and returns results using the CanonicalCustomer model structure.

Scaling with Additional Platforms

As new platforms are integrated:

• Map to Canonical Model: Each platform's data maps to the existing canonical model, following the established transformation logic.
• Reuse Services and Workflows: Existing services and workflows that operate on the canonical model automatically work with new platform data.
• Consistent API and Reporting: APIs and reports continue to function without changes, providing consistent output regardless of the number of integrated platforms.

Accelerating Development with Negroni

Negroni is Lonti's cloud-based platform for designing entities within manifests that comply with Common Data Model (CDM) standards. Negroni provides unique functionality for developers working with Martini through its ability to design entities collaboratively and export them as complete, ready-to-use Martini packages.

The two fundamental components of Negroni are Manifest and Entity. Entities are the business objects you and your team design together, defining their attributes and relationships. Manifests serve as blueprints that contain these interconnected entities, representing complete business domains like "Customer Management" or "E-commerce Operations."

Why Negroni Accelerates Development

Negroni addresses several challenges that teams face when building data models:

• Team Collaboration: Multiple team members can work together designing entities, ensuring everyone agrees on canonical definitions before implementation begins.
• Industry Standards Out-of-the-Box: Instead of inventing entities from scratch, teams can start with core entities and manifests derived from Microsoft's Common Data Model (CDM) for common business concepts like Customer, Product, and Order.
• Reusability Across Projects: Once designed, entities can be reused across different projects and integrations, maintaining consistency throughout your organization.
• Complete Implementation Generation: Manifests export as complete Martini packages containing everything needed to start building your project.

From Collaborative Design to Martini Implementation

The workflow from team entity design to working data models follows this "model once, use everywhere" approach:

1. Collaborative Entity Design: Teams use Negroni's interface to define entities that align with business requirements.
2. Manifest Assembly: Organize related entities into manifests that represent complete business domains or integration scenarios.
3. Configuration Setup: Configure the manifest to control how the implementation will function once exported as a Martini package—defining API endpoints, database connections, service implementation, and more.
4. Package Export: Export the manifest as a complete Martini package with all implementation components configured according to your manifest specifications.
5. Import and Extend: Import the package into Martini and build transformation logic to map source systems to your canonical entities.

What You Get in a Negroni-Generated Martini Package

When you export a configured Negroni manifest as a Martini package, you receive a complete foundation for your project that typically includes:

• Data Models: Each entity becomes a Martini data model, ready to use in services, workflows, and APIs.
• Database Setup Service: Automatically configures database connection pools and creates the schema.
• Complete CRUD API: Endpoints for each entity with all CRUD operations already configured and ready to use.
• CRUD Services: Operation handler services for each API endpoint.
• SQL Services: Database services that the CRUD services use.

The exact contents depend on your manifest configuration and the entities you've defined. This means developers get a working foundation they can immediately build upon, integrate with, and modify—without writing boilerplate setup code.

When to Use Negroni vs. Direct Martini Modeling

Choose your approach based on your team's needs and project complexity:

Use Negroni When:

• Multiple team members need to collaborate on entity definitions
• You want to leverage core entities as a starting point
• You need complete API and database scaffolding for your canonical models
• You're building multiple projects that should share the same entity definitions
• You want to maintain consistent canonical models across your organization

Model Directly in Martini When:

• You're working solo or with a small team that doesn't need collaborative design
• Your canonical models are highly specific and don't benefit from CDM standards
• You need fine-grained control over every aspect of the data model implementation
• You're extending existing Martini packages rather than starting fresh

Maintaining Version Alignment

When using Negroni-generated packages, treat your entity models as contracts that should be versioned intentionally:

• Package Versioning: When exporting manifests as Martini packages, Negroni supports package versioning to track changes and maintain compatibility.
• Documentation Strategy: For data model exports (without full packages), maintain clear documentation of entity changes and coordinate updates across team members.
• Contract-Based Approach: Consider canonical entities as API contracts—changes should be planned, communicated, and deployed in a coordinated manner across all systems that depend on them.

This approach ensures your canonical models remain stable foundations for integration while allowing for controlled evolution as business requirements change.

Helpful Resources

• Creating and Deleting Data Models - Foundation for building canonical models
• Data Model Best Practices - Guide for designing effective data models
• HTTP Client Documentation - For external system integration
• SQL Services Guide - Database persistence with canonical models
• REST API Creation Guide - Building APIs with canonical models
• Negroni Platform Documentation - Accelerated canonical model development
• Community Q&A: Martini Community
  Have a Question? Post or search it here.