diff --git a/build/metaschema/lib/metaschema.xsd b/build/metaschema/lib/metaschema.xsd index 3129fc2ba1..67d4a9f162 100644 --- a/build/metaschema/lib/metaschema.xsd +++ b/build/metaschema/lib/metaschema.xsd @@ -108,6 +108,7 @@ + diff --git a/build/metaschema/metaschema-notes.md b/build/metaschema/metaschema-notes.md index 0e97487e60..c7b8c66806 100644 --- a/build/metaschema/metaschema-notes.md +++ b/build/metaschema/metaschema-notes.md @@ -1,6 +1,6 @@ # Metaschema Design and Terminology -OSCAL Metaschema is a descriptive format for the specification and support of OSCAL tagging. Each metaschema is used as the basis for producing schema files, conversion files, documentation and utilities in support of that format. For any given OSCAL format defined by a metaschema (such as **catalog** or **profile**), the XML Schema (XSD) and JSON Schema will be consistent because they are produced from the same source. +OSCAL Metaschema is a descriptive format for the specification and support of OSCAL tagging. A metaschema is used as the basis for producing schema files, conversion files, documentation and utilities in support of that format. For any given OSCAL format defined by a metaschema (such as **catalog** or **profile**), the XML Schema (XSD) and JSON Schema will be consistent because they are produced from the same source. However, the terminology used to describe data in either format will be different depending on whether XML or JSON is used. (As a notation for an object-oriented model, YAML will be similar to JSON.) While both data formats describe tree structures (directed graphs), each format (with its implicit data model) has its peculiar design, which requires specification in detail. 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 notation. Accordingly, a mapping between JSON and XML conceptual descriptions for any OSCAL format is possible, given the metaschema. @@ -10,16 +10,14 @@ Within OSCAL models, all constructs are optional unless marked otherwise. | OSCAL Metaschema | XML | JSON \| YAML | |------------------|-----|------| -| Assembly | A single element with element content (child of assembly element parent) | Object property (of parent assembly object) | -| Assemblies | A sequence of elements (element content) *each named as an individual* | Array property of parent object, with a key for the group, containing objects | +| 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 | Object property with `STRVALUE` String property, flags as other properties | -| Field `as='mixed'`, no flags permitted | An element permitting mixed content inline | String property, parseable as markdown | -| Field `as='mixed'`, flag(s) permitted | idem | Object property with `RICHTEXT` String property parseable as markdown | -| Fields | A sequence elements each for a single field (as above), named singly | Array property, with a key *for the group*, containing objects or strings as above (for fields with and without flags) | +| 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 type | Attribute with lexical constraints per type | String property with lexical constraints per type, or typed property such as `number` or URI (per type) | -| Prose | Sequence of markdown-convertible elements (`p`, `ul` etc.) | Array property with key=`prose` containing (markdown) strings | +| 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 | idem | Object property with `RICHTEXT` String property or object with string property, parseable as markdown (full blocks) | + ## Constraints imposed on the Metaschema diff --git a/build/metaschema/xml/produce-xsd.xsl b/build/metaschema/xml/produce-xsd.xsl index b76685d7d6..2d2ee2ffdc 100644 --- a/build/metaschema/xml/produce-xsd.xsl +++ b/build/metaschema/xml/produce-xsd.xsl @@ -82,28 +82,9 @@ - - - - - - - - - short name: - - - - - oscal-version: - - - - - - - - + + @@ -159,6 +140,9 @@ + + + @@ -252,15 +236,18 @@ - + + + http://csrc.nist.gov/ns/oscal/metaschema/1.0 @@ -268,7 +255,17 @@ - + + + http://csrc.nist.gov/ns/oscal/metaschema/1.0 + + + + + + + + diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml index c3f2b84c97..c4abb97adc 100644 --- a/src/metaschema/oscal_catalog_metaschema.xml +++ b/src/metaschema/oscal_catalog_metaschema.xml @@ -24,14 +24,14 @@ Catalog A collection of controls. - + - + - - + + Back matter including references and resources. @@ -88,16 +88,16 @@ Control Group A group of controls, or of groups of controls. - + - - - - + + + + - - + + @@ -120,16 +120,16 @@ Control A structured information object representing a security or privacy control. Each security or privacy control within the Catalog is defined by a distinct control instance. - + - - + + - - - - + + + + @@ -147,16 +147,14 @@ Sub-Control A control extension or enhancement - + - - The subcontrol's human-readable name. - - - - - + + + + + @@ -170,9 +168,9 @@ Parameter Parameters provide a mechanism for the dynamic assignment of value(s) in a control. - + - + A short name for the parameter. @@ -180,21 +178,9 @@

The label value should be suitable for inline display in a rendered catalog.

 - - A short summary of the parameter's intended use. - -

