From 52b289a049651b80c57a991ce8762bdf42effc2d Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 7 Apr 2023 12:16:57 -0400 Subject: [PATCH] Continued work on the specification. Mostly through the define-assembly around line 810. --- website/content/specification/_index.md | 95 +++++++++++++++++-------- 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/website/content/specification/_index.md b/website/content/specification/_index.md index 3355fb56d..fbbf121c0 100644 --- a/website/content/specification/_index.md +++ b/website/content/specification/_index.md @@ -468,7 +468,7 @@ The `example` element is optional and may occur multiple times. A flag definition, represented by the `` element, is used to declare a reusable [flag](/specification/terminology/#flag) within a Metaschema module. -A flag definition provides the means to implement a simple, named [*information element*](terminology/#information-element) with a value. +A flag definition provides the means to implement a simple, named [*information element*](/specification/terminology/#information-element) with a value. {{}} Flag definitions are the primary leaf nodes in a Metaschema-based model. Flags are intended to represent granular particles of identifying and qualifying information. @@ -555,7 +555,7 @@ Elements: | [``](#remarks) | special | 0 or 1 | | [``](#example) | special | 0 to ∞ | -The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all definitions are [defined earlier](#common-definition-metadata) in this specification. +The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all definitions are [defined earlier](#common-definition-metadata) in this specification. ### `@as-type` @@ -757,19 +757,73 @@ TODO: complete this example. ## Top Level `` -The top level `` element represents a *flag definition* that defines a reusable [flag](terminology/#flag). +An assembly definition, represented by the `` element, is used to declare a reusable [assembly](/specification/terminology/#assembly) within a Metaschema module. + +An assembly definition provides the means to implement a complex, composite, named [*information element*](/specification/terminology/#information-element) that has no value. An assembly definition consists of an optional set of [*flags*](#flag) and an optional sequence of model instances, which are instances of assemblies and fields. + +{{}} +An assembly is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects that combine multiple information elements together into a composite object representing a larger semantic concept. The flag instances, typically characterize or identify this composite object, while the 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 `@as-type` attribute is not permitted on an assembly definition. +An assembly definition has no value, so the `@as-type` and `@default` attributes are not permitted. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@scope`](#scope) | `local` or `global` | optional | `global` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) or
[``](#root-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [`json-key`](#json-key) | special | 0 or 1 | +| [`json-value-key`](#json-value-key) or
[`json-value-key-flag`](#json-value-key-flag) | special | 0 or 1 | +| [`flag`](#flag-instance-children-1) or
[`define-flag`](#define-flag-inline-definition-1) | special | 0 or ∞ | +| [``](#model) | special | 0 or 1 | +| [``](#define-flag-constraints) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | +| [``](#example) | special | 0 to ∞ | + +The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all definitions are [defined earlier](#common-definition-metadata) in this specification. + +### `` + +### `` Instance Children + +A field may have zero or more flag instance children. + +See [flag instances](#flag-instances) + +### `` Inline Definition + +See [inline ``](#inline-define-flag). + +### `` Instances + +The `` element is used to reference the `field` and `assembly` components that compose the assembly's model. A `choice` element is also provided to define mutually exclusive model members. + +# Instances + +## Redefining the `` + +## Redefining the `description` -### `flag` Instances +The optional `description` element of the child `field` and `assembly` elements can be used to provide a different description for when the referenced component is used in the specified model context. -### Model Instances +## `flag` Instances -This element is used to reference the `field` and `assembly` components that compose the assembly's model. A `choice` element is also provided to define mutually exclusive model members. +## Model Instances -#### Using cardinalities and `group-as` +### Using cardinalities and `group-as` The child `field` and `assembly` elements share the following common set of attributes: @@ -812,19 +866,11 @@ Used to reference a `field-definition` who's `@name` matches the value of the `@ #### `choice` -#### Inline Definitions +##### Inline Definitions - do not allow `use-name` or `scope` -#### `any` - -### Root Assemblies - -## `` - -Use of `` for a `` is the same as for a ``. See [``](#json-key). - -## `@deprecated` version +##### `any` # Inline Definitions @@ -834,19 +880,6 @@ Use of `` for a `` is the same as for a `` -# Object Instance Syntax - -redefine formal-name - -Figure out how best to handle instances -## Redefining the `description` - -The optional `description` element of the child `field` and `assembly` elements can be used to provide a different description for when the referenced component is used in the specified model context. - - -## `flag` Instance - - ### XML Representational Form In XML, a flag instance is represented as an [attribute](https://www.w3.org/TR/xml/#attdecls).