Metadata

Metadata lets you enrich entities with user-defined information. You attach custom data as key-value pairs within a metadata object.

What is metadata?

Metadata lets you store supplementary information alongside an entity’s standard data model by adding custom attributes or annotations without altering the entity’s predefined schema. In Midaz, metadata is an object that supports key-value pairs in these data types: strings, integers, floats, and booleans. Keys take up to 100 bytes and values up to 2,000 bytes.

Metadata does not support nested values.

Example of metadata

Consider an Organization entity as shown below:

{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": null,
  "legalName": "Empresa Teste Ltda",
  "doingBusinessAs": "Empresa Teste",
  "legalDocument": "86820799000188",
  "address": {
    "line1": "Rua Botucatu, 10",
    "line2": "Casa B",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "metadata": null,
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

To enrich this organization with additional information, such as industry sector and number of employees, you can include a metadata object in your POST or PATCH requests:

{
  "metadata": {
    "sector": "Fintech",
    "employees": "50-100"
  }
}

Creating entities with metadata

When creating an entity, you can submit metadata through our POST endpoints and add custom data from the start.

Updating and removing metadata

Our API follows the JSON Merge Patch RFC for metadata updates:

Adding or Updating Values: Submitting a key with a new value in a PATCH request updates the existing metadata.
Removing Keys: Sending a key as null in a PATCH request removes that key-value pair. A key you omit keeps its value.
Removing all keys: On /v1, sending metadata as null in a PATCH request removes every key that you set. On a transaction or an operation, the keys that the ledger writes stay. On /v2, sending metadata as null keeps the stored metadata. To remove keys on /v2, send each key as null.
Keeping metadata unchanged: Sending metadata as {}, or leaving metadata out of the PATCH request, keeps the stored metadata.

Practical example: modifying metadata

Suppose an Organization entity initially included metadata for sector and employee count. To update the employee count while removing the sector, send a PATCH request with the following metadata:

{
  "metadata": {
    "employees": "100-150",
    "sector": null
  }
}

After the request is processed, the sector key will be removed, and the employee count will be updated.

Overview

Integration essentials

Stability & quality

Field dictionary

Event streaming

What is metadata?

Example of metadata

Creating entities with metadata

Updating and removing metadata

Practical example: modifying metadata

​What is metadata?

​Example of metadata

​Creating entities with metadata

​Updating and removing metadata

​Practical example: modifying metadata

What is metadata?

Example of metadata

Creating entities with metadata

Updating and removing metadata

Practical example: modifying metadata