<-- Assembly Instance -->
diff --git a/website/content/specification/syntax/constraints.md b/website/content/specification/syntax/constraints.md
index e20806adc..da8a05632 100644
--- a/website/content/specification/syntax/constraints.md
+++ b/website/content/specification/syntax/constraints.md
@@ -14,27 +14,25 @@ TODO: P3: Address issue https://github.com/usnistgov/metaschema/issues/325
## Enumerated values
-Additionally, flags may be constrained to a set of known values listed in advance.
+One kind of Metaschema constraint is restricting assembly, field, or flag value(s) with `allowed-values` enumerations. Metaschema processors MUST process `allowed-values` enumerations as defined with the `allow-other` attribute.
-This restriction can be either:
+1. When the `allow-other` attribute is defined as `allow-other="no"`, the processor MUST strictly validate content instances with enumerations: only defined `enum` values are valid for the given target(s).
+2. When the `allow-other` attribute is defined as `allow-other="yes"`, the processor MUST loosely validate content instances with enumerations: both `enum` values and other values are valid.
+3. When the `allow-other` attribute is not explicitly defined, the Metaschema processor MUST strictly validate content instances. The implied default is `allow-other="no"`.
-1. strict (values must be in the list for document validity with `allow-other="no"` attribute for an `allowed-values` element) or
-2. loose (i.e. for documentation only, no effect in schemas, with `allow-other="yes"`).
-
-If an `allowed-values` constraint does not have the `allow-other` attribute defined, the default is `allow-other="no"`, resulting in strict validation where the only valid values are those in the list.
-
-Within `allowed-values` of a `constraint`, an `enum` element's `@value` attribute assigns the permissible value, while its data content provides documentation. For example:
+Within `allowed-values` of a `constraint`, a Metaschema processor MUST strictly or loosely validate `enum` values with the `@value` attribute. A Metaschema processor MAY use the text value of the `enum`'s XML element as documentation for a given allowed value enumeration. Below is an example.
```xml
-
- Hash algorithm
- Method by which a hash is derived
+
+ Computer Form Factor
+ The type of computer in the example application's data model.
- Documentation for one permissible option.
- Documentation for another permissible option.
+ this text value documents the domain and information model's meaning of a laptop
+ this text value documents the domain and information model's meaning of a desktop
- ...
+ ...
+
```
## `define-flag` constraints
diff --git a/website/content/specification/syntax/definitions.md b/website/content/specification/syntax/definitions.md
index 5aa76c142..6a82d7193 100644
--- a/website/content/specification/syntax/definitions.md
+++ b/website/content/specification/syntax/definitions.md
@@ -8,7 +8,7 @@ weight: 20
A *definition* in a *Metaschema module* declares a reusable [*information element*](/specification/glossary/#information-element) within an [*information model*](/specification/glossary/#information-model).
-In graph theoretical terms, a *definition* provides a declaration of an graph *node* and any associated *edges* that form a given subgraph shape.
+In graph theoretical terms, a *definition* provides a declaration of a graph *node* and any associated *edges* that form a given subgraph shape.
In object-oriented terms, a *definition* provides a declaration of a *class*, along with any associated *class members*.
@@ -16,7 +16,7 @@ The following subsections describe the [common syntax](#common-definition-data)
## Common Definition Data
-All *definition* types share a common syntax comprised of the following XML attributes and elements.
+All *definition* types share a common syntax composed of the following XML attributes and elements.
Attributes:
@@ -61,7 +61,7 @@ The following example illustrates deprecating the flag named `flag-name` startin
The `@name` attribute provides the definition's identifier, which can be used in other parts of a module, or in an importing *Metaschema module*, to reference the definition.
-This attribute's value MUST be a [token](/specification/datatypes/#token) that is unique among sibling top-level flag definitions.
+In top-level definitions, this attribute's value MUST be a [token](/specification/datatypes/#token) that is unique among sibling definitions of the same type.
**Note:** The names of flags, fields, and assemblies are expected to be maintained as separate identifier sets. This allows a *flag definition*, a *field definition*, and an *assembly definition* to each have the same name in a given *Metaschema module*.
@@ -172,7 +172,7 @@ field:
The optional `` element provides a place to add notes related to the use of the definition. Remarks can be used to clarify the semantics of the definition in specific conditions, or to better describe how the definition may be more fully utilized within a model.
The `` element is optional and may occur multiple times.
-It supports an optional `@class` attribute that can be used to identify format specific specific remarks, to be handled appropriately (or ignored when not useful) in a downstream application. Valid values for `@class` are:
+It supports an optional `@class` attribute that can be used to identify format specific remarks, to be handled appropriately (or ignored when not useful) in a downstream application. Valid values for `@class` are:
- `XML`: The remark applies to the XML format binding.
- `JSON`: The remark applies to the JSON or YAML format bindings.
### ``
@@ -194,7 +194,7 @@ A *flag definition* provides the means to implement a simple, named [*informatio
The flag's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) identified by the `@as-type` attribute.
-The syntax of a flag is comprised of the following XML attributes and elements.
+The syntax of a flag is composed of the following XML attributes and elements.
Attributes:
@@ -245,12 +245,12 @@ A *field definition*, represented by the `` element, is used to de
A *field definition* provides the means to implement a complex named [*information element*](/specification/glossary/#information-element) with a value and an optional set of [*flag instances*](/specification/syntax/instances/#flag-instance).
{{}}
-A *field definition* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional set of *flag instances* declared on a *field definition*, typically characterize or identify the fields value. With optional use of flags, a field can be more or less complex, depending on the modeling need.
+A *field definition* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional *flag instances*, declared on a *field definition*, typically characterize or identify the field's value. With optional use of flags, a field can be more or less complex, depending on the modeling need.
{{}}
The field's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types) identified by the `@as-type` attribute.
-The syntax of an *field definition* is comprised of the following XML attributes and elements.
+The syntax of an *field definition* is composed of the following XML attributes and elements.
Attributes:
@@ -488,11 +488,11 @@ An assembly definition consists of an optional set of [*flags*](/specification/s
An *assembly definition* is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects, combining multiple information elements together into a composite object representing a larger semantic concept. An assembly's flag instances will typically characterize or identify this composite object, while its model instances represent the information being composed.
{{}}
-An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text". The contents permitted in a particular (type of) assembly are indicated in its `model` element.
+An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text." The contents permitted in a particular (type of) assembly are indicated in its `model` element.
An assembly definition has no value, so the `@as-type` and `@default` attributes are not permitted.
-The syntax of an *assembly definition* is comprised of the following XML attributes and elements.
+The syntax of an *assembly definition* is composed of the following XML attributes and elements.
Attributes:
diff --git a/website/content/specification/syntax/inline-definitions.md b/website/content/specification/syntax/inline-definitions.md
index 2e511c42d..fe3894b41 100644
--- a/website/content/specification/syntax/inline-definitions.md
+++ b/website/content/specification/syntax/inline-definitions.md
@@ -8,11 +8,11 @@ weight: 40
*Inline definitions* are a mechanism to both define a named [*information element*](/specification/glossary/#information-element) and instantiate it. In this way, *inline definitions* can be thought of as both [*definitions*](/specification/syntax/definitions/) and [*instances*](/specification/syntax/instances/), sharing most of the data elements of both.
-*Inline definitions* are provided as a convenience to allow single-use *information elements* to declared inline, within other *definitions*. Single-use, inline declarations are easier to maintain than a *top-level definition* that is referenced, since the maintainer doesn't have to trace the reference.
+*Inline definitions* are provided as a convenience to allow single-use *information elements* to be declared inline, within other *definitions*. Single-use, inline declarations are easier to maintain than a *top-level definition* that is referenced, since the maintainer doesn't have to trace the reference.
## Common Inline Definition Data
-All *inline definition* types share a common syntax comprised of the following XML attributes and elements.
+All *inline definition* types share a common syntax composed of the following XML attributes and elements.
Attributes:
@@ -47,9 +47,9 @@ A *inline flag definition* provides the means to implement a simple, named [*inf
An *inline flag definition* is a leaf node in a Metaschema-based model that is intended to represent a granular particle of identifying and qualifying information.
{{}}
-The flag's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) identified by the `@as-type` attribute.
+The flag's value is strongly typed using one of the built-in [simple data types](/specification/datatypes/#simple-data-types) identified by the `@as-type` attribute.
-The syntax of an *inline flag definition* is comprised of the following XML attributes and elements.
+The syntax of an *inline flag definition* is composed of the following XML attributes and elements.
Attributes:
@@ -83,12 +83,12 @@ An *inline field definition*, represented by the `` element, is us
A *inline field definition* provides the means to implement a complex named [*information element*](/specification/glossary/#information-element) with a value and an optional set of [*flag instances*](/specification/syntax/instances/#flag-instance).
{{}}
-An *inline field definitions* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional set of *flag instances* declared on an *inline field definition*, typically characterize or identify the fields value. With optional use of flags, a field can be more or less complex, depending on the modeling need.
+An *inline field definitions* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional *flag instances*, declared on an *inline field definition*, typically characterize or identify the field's value. With optional use of flags, a field can be more or less complex, depending on the modeling need.
{{}}
-The fields's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types) identified by the `@as-type` attribute.
+The fields's value is strongly typed using one of the built-in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types) identified by the `@as-type` attribute.
-The syntax of an *inline field definition* is comprised of the following XML attributes and elements.
+The syntax of an *inline field definition* is composed of the following XML attributes and elements.
Attributes:
@@ -131,14 +131,14 @@ A *inline assembly definition* provides the means to implement a complex, compos
An assembly definition consists of an optional set of [*flags*](/specification/syntax/instances/#flag-instance) and an optional sequence of [model instances](/specification/syntax/instances/#model-instances).
{{}}
-An *inline assembly definition* is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects, combining multiple information elements together into a composite object representing a larger semantic concept. An assembly's flag instances will typically characterize or identify this composite object, while its model instances represent the information being composed.
+An *inline assembly definition* is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects, combining multiple information elements together into a composite object representing a larger semantic concept. An assembly's flag instances typically characterize or identify this composite object, while its model instances represent the information being composed.
{{}}
-An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text". The contents permitted in a particular (type of) assembly are indicated in its `model` element.
+An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text." The contents permitted in a particular (type of) assembly are indicated in its `model` element.
An assembly definition has no value, so the `@as-type` and `@default` attributes are not permitted.
-The syntax of an *inline assembly definition* is comprised of the following XML attributes and elements.
+The syntax of an *inline assembly definition* is composed of the following XML attributes and elements.
Attributes:
diff --git a/website/content/specification/syntax/instances.md b/website/content/specification/syntax/instances.md
index 5adb09509..071d67d85 100644
--- a/website/content/specification/syntax/instances.md
+++ b/website/content/specification/syntax/instances.md
@@ -13,11 +13,11 @@ An *instance* is used to declare an information element *child* within a *parent
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 will never contain instances since flags have no children in the model, only values.
+- A flag definition never contains instances since flags have no children in the model, only values.
## Common Instance Data
-The [``](#assembly-instance), [``](#field-instance), and [``](#flag-instance) child elements share a common syntax comprised of the following XML attributes and elements.
+The [``](#assembly-instance), [``](#field-instance), and [``](#flag-instance) child elements share a common syntax composed of the following XML attributes and elements.
Attributes:
@@ -82,7 +82,7 @@ The instance type corresponds with the definition type as follows.
The optional `` element provides a human-readable, short string label for the instance for use in documentation.
-If provided, this formal name MUST override the `` declared on the corresponding definition, if a `` is declared there. If not provided, the effective formal name of the instance MUST be the `` declared on the definition. If neither the instance or the definition provide a ``, then the instance MUST NOT have a declared formal name.
+If provided, this formal name MUST override the `` declared on the corresponding definition, if a `` is declared there. If not provided, the effective formal name of the instance MUST be the `` declared on the definition. If neither the instance nor the definition provides a ``, then the instance MUST NOT have a declared formal name.
{{}}
The `` label is intended to provide an easy to recognize, meaningful name for the instance. This element can be used when the formal name of the instance differs in use from the formal name declared by the referenced definition.
@@ -94,7 +94,7 @@ While not required, it is best practice to include a `` when the us
The optional `` element is a [single line of markup](/specification/datatypes/#markup-line) 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 `` declared on the corresponding definition, if a `` is declared there. If not provided on an instance, the effective description of the instance MUST be the `` declared on the definition. If neither the instance or the definition provide a ``, then the instance MUST NOT have a declared description.
+If provided, this description MUST override the `` declared on the corresponding definition, if a `` is declared there. If not provided on an instance, the effective description of the instance MUST be the `` declared on the definition. If neither the instance nor the definition provides a ``, then the instance MUST NOT have a declared description.
{{}}
The description ties the instance to the related information element concept in the information domain that the instance is representing. This element can be used when the description of the instance differs in use from the description declared by the referenced definition.
@@ -116,7 +116,7 @@ A property is useful for annotating an instance with additional information that
### Naming and ``
-Similar to the [``](/specification/syntax/definitions/#naming-and-use-name) allowed on the referenced definition, the optional `` on a instance changes the *effective name* to use for the information element in a compositional data model.
+Similar to the [``](/specification/syntax/definitions/#naming-and-use-name) allowed on the referenced definition, the optional `` on an instance changes the *effective name* to use for the information element in a compositional data model.
The `` element is optional and MAY only occur once.
@@ -145,7 +145,7 @@ For example:
```
-In the example above, the *effective name* of the definition is `flag-c`. If the `` was omitted on the instance, the *effective name* would be `flag-b`. If the `` was also omitted on the definition, the *effective name* would be `flag-a`.
+In the example above, the *effective name* of the flag instance is `flag-c`. If the `` was omitted on the instance, the *effective name* would be `flag-b`. If the `` was also omitted on the definition, the *effective name* would be `flag-a`.
The following content is valid to the model above.
@@ -181,7 +181,7 @@ The `` element is optional and may occur multiple times.
## `` Instance
-A *flag instance* is used to declare that a top-level [*flag definition](/specification/syntax/definitions/#top-level-define-flag) is part of the model of a *field definition* or *assembly definition*.
+A *flag instance* is used to declare that a top-level [*flag definition*](/specification/syntax/definitions/#top-level-define-flag) is part of the model of a *field definition* or *assembly definition*.
Attributes:
@@ -228,7 +228,7 @@ The following behaviors are REQUIRED to be used for each value of `@required`.
A *model instance* is used to declare a relationship to other information elements in an assembly definition's model.
-There are 5 kinds of model instances, which can be declared as part of the assembly's model.
+The following kinds of model instances can be declared as part of the assembly's model.
- [``](#field-instance) - Instantiates a globally defined [field definition](/specification/syntax/definitions/#top-level-define-field) as a model instance.
- [``](/specification/syntax/inline-definitions/#inline-define-field) - Defines a [single use field](/specification/syntax/inline-definitions/#inline-define-field) for use as a model instance.
@@ -237,7 +237,7 @@ There are 5 kinds of model instances, which can be declared as part of the assem
- [``](#choice-selections) - Declares a [mutually exclusive selection](#choice-selections) of child model instances.
- [``](#any) - Declares a [placeholder for extra content](#any) that is not described by an assembly definition's model.
-The ``, ``, ``, `` model instance types are considered [*named model instances*](#named-model-instances), since they all instantiate either a [top-level](/specification/syntax/definitions/) or [inline](/specification/syntax/inline-definitions/) definition that represent a named information element within an assembly's model.
+The ``, ``, ``, and `` model instance types are considered [*named model instances*](#named-model-instances), since they all instantiate either a [top-level](/specification/syntax/definitions/) or [inline](/specification/syntax/inline-definitions/) definition that represents a named information element within an assembly's model.
The `` and `` elements represent special constructs which differ significantly in their semantics from the named model instances.
@@ -245,7 +245,7 @@ These different types of model instances are discussed in the following subsecti
## Named Model Instances
-The ``, ``, ``, `` model instance types are considered [*named model instances*](#named-model-instances), which instantiate a definition within an assembly's model.
+The ``, ``, ``, and `` model instance types are considered [*named model instances*](#named-model-instances), which instantiate a definition within an assembly's model.
The `` and `` elements are used to instantiate a referenced [top-level definition](/specification/syntax/definitions/).
@@ -253,7 +253,7 @@ The `` and `` elements are used to both declare a
### Common Named Model Instance Data
-All named model instances share a common common syntax comprised of the following XML attributes and elements. This syntax builds on the [common syntax and semantics](#common-instance-data) shared by all instance types.
+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](#common-instance-data) shared by all instance types.
Attributes:
@@ -306,9 +306,9 @@ The `group-as` element has the following set of attributes:
The optional `@in-json` attribute controls the representational form of a group of instances in JSON and YAML.
-When no attribute and value is provided for the `@in-json` attribute, the value MUST default to `SINGLETON_OR_ARRAY`.
+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 when no attribute and value is provided.
+One of the following behaviors MUST be used based on the provided or default value.
| Value | JSON and YAML Behavior |
|:--- |:--- |
@@ -331,9 +331,9 @@ TODO: P2: Address issue https://github.com/usnistgov/metaschema/issues/316
The optional `@in-xml` attribute controls the representational form of a group of instances in XML.
-When no attribute and value is provided for the `@in-xml` attribute, the value MUST default to `UNGROUPED`.
+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 when no attribute and value is provided.
+One of the following behaviors MUST be used based on the provided or default value.
| Value | XML Behavior |
|:--- |:--- |
@@ -371,7 +371,7 @@ For *field instances* that use [`@in-xml="UNWRAPPED"`](#in-xml-1), no other effe
With these limitations, a model may be defined to contain any mix of fields and assemblies.
{{}}
-In JSON, YAML, and XML, the [effective names of named instances](#naming-and-use-name) and the [grouping name](#group-as) of named model instances need to be restricted to allow for distinct naming of resulting JSON and YAML properties, and XML elements. By ensuring that names are unique, Metaschema aware parsers are able to map data elements in JSON, YAML, and XML into Metaschema module based *instances*.
+In JSON, YAML, and XML, the [effective names of named instances](#naming-and-use-name) and the [grouping name](#group-as) of named model instances need to be restricted to allow for distinct naming of resulting JSON and YAML properties, and XML elements. Uniqueness of names enables Metaschema aware parsers to map data elements in JSON, YAML, and XML into Metaschema module based *instances*.
{{}}
### `` Instance
@@ -437,7 +437,7 @@ Elements:
| [``](#group-as) | special | 0 or 1 |
| [``](#remarks) | special | 0 or 1 |
-There are no attributes and elements specific to an `` instance. The elements and attributes common to all named model instance types are [defined earlier](#common-named-model-instance-data) in this specification.
+There are no attributes or elements specific to an `` instance. The elements and attributes common to all named model instance types are [defined earlier](#common-named-model-instance-data) in this specification.
The [`@ref`](#ref) attribute MUST reference a top-level *assembly definition's* [`@name`](/specification/syntax/definitions/#name) that is in scope. See [Definition Name Resolution](/specification/syntax/module/#definition-name-resolution) for a detailed explanation of definition name scoping.
diff --git a/website/content/specification/syntax/module.md b/website/content/specification/syntax/module.md
index 752c36bad..692a22428 100644
--- a/website/content/specification/syntax/module.md
+++ b/website/content/specification/syntax/module.md
@@ -269,5 +269,5 @@ Both files contain globally scoped *flag definitions* named `global-flag`.
According to the rules above, the following is true.
-- The assembly named `imported-flags` uses the flag named `global-flag` from the `shadow-imported_metaschema.xml`. This is because definitions names are resolved in the local context of each model.
+- The assembly named `imported-flags` uses the flag named `global-flag` from the `shadow-imported_metaschema.xml`. This is because definition names are resolved in the local context of each model.
- The assembly named `importing-A` uses the flag named `global-flag` from the `shadow-importing_metaschema.xml`. This is because definitions declared in the current module shadow imported definitions.