A label is optional, but should be provided unless a select (selection) is provided.

- - - - A rule describing the permissible parameter values. - -

Currently, OSCAL does not standardize any formal rules language for value constraints. A test option may be used to specify a formal rule that may be automatically used if recognized by an OSCAL tool. Further development is needed to support the declaration of a rule language and value.

- - - - Additional recommendations for the use of the parameter, or around what values should be provided. - + + + A recommended parameter value or set of values. @@ -209,9 +195,7 @@ - - - + @@ -230,7 +214,7 @@ Parameter description Indicates and explains the purpose and use of a parameter - + @@ -267,7 +251,7 @@ Presenting a choice among alternatives - + @@ -280,16 +264,16 @@ Part A partition or component of a control, subcontrol or part - - + + - + - - + + @@ -308,17 +292,17 @@ - + Constraint test A formal (executable) expression of a constraint - - + + Cardinality When selecting, a requirement such as one or more - - + + Depends on Another parameter invoking this one diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml index 0adafb93d2..ca70ca6d3b 100644 --- a/src/metaschema/oscal_metadata_metaschema.xml +++ b/src/metaschema/oscal_metadata_metaschema.xml @@ -31,15 +31,15 @@ Publication metadata Provides information about the publication and availability of the containing document. - + - - - - - - + + + + + + @@ -49,8 +49,8 @@ A collection of citations and resource references. - - + +

Provides a collection of identified citation and resource objects that can be referenced by a link with a rel value of "reference" and an href value that is a fragment "#" followed by a reference to a citation identifier. A citation can reference a resource by specifying a local target value using the same fragment-identifier approach.

@@ -229,7 +229,7 @@ - + @@ -251,12 +251,12 @@ Affiliated organization - - - - - - + + + + + + @@ -267,11 +267,11 @@ - - - - - + + + + + @@ -353,7 +353,7 @@ - + @@ -434,7 +434,7 @@ - + @@ -543,10 +543,10 @@ A citation to resources, either external or internal (by means of internal cross-reference). - + - + diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index a8b5f6ff73..bb2205f881 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -23,8 +23,8 @@ Each OSCAL profile is defined by a Profile element - - + + @@ -121,9 +121,9 @@ A Custom element frames a structure for embedding represented controls in resolution. - - - + + + @@ -138,9 +138,9 @@ As in catalogs, a group of (selected) controls or of groups of controls - - - + + + @@ -148,8 +148,8 @@ Modify controls Set parameters or amend controls in resolution - - + + @@ -160,8 +160,8 @@ - - + + @@ -239,8 +239,8 @@ imported - - + + @@ -253,20 +253,23 @@ Parameter Setting A parameter setting, to be propagated to points of insertion - + + Parameter ID + Value of the 'id' flag on a target parameter + - - + + - - + + @@ -276,8 +279,8 @@ - - + +

Use @control-id or @subcontrol-id to indicate the scope of alteration.

