---
title: "Enriching Unified Objects with Custom Metadata"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/enriching_unified_objects_with_custom_metadata-icon.webp
date: 2025-07-23T00:00:00.000Z
tag: Guides
description: "The metadatametadata object is a powerful addition to the Unified data model. It enables the definition of metadata schemas (custom fields) that can be..."
url: "https://docs.unified.to/guides/enriching_unified_objects_with_custom_metadata"
---

# Enriching Unified Objects with Custom Metadata
------
_July 23, 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


```typescript
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
{
  "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`


```javascript
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.)

```json
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):


```json
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


```json
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:


```json
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


| Use Case                          | Example                                |
| --------------------------------- | -------------------------------------- |
| Custom field on ATS Job           | `"interview_style": "technical panel"` |
| Enrich commerce item with specs   | `"binding_mount": "Optimistic"`        |
| Add legal identifiers to employee | `"national_id": "IN123456"`            |