Metadata

Many resources in the platform have a metadata field that can be used to store miscellaneous custom information. This field is used by extensions and applications to store data like: UI/UX preferences, additional references and notes and relationships to extensions etc.

The metadata field always defaults to null and when populated is a JSON object with some additional rules:

• Keys must only contain alphanumeric characters, numbers and single underscores.
• Keys may not contain double underscores like __. Double underscores are reserved for lookups on fields.
• Keys and values are merged using JSON Merge Patch when adding metadata to a field that already contains metadata.
• Values may not be null (this is required to support JSON Merge Patch).
• The max size of the entire metadata field (per resource) is capped at 104857 bytes.

JSON Merge Patch

In order to allow simultaneous and partial updates to metadata fields, the platform always runs a JSON Merge Patch when the metadata field is updated.

As a result, the metadata field can be used in the following ways:

• The metadata field can be partially updated without unsetting existing data.
• The metadata can be edited simultaneously without the risk of losing data between multiple edits.
• Keys can be explicitly unset by setting their value to null.

For example, if we have a resource with the following metadata:

{
    "a": "x",
    "b": "y"
}

And we update the field with the following:

{
    "b": null,
    "c": "y"
}

The end result of the update will be:

{
    "a": "x",
    "c": "y"
}

As you can see, b was removed (because it was set to null), c was added, and a was kept (even though it was not explicitly included in the update data).