@@ -311,10 +314,10 @@ - - - - + + + + @@ -342,10 +345,6 @@ Control ID Value of the 'id' flag on a target subcontrol - - Parameter ID - Value of the 'id' flag on a target parameter - Pattern A regular expression matching the IDs of one or more controls or subcontrols to be selected @@ -382,19 +381,5 @@ References by name Items to remove, by item type (name), e.g. title or prop - - - - - - Depends on - Another parameter invoking this one - diff --git a/src/metaschema/readme.md b/src/metaschema/readme.md index 5960e20a60..62578bcad5 100644 --- a/src/metaschema/readme.md +++ b/src/metaschema/readme.md @@ -50,14 +50,17 @@ The following is the Mermaid notation for the chart above: ``` graph TB - ms -- extract documentation --> xmldocsh[XML docs / HTML] - xmldocsh -- generic HTML to md --> xmldocmd[XML docs / md] - ms((Metaschema)) -- translate --> sch(XML Schema) - ms -- xdm::object map --> xj{xml to json XSLT} - ms -- object::xdm map --> jx{json to xml XSLT} - ms -- translate --> jsch(JSON Schema) - ms -- extract documentation --> jsondocsh[JSON docs / HTML] - jsondocsh -- generic HTML to md --> jsondocmd[JSON-flavored docs / md] + 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; @@ -65,7 +68,7 @@ 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 ms metasch +class cms,ms,ms1,ms2,xmp1,xmp2 metasch class sch,xj xml class jsch,jx json class xmldocsh,jsondocsh html @@ -89,15 +92,15 @@ Nonetheless and with this in mind, understanding the mechanism by which the Meta Terminology note: "metaschema" is a common noun and there are many metaschema technologies (indeed almost any mature XML tag set has one), with different purposes, feature sets and capabilities. "Metaschema" (capitalized) is our peculiar homegrown metaschema technology and application. -## The Overall Approach +## The Approach A reduced, lightweight modeling language with certain specially-enforced constraints can be sketched such that multiple schemas constraining disparate formats, such as XML and JSON, can be produced from a single metaschema instance (a document written in Metaschema) deterministically, and thus designed and coordinated in parallel. We begin by producing functioning schemas to describe OSCAL data in XML Schema Definition Language (XSD) 1.1 on the XML side and JSON Schema draft7 on the JSON side. As we do this, the constraints imposed by using the Metaschema modeling syntax enable us to do two things implicitly (that is, without any further effort or additional cost or planning): -- Limit ourselves to schema constructs that map cleanly into features offered by both (target) schema technoologies, thus ensuring that all information can be preserved in (lossless bidirectional) conversion. +- Limit ourselves to schema constructs that map cleanly into features offered by both (target) schema technologies, thus ensuring that all information can be preserved in (lossless bidirectional) conversion. -- Mediate between the "structural imbalances" in the data formats by providing the extra information we need to introduce improvements to model and syntax on both sides. By "model and syntax" we mean everything bearing on both the information sets to be represented, and their (canonical or recognized) representations, including object structures, notations and data type bindings. Beyond the applicable metaschema, no further inputs and no reliance on arbitrary conventions or runtime settings should be necessary to produce, reliably, correspondent JSON from any (metaschema-described, schema-valid) XML, and vice-versa. +- Mediate between the structural imbalances in the data formats by providing the extra information we need to introduce improvements to model and syntax on both sides. By "model and syntax" we mean everything bearing on both the information sets to be represented, and their (canonical or recognized) representations, including object structures, notations and declarations of data type bindings. Beyond the applicable metaschema, no further inputs and no reliance on arbitrary conventions or runtime settings should be necessary to produce, reliably, correspondent JSON from any (metaschema-described, schema-valid) XML, and vice-versa. - Additionally, (and this is crucial) produce specifications and running code supporting automated production of schemas and model-related artifacts, consistent with the circumscribed model defined (and documented) in the Metaschema. @@ -121,23 +124,28 @@ Top level documentation for the Metaschema instance appears in the header sectio The root element is `METASCHEMA` using all capitals. To name the root element in all capitals (unlike the general rule) and to give it a name somewhat peculiar to its application, retains and expresses the information that it is intended to be the document root. This is the only element named in all caps. -`METASCHEMA` may take two attributes, `@use` and `@top`. `@use` must be equal to the `@name` assigned to an assembly definition in the schema. `@top` must be equal to the `@group-as` on the same definition. (This is the first instance of the Metaschema tactic of "strategic redundancy" in naming and managing its various components. While in principle, we would be able to infer each of these values from the other, we require both to be expressed in order to confirm the integrity of the binding.) - -Note the assembly definition indicated by @use will be expected to apply to the root or virtual root for the conformant XML or JSON data set. +`METASCHEMA` indicates the root element or object for the schema with its `@root` attribute, which must correspond to the `@name` of one of the (assembly) definitions in the metaschema. ## Metaschema header In addition to the top-level attributes `@use` and `@top`, the top of the metaschema may include these elements, in order: - ### schema-name Describing the scope of application of the data format, for example "OSCAL Catalog". +### schema-version + +A literal value indicating the version to be assigned to schemas and tools produced from the Metaschema. + ### short-name A coded version of the schema name, for use when a string-safe identifier is needed, for example on artifact file names. Expect this short name to be propagated anytime such a "handle" is needed. A short name for the OSCAL Catalog metaschema (and schemas) might be `oscal-catalog`. +### namespace + +An XML namespace identifier (URI) to be used for the resulting XSD. All elements in the metaschema will be assigned to this namespace, including elements defined in metaschema modules, that are designated with their own namespaces. (In other words, this data value is operative only for the top-level metaschema, not for any of its imported modules. This makes it possible to use modules in metaschemas defined with different namespaces.) + ### remarks Paragraphs describing the metaschema. @@ -154,7 +162,7 @@ There are three kinds of definitions: ### Fields -Fields can be thought of as simple text values, either scalars or sequences of scalars, or when appropriate, of "rich text", i.e. text permitting inline formatting. Depending on modeling requirements, fields may also be used for even simpler bits of data, such as objects that carry specialized flags but have no values or structures otherwise. +Fields can be thought of as simple text values, either scalars or sequences of scalars, or when appropriate, of "rich text" or mixed content, i.e. text permitting inline formatting. Depending on modeling requirements, fields may also be used for even simpler bits of data, such as objects that carry specialized flags but have no values or structures otherwise. This means that fields can be more or less complex, depending on the need. This distinction is made by qualifying the `field` with an `@as` attribute, as follows: