Table of Contents
Just a second...

Metadata in the Unified API

Metadata is available in the Unified API. It defines how the bytes in your content are formatted.

Content contains byte data. This byte data can be formatted in whatever way your application requires. For example, the data can structured using Diffusion™ record format.

You can use the provided Diffusion APIs to format the byte data as record-based data by defining a metadata structure that describes the data format.

Metadata structure

The metadata structure is made up of nested records and fields. The outer container is the content. This contains one or many records. Each record can contain one or many fields.

Content contains one or more records. Records contain one or more fields.

Fields and records are identified by a name. Every record must have a name that is unique within the content. Every field must have a name that is unique within the enclosing record.

Every field or record defined in the metadata structure can represent one or more possible occurrences of that field or record in the byte data. The number of possible occurrences of a record or field is described by its multiplicity.

The order in which records and fields are defined within their enclosing container defines the order that they appear in byte data.

Field metadata

A metadata field defines an elementary data item within a record.

Every field has the following properties:

Data type

The data type of a field defines its actual representation within the byte data. The following table describes the data types that are available.
Table 1. Data types for metadata fields
Data type Description Default
String

A character string.

Zero-length string
Integer string

An integer represented in the content as a character string.

If a field is defined as this type, it can only contain numeric digits with an optional leading sign. Fields of this type cannot be empty.

0
Decimal string

A decimal number represented in the content as a character string.

Decimal fields have the number of places to the right of the decimal point defined by the scale, the default being 2. Such values can be parsed from a character string with any number of digits to the right of the decimal point. Half-up rounding is applied to achieve the target scale. Output of the field is rendered with the specified scale. Fields of this type cannot be empty.

For comparison purposes the scale is ignored: a value of 1.50 is the same as 1.5.

0.00 (depending on scale)
Custom string

This is a special type where the behavior is delegated to a user-written custom field handler.

This type is available in all topic data types.

-

Multiplicity

The multiplicity of a metadata field or record defines the number of times the corresponding byte data can occur within the enclosing record or content.

Multiplicity is defined in terms of the minimum and maximum number of occurrences. Some byte data representations support variable numbers of records and field, whereas others (such as record data) only support fixed number of records and fields (where minimum=maximum) except in the last position.

Fixed multiplicity is defined by a single number. For example, a multiplicity of 5 on a field indicates that there must be exactly five occurrences of the field within its enclosing record.

Variable multiplicity is defined by a minimum value and a maximum value and is represented with the notation n..n. For example, multiplicity of 1..5 on a field specifies that there can be between one and five occurrences of the field within its enclosing record.

A special maximum value of -1 is used to represent no maximum. For example, a multiplicity of 1..-1 on a field specifies there can be any number of occurrences of the field, but there must be at least one.

Optional nodes are defined by a minimum value of 0. For example, a multiplicity of 0..1 on a field specifies that there can be zero of one occurrences of the field within its enclosing record. A fixed multiplicity of 0 is not allowed.

Default value

You can specify a default value for a field. If you do not specify a default value, the default value for the data type is used. When content is created using metadata, default initialization applies the default values specified for each field.