Instances

In a Metaschema module, complex information elements are created through composition. Through composition, an information element can be built by indicating which other information elements are used as its constituent parts.

An instance is used to declare an information element child within a parent information element. Each instance is a flag instance, field instance, or assembly instance, and either references an existing top-level definition by name or provides an inline definition.

In a Metaschema module, an instance appears inside the definition of its parent information element.

• An assembly definition may contain flag, field or assembly instances reflecting the objects to be permitted in that assembly.
• A field definition may only include flag instances.
• A flag definition never contains instances since flags have no children in the model, only values.

Common Instance Data

The <assembly>, <field>, and <flag> child elements share a common syntax composed of the following XML attributes and elements.

Attributes:

Elements:

These attributes and elements are described in the following subsections.

@deprecated Version

The optional @deprecated attribute communicates that a given compositional use of the referenced information element is intended to be discontinued starting with the specified version.

This version is a reference to the <schema-version> declared in the module header.

If both the definition and the instance declare a @deprecated version, the value provided by the instance MUST override the value provided by the definition.

For example, deprecating the use of the flag named id within the computer assembly starting with the model version 1.1.0 would be represented as follows.

1
2
3
4
5
6
7

<define-flag name="id"/>
<define-assembly name="computer">
  <root-name>computer</root-name>
  <flag ref="id"
    required="yes"
    deprecated="1.1.0"/>
</define-assembly>

@ref

The @ref attribute references the top-level definition that the instance represents through composition. The name indicated by the @ref attribute MUST be a definition of the corresponding type declared in the containing module or a globally scoped definition in an imported module. See Definition Name Resolution.

The instance type corresponds with the definition type as follows.

Note: The names of flags, fields, and assemblies are expected to be maintained as separate identifier sets. This allows a flag, field, and an assembly definition to each have the same name in a given Metaschema module.

<formal-name>

The optional <formal-name> element provides a human-readable, short string label for the instance for use in documentation.

If provided, this formal name MUST override the <formal-name> declared on the corresponding definition, if a <formal-name> is declared there. If not provided, the effective formal name of the instance MUST be the <formal-name> declared on the definition. If neither the instance nor the definition provides a <formal-name>, then the instance MUST NOT have a declared formal name.

<description>

The optional <description> element is a single line of markup that describes the semantic meaning and use of the instance. This information is ideal for use in documentation.

If provided, this description MUST override the <description> declared on the corresponding definition, if a <description> is declared there. If not provided on an instance, the effective description of the instance MUST be the <description> declared on the definition. If neither the instance nor the definition provides a <description>, then the instance MUST NOT have a declared description.

<prop>

The optional <prop> element provides a structure for declaring arbitrary properties, which consist of a @namespace, @name, and @value.

This data element uses the same syntax as the <prop> allowed on a definition. When used on an instance, the set of properties MUST apply only to the instance.

Properties declared on the definition MAY be inherited by the instance. Metaschema does not define any general rules for how to handle overlapping and conflicting properties. How to handle these cases SHOULD be defined and documented for each property.

Naming and <use-name>

Similar to the <use-name> allowed on the referenced definition, the optional <use-name> on an instance changes the effective name to use for the information element in a compositional data model.

The <use-name> element is optional and MAY only occur once.

By default the effective name of the information element in a data model is taken from the effective name of the definition. The <use-name> value overrides this behavior for the instance only.

The first matching condition determines the effective name for the definition:

1. A <use-name> is provided on the instance. The effective name is the value of the <use-name> element on the instance.
2. A <use-name> is provided on the definition. The effective name is the value of the <use-name> element on the definition.
3. No <use-name> is provided on the definition. The effective name is the value of the @name attribute on the definition.

For example:

<define-flag name="flag-a">
  <use-name>flag-b</use-name>
</define-flag>
<define-field name="field">
  <flag ref="flag-a">
    <use-name>flag-c</use-name>
  </flag>
</define-field>

In the example above, the effective name of the flag instance is flag-c. If the <use-name> was omitted on the instance, the effective name would be flag-b. If the <use-name> was also omitted on the definition, the effective name would be flag-a.

The following content is valid to the model above.

{
  "field": {
    "flag-c": "value"
  }
}

---
field:
  flag-c: "value"

<field flag-c="value"/>

<remarks>

The optional <remarks> element provides a place to add notes related to the use of the instance. Remarks can be used to clarify the semantics of the instance in specific conditions, or to better describe how the instance may be more fully utilized within a model.

The <remarks> element is optional and may occur multiple times.

<flag> Instance

A flag instance is used to declare that a top-level flag definition is part of the model of a field definition or assembly definition.

Attributes:

Elements:

The attributes and elements specific to a <flag> instance are described in the following subsections. The elements and attributes common to all instance types are defined earlier in this specification.

The @ref attribute MUST reference a top-level flag definition’s @name that is in scope. See Definition Name Resolution for a detailed explanation of definition name scoping.

The following is an example of a flag instance.

1
2
3
4
5

<define-flag name="id"/>
<define-assembly name="computer">
  <root-name>computer</root-name>
  <flag ref="id" required="yes"/>
</define-assembly>

@required

The optional @required attribute declares if the flag is required to be provided in an associated content instance.

The following behaviors are REQUIRED to be used for each value of @required.

• no - Do not require the flag to be present in content. This is the default behavior when @required is not declared.
• yes - Require the flag to be present in content. Content missing the flag and its value will be considered invalid.

Model Instances

A model instance is used to declare a relationship to other information elements in an assembly definition’s model.

The following kinds of model instances can be declared as part of the assembly’s model.

• <field> - Instantiates a globally defined field definition as a model instance.
• <define-field> - Defines a single use field for use as a model instance.
• <assembly> - Instantiates a globally defined assembly definition as a model instance.
• <define-assembly> - Defines a single use assembly for use as a model instance.
• <choice> - Declares a mutually exclusive selection of child model instances.
• <any> - Declares a placeholder for extra content that is not described by an assembly definition’s model.

The <field>, <define-field>, <assembly>, and <define-assembly> model instance types are considered named model instances, since they all instantiate either a top-level or inline definition that represents a named information element within an assembly’s model.

The <choice> and <any> elements represent special constructs which differ significantly in their semantics from the named model instances.

These different types of model instances are discussed in the following subsections.

Named Model Instances

The <field>, <define-field>, <assembly>, and <define-assembly> model instance types are considered named model instances, which instantiate a definition within an assembly’s model.

The <field> and <assembly> elements are used to instantiate a referenced top-level definition.

The <define-field> and <define-assembly> elements are used to both declare a single use inline definition and also instantiate the declared definition.

Common Named Model Instance Data

All named model instances share a common common syntax composed of the following XML attributes and elements. This syntax builds on the common syntax and semantics shared by all instance types.

Attributes:

Elements:

The following subsections describe the XML attributes and elements that are specific to named model instances.

@max-occurs

The optional @max-occurs attribute declares the maximum cardinality bound for the named model instance, which defaults to 1.

This value can be either:

• a positive-integer value, representing a bounded maximum cardinality; or
• the unbounded value, representing a maximum cardinality with no upper bound.

@min-occurs

The optional @min-occurs attribute declares the minimum cardinality bound for the named model instance as a non-negative-integer value, which defaults to 0.

<group-as>

The <group-as> element is required if the @max-occurs attribute has a value greater than ‘1’ or is unbounded. This element provides additional information about how to handle the collection of data.

The group-as element has the following set of attributes:

@in-json

The optional @in-json attribute controls the representational form of a group of instances in JSON and YAML.

When the @in-json attribute and value are not provided, the value MUST default to SINGLETON_OR_ARRAY.

One of the following behaviors MUST be used based on the provided or default value.

@in-json="ARRAY"

TODO: P2: complete this section.

@in-json="SINGLETON_OR_ARRAY"

TODO: P2: complete this section.

@in-json="BY_KEY"

TODO: P2: Address issue https://github.com/usnistgov/metaschema/issues/316

@in-xml

The optional @in-xml attribute controls the representational form of a group of instances in XML.

When the @in-xml attribute and value are not provided, the value MUST default to UNGROUPED.

One of the following behaviors MUST be used based on the provided or default value.

@in-xml="GROUPED"

TODO: P2: complete this section.

@in-xml="UNGROUPED"

TODO: P2: complete this section.

@name

The REQUIRED @name attribute declares the grouping name to use in JSON, YAML and XML (when exposed).

In JSON and YAML, this name is used as the property name.

In XML, the specific use of the @name is based on the @in-xml attribute’s value.

Instance Naming

Given the set of instance names for a definition, a given instance on that definition MUST have a unique effective name. If the instance allows a maximum cardinality greater than 1, the <group-as name> MUST also be unique within the set of instance names for the definition.

For field instance values, the effective name of the value, based on a <json-value-key> or <json-value-key-flag> MUST also be unique within the set of instance names for the definition. This ensures that the property name for the field value is unique in JSON and YAML.

For field instances that use @in-xml="UNWRAPPED", no other effective instance name in the within the set of instance names for the definition MUST be named in a way that matches the allowed element contents of the markup-multiline data type in XML. This ensures that a naming clash with markup data is disallowed.

With these limitations, a model may be defined to contain any mix of fields and assemblies.

<field> Instance

A field instance is used to declare that a top-level field definition is part of the model of an assembly definition.

Attributes:

Elements:

The attributes and elements specific to a <field> instance are described in the following subsections. The elements and attributes common to all named model instance types are defined earlier in this specification.

The @ref attribute MUST reference a top-level field definition’s @name that is in scope. See Definition Name Resolution for a detailed explanation of definition name scoping.

@in-xml

TODO: P2: describe this with examples

<define-field> Instance

A <define-field> instance is a special type of field instance that also declares a new single use, inline field definition. It combines a subset of the data used to declare a field definition and a field instance.

The data model of the inline <define-field> instance is covered in the section of the specification discussing inline definitions.

<assembly> Instance

An assembly instance is used to declare that a top-level assembly definition is part of the model of an assembly definition.

Attributes:

Elements:

There are no attributes or elements specific to an <assembly> instance. The elements and attributes common to all named model instance types are defined earlier in this specification.

The @ref attribute MUST reference a top-level assembly definition’s @name that is in scope. See Definition Name Resolution for a detailed explanation of definition name scoping.

<define-assembly> Instance

A <define-assembly> instance is a special type of field instance that also declares a new single use, inline assembly definition. It combines a subset of the data used to declare a assembly definition and a assembly instance.

The data model of the inline <define-assembly> instance is covered in the section of the specification discussing inline definitions.

Other Model Instance Types

The elements <choice> and <any> are specialized model instance types that have different semantics from the name model instances above.

<choice> Selections

Permits the mutually exclusive use of a non-empty set of named model instances.

• <assembly> - Instantiates a globally defined assembly definition as a model instance.
• <field> - Instantiates a globally defined field definition as a model instance.
• <define-assembly> - Defines a single use assembly for use as a model instance.
• <define-field> - Defines a single use field for use as a model instance.

<any>

TODO: P2: describe this with examples