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