Adding metaschema documentation. #16 usnistgov/OSCAL#596

website/content/specification/concepts/architecture-mermaid.md

@@ -0,0 +1,38 @@
+---
+title: "Metaschema Architecture using Mermaid"
+Description: "Source for the Metaschema Architecture diagram."
+sidenav:
+    activerenderdepth: 0
+---
+
+[Mermaid](https://mermaidjs.github.io/) is a notation for producing graphics from abstract node/network descriptions
+
+
+The following is the Mermaid notation for the chart above:
+
+```mermaid
+graph TB
+  ms1[module] -- include --> ms
+  ms2[module] -- include --> ms
+  xmp1[example] -- cite --> ms
+  xmp2[example] -- cite --> ms
+  ms[main Metaschema] -- compile metaschema --> cms
+  cms -- extract documentation --> xmldocsh[XML docs / HTML]
+  cms((Compiled metaschema)) -- translate --> sch(XML Schema)
+  cms -- xdm::object map --> xj{xml to json XSLT}
+  cms -- object::xdm map --> jx{json to xml XSLT}
+  cms -- translate --> jsch(JSON Schema)
+  cms -- extract documentation --> jsondocsh[JSON docs / HTML]
+
+classDef metasch fill:skyblue,stroke:blue,stroke-width:12px,stroke-opacity:0.2
+classDef xml fill:gold,stroke:#333,stroke-width:2px;
+classDef json fill:pink,stroke:#333,stroke-width:2px
+classDef html fill:lightgreen,stroke-width:2px
+classDef md fill:lightgreen,stroke-width:4px,stroke-dasharray:2,2
+
+class cms,ms,ms1,ms2,xmp1,xmp2 metasch
+class sch,xj xml
+class jsch,jx json
+class xmldocsh,jsondocsh html
+class xmldocmd,jsondocmd md
+```

website/content/specification/concepts/terminology.md

@@ -0,0 +1,103 @@
+---
+title: "Metaschema Terminology"
+Description: "Definitions of Metaschema Terms"
+---
+
+The following terminology is used in this specification:
+
+## Assembly
+
+An *assembly* is defined as follows:
+
+{{<callout>}}The [*information structure*](#information-structure) used to represent a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{</callout>}}
+
+An assembly does not have an associated value.
+
+An assembly may reference or directly define zero or more [*flags*](#flag).
+
+An Assembly has a model consisting of references to zero or more [*assemblies*](#assembly) or [*flags*](#flag).
+
+## Data Model (DM)
+
+A *data model*, abbreviated as DM, is defined as follows:
+
+{{<callout>}}A representation of an [*information model*](#information-model) in a format specific serializable form (e.g., XML, JSON, YAML) expressed in a format-specific schema definition syntax. The format-specific schema definition is generated within the Metaschema architecture from the [*metaschema-definition*](#metaschema-definition). These generated schema can be used to validate that data is conformant to the asscoiated format, and thus conformant to the *information model* defined by a given *metaschema defintion*.{{</callout>}}
+
+> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-4)), a data model is defined at a lower level of abstraction and include many details.
+
+> - Intended for implementors
+> - Include protocol-specific constructs.
+
+## Domain
+
+An *domain* is defined as follows:
+
+{{<callout>}}A specific area of knowledge, interest, and/or practice.{{</callout>}}
+
+## Flag
+
+A *flag* is defined as follows:
+
+{{<callout>}}A simple named data element with an associated scalar value. A *flag* is a simple [*information structure*](#information-structure) used to represent a part of a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{</callout>}}
+
+A *flag* is a pairing of a name and a value.
+
+A flag typically provides identifying or classifying information for the containing assembly or field.
+
+## Field
+
+A *field* is defined as follows:
+
+{{<callout>}}A complex named data element with an associated scalar or markup typed value and zero or more flags. A *field* is a complex [*information structure*](#information-structure) used to represent a part of a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{</callout>}}
+
+A field has a required value.
+
+A field may reference or directly define zero or more [*flags*](#flag).
+
+A field does not have a model.
+
+A field provides supporting information for the containing assembly.
+
+## Information Model
+
+An *information model*, abbreviated as IM, is defined as follows:
+
+{{<callout>}}A format-neutral description of a set of [*managed objects*](#managed-object) for a given [*domain*](#domain).{{</callout>}}
+
+> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-3)), an IM describes managed objects at a conceptual level, independent of any specific implementations or protocols used to transport the data.
+
+> - Level of abstraction depends on the modeling needs of the designers
+> - Define relationships between managed objects
+> - Should hide all protocol or implementation details, allowing for different implementations
+
+## Information Structure
+
+An *information structure* is defined as follows:
+
+{{<callout>}}A description of heirarchically related information elements, along with their cardinalities, representing a semanticly well-defined data structure.{{</callout>}}
+
+## Managed Object
+
+An *managed object* is defined as follows:
+
+{{<callout>}}A given concept within a specific [*domain*](#domain) consisting of a defined [*information structure*](#information-structure).{{</callout>}}
+
+A *managed object* is represented by an [*assembly*] in a [*metaschema definition*](#metaschema-definition).
+
+## Metaschema Definition
+
+An *metaschema definition* is defined as follows:
+
+{{<callout>}}A format for describing the [*managed objects*](#managed-object) in an [*information model*](#information-model) using Metaschema syntax. For each managed object, details are provided about its structure, meaning (semantics) and use.{{</callout>}}
+
+A metaschema definition consists of a few different types of information elements:
+
+- **Flag:** A named data element with an associated scalar value. A simple name / value pair.
+- **Field:** A complex named data element with an associated scalar or markup typed value and zero or more flags.
+- **Assembly:** A complex named data object, with no value, zero or more flags, and a complex model consisting of a combination of child fields and assemblies.
+
+![A metaschema definition is composed of flag, field, and assembly definitions. A flag has a value. A Field has a value and may associate zero or more flags. An assembly has no value, may associate zero or more flags, and has a model which may associate zero or more assemblies or fields.](../metaschema-information-elements.png)
+
+*Flags* and *fields* are leaf information elements that support the managed object.
+
+A metaschema definition is used as the basis for producing schema files, conversion files, documentation and utilities in support of that format. For any given model defined by a metaschema, the XML Schema (XSD) and JSON Schema will be consistent to a common information model because they are produced from the same metaschema definition.

website/content/specification/mapping/_index.md

@@ -0,0 +1,22 @@
+---
+title: "Mapping to XML, JSON, and YAML"
+Description: "Discussion of how Metaschema primatives map to XML, JSON, and YAML primatives"
+weight: 90
+---
+
+XML, JSON, and YAML each use specialized terminology and format primatives. As a notation for an object-based data, YAML is fairly similar to JSON, while XML is quite different to the other two. While all data format describe tree structures (directed graphs), each format (with its implicit data model) has its peculiar design, which requires specification in detail.
+
+For example, a data point represented as an attribute on an element in XML, for example, might be a string property on a data object in JSON. The metaschema moderates this distinction by providing rules regarding its own semantic constructs and how they are to be represented in the target format. As a result, a mapping between JSON and XML concepts is implicitly available through the corresponding metaschema.
+
+Within OSCAL models, all constructs are optional unless marked otherwise.
+
+| OSCAL Metaschema | XML | JSON and YAML |
+|------------------|-----|------|
+| Assembly | An element with element content |  An object, either a property or a member of an array property |
+| Field (with no flags) | A single element with text content | String property |
+| Field with one or more flags | An element with text content, flags as attributes |   An object property with a designated property for its nominal string value as well as properties for its flags |
+| Flag | Attribute | String property |
+| Flag with designated data type | Attribute with lexical constraints per type | String property with lexical constraints per type, or typed property such as `number` or URI (per type) | 
+| Field `as-type='simple-markup'`, no flags permitted | An element permitting mixed content inline | String property or map with string property, parseable as markdown (line only) |
+| Field `as='complex-markup'`, flag(s) permitted | An element permitting mixed content inline | Object property with `RICHTEXT` String property or object with string property, parseable as markdown (full blocks) |
+