Custom metadata

Content Platform Tenant Management Help

File Size
4269 KB
Part Number

Custom metadata is user-supplied descriptive information about an object. Custom metadata is specified as annotations, where each annotation is a discrete unit of information about the object.

You can add, replace, or delete an annotation in its entirety. You cannot modify it in place.

Each object can have zero or more annotations, including a special one named default.

Annotations let you compartmentalize custom metadata by logical units, such as organization or application. They can also help prevent collisions between two users or applications trying to update custom metadata at the same time. You can create an annotation that has no content.

Each annotation has a name. The default annotation can be created or accessed without specifying a name or by using the name default. Annotation names must be one through 32 characters long. They must contain at least one alphanumeric character and can contain periods (.), underscores (_), and hyphens (-). Annotation names are case sensitive.

Annotations are typically specified in XML format, but this is not necessarily required. The namespace configuration determines whether HCP checks that annotations are well-formed XML. While checking is enabled, if you try to store an annotation that is not well-formed XML, HCP rejects it.

The following list shows limits that apply to custom metadata.

Maximum number of annotations per object
Maximum annotation size
1 GB
Largest annotation that HCP indexes
1 MB
Largest nondefault annotation that HCP checks for well-formed XML
1 MB
Largest default annotation that HCP checks for well-formed XML
1 GB
Maximum level of nested XML elements
Maximum number of XML elements in an annotation

As specified above, the largest annotation that HCP indexes is 1 MB. This means that the cumulative size of all indexed annotations for the object cannot exceed 1 MB total. For example, if you have four separate 215 KB annotations with a cumulative size of 860 KB, HCP indexes all annotations. If you add a fifth 215 KB annotation, the cumulative size exceeds the 1 MB limit and HCP does not index any of the annotations for the object.

To add, replace, or delete the default annotation, you can use the HTTP or WebDAV protocol. To add, replace, or delete any other annotation, you need to use HTTP.

With HTTP, you can use a single request to store or retrieve an annotation together with the object data. With WebDAV, you store and retrieve annotations separately from object data.

With WebDAV, you store the default annotation in the custom-metadata.xml metafile. You can also use the custom-metadata.xml metafile to store dead properties.

With HTTP, you use a GET request to retrieve an annotation for an object. With WebDAV, CIFS, and NFS, you retrieve the default annotation for an object from the custom-metadata.xml metafile.

The namespace configuration determines what you can do with custom metadata for objects that are under retention. The namespace can be set to:

  • Allow all annotation operations for objects under retention
  • Allow only the addition of new annotations for objects under retention and disallow replacement or deletion of existing annotations
  • Disallow all annotation operations for objects under retention

Whether annotations are indexed and how they are indexed depend on system-level and namespace-level settings.