Enriching Unified Objects with Custom Metadata

July 27, 2025

Overview

The metadata_metadata object is a powerful addition to the Unified data model. It enables the definition of metadata schemas (custom fields) that can be attached to various unified objects—such as commerce_item, ats_job, hris_employee, and more.

This document explains its structure, how to use it effectively, and best practices for managing dynamic metadata across models.

Purpose

metadata_metadata serves as a schema registry for custom fields, allowing users to enrich objects with reusable, structured metadata. These definitions dictate the format and structure of metadata values that live inside the metadata field of supported Unified objects.

Object Structure

interface IMetadataMetadata {
  id?: string;
  created_at?: (string | Date | number);
  updated_at?: (string | Date | number);
  name: string; // Required
  slug?: string;
  format?: string; // One of the supported formats
  original_format?: string;
  options?: string[];
  object_type: string; // e.g. 'commerce_item', 'ats_job'
  objects?: { [objectType: string]: string[] }; // Map of object_type to object IDs
}

Key Concepts

object_type

This specifies the unified model the metadata is associated with. Examples include:

• "commerce_item"
• "ats_job"
• "hris_employee"
• Other Unified Objects

When listing metadata_metadata entries, you can filter by type, which corresponds to the object_type.

format

Defines the data type for the metadata field. Supported formats include:

• 'TEXT'
• 'NUMBER'
• 'DATE'
• 'BOOLEAN'
• 'FILE'
• 'TEXTAREA'
• 'SINGLE_SELECT'
• 'MULTIPLE_SELECT'
• 'MEASUREMENT'
• 'PRICE'
• 'YES_NO'
• 'CURRENCY'
• 'URL'

objects

A mapping of object types to the specific object IDs where this metadata is currently applied. Example:

json
CopyEdit
{
  "objects": {
    "commerce_item": ["item1", "item2"],
    "ats_job": ["job1"]
  }
}

This makes it easy to track which unified records are using each metadata definition.

Usage in Unified Objects

Each unified object includes a metadata array, where each entry corresponds to a metadata definition from the metadata_metadata registry.

Example: IAtsJob

interface IAtsMetadata {
  id?: string;
  slug?: string;
  value?: unknown;
  namespace?: string;
  format?: string;
  extra_data?: unknown;
}

interface IAtsJob {
  ...
  metadata?: IAtsMetadata[];
  ...
}

Workflow Example

Step 1: Create a metadata_metadata Definition

To begin, define the metadata schema by providing only the following required fields:

• name: Human-friendly label
• slug: Unique programmatic identifier (Picked up from name if not given)
• format: Expected data format (e.g., "TEXT", "NUMBER", etc.)

POST /metadata_metadata
{
  "name": "Binding Mount",
  "slug": "binding_mount",
  "format": "TEXT"
}

Step 2: Review the Created Metadata

Once the metadata is created, the full record might look like this (after automatic enrichment):

GET /metadata_metadata/1
{
  "id": "1",
  "name": "Binding Mount",
  "slug": "binding_mount",
  "format": "TEXT",
  "original_format": "single_line_text_field"
}

Step 3: Attach Metadata to a Unified Object

PATCH /commerce_item/7
{
  "metadata": [
    {
      "id": "1",
      "slug": "binding_mount",
      "value": "Optimistic"
    }
  ]
}

Make sure the id / slug match the schema created in Step 1.

Step 4: Review the Metadata Again

Once the metadata is used in a Unified object, the full record might be updated to look like this:

GET /metadata_metadata/1
{
  "id": "1",
  "name": "Binding Mount",
  "slug": "binding_mount",
  "format": "TEXT",
  "original_format": "single_line_text_field",
  "object_type": "commerce_item",
  "objects": {
    "commerce_item": ["7"]
  }
}

This shows the metadata definition has been associated with the unified object type commerce_item and is linked to object with ID 7.

CRUDL Support

Full Create, Read, Update, Delete, and List operations are supported on metadata_metadata. This enables:

• Schema-driven form builders
• Reusable definitions across multiple objects
• Consistent data validation and audit trails

Use Cases