A Metaschema module is represented using the top-level XML element
<?xml version="1.0" encoding="UTF-8"?> <METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"> <schema-name>Computer Model</schema-name> <schema-version>0.0.5</schema-version> <short-name>computer</short-name> <namespace>http://example.com/ns/computer</namespace> <json-base-uri>http://example.com/ns/computer</json-base-uri> <remarks> <p>This is an example model to describe the components of a computer.</p> <p>The "computer" element is the root element of this model.</p> </remarks> <!-- followed by a series of imports, then a series of definitions --> </METASCHEMA>
|Attribute||Data Type||Use||Default Value||Section|
|optional||Header: Abstract Module|
|version (||1||Header: Documentation|
|1||Header: XML Namespace|
|1||Header: JSON Base URI|
|special||0 or 1||Header: Documentation|
|special||0 to ∞||Module Imports|
|special||0 to ∞||Module Definitions|
The first set of elements in a Metaschema module represent the header, which contains information about the Metaschema module as a whole. The remainder of this section discusses the use of these elements.
<define-flag>elements first appear.
Top-level documentation for the Metaschema module appears in the the header section.
The header may include the following elements, in order:
@abstract attribute indicates if the Metaschema module is intended to be used on its own or only for import into another Metaschema module.
The following values describe the intent of
no- Indicates that the Metaschema module is usable on its own. This is the default behavior when
@abstractis not declared.
yes- Indicates that the Metaschema module is not usable on its own. Instead, the Metaschema module SHOULD only be imported by other Metaschema modules.
@abstract=yes. This communicates to users of the module that the module is not standalone.
<schema-name> is a line of structured markup that provides a human-readable name, suitable for display, for the information model represented by this Metaschema module.
A required, unique string literal value indicating the distinct version assigned to the Metaschema module.
This version MUST provide a means to distinctly identify a given revision of the Metaschema module in a series of revisions. The value child of the
<schema-version> SHOULD be a semantic version, which allows for automatically determining if a given version precedes, matches, or succeeds another version.
<schema-version>is encouraged, since semver provides a standardized set of rules for how version numbers are assigned and incremented. This allows computation over version ranges and comparison of individual versions.
This example defines a semantic version with a major version of
0, a minor version of
0, and a patch version of
A required, unique string literal value that identifies a series of revisions of the Metaschema module. Each revision in the series will have the same
<schema-version> provide an identification pair that uniquely identifies a given Metaschema module revision. This pair of values is intended to be associated with any schemas, code, tools, or other derivative artifacts produced from the Metaschema module, providing for clear identification of the revision from which an artifact is derived.
An optional sequence of multiline markup used to provide additional supporting notes related to the Metaschema module.
<remarks> element is typically used to include explanatory commentary of any kind.
<remarks> <p>This is an example model to describe the components of a computer.</p> <p>The "computer" element is the root element of this model.</p> </remarks>
<remarks>element is also permitted to appear elsewhere in the Metaschema module model. Its scope of application is tied to the location of use in the document. Thus, the top-level remarks relate to the entire Metaschema module, while remarks on a definition relate to the definition.
All information elements defined in the Metaschema module will be assigned to this namespace when handling related XML data.
The XML namespace defined using this element will be the target namespace used in an XML schema generated from this Metaschema module.
<import> element is used to import the definitions defined in another Metaschema module for use in the importing Metaschema module.
An import cycle occurs when a Metaschema module imports itself directly or transitively.
An example scenario is illustrated below.
In this example a cycle is created
A -> B -> A.
When processing imports, an implementation MUST be capable of detecting and generating a fatal error when an import cycle is found.
The top-level definition names exported by a Metaschema module are controlled by the top-level definition’s
@scope attribute. Definitions with a given Metaschema module without an explicit
@scope or with
@scope="global" are exported for use by other Metaschema modules that import it directly or transitively. The possibility of name conflicts arises when two modules have different definitions of the same type (i.e. flag, field, assembly) with the same name, and these modules are both imported.
The following rules MUST be applied to resolve naming conflicts that arise from module imports.
- A definition MUST be considered for import if the definition is in an imported module, and it either has no
@scope="global". A definition with
@scope="local"MUST be ignored.
- When a definition of a given type is imported, if its name matches the name of a previously imported definition of the same type, the most recently imported definition MUST be used.
- If a definition of a given type exists in the importing Metaschema module that matches the name of a previously imported definition of the same type, the definition in the importing Metaschema module MUST be used.
- Each module uses the resulting set of named definitions to resolve references within the module.
The following example illustrates how scoping affects definition name resolution.
The following file is the
This file declares the globally scoped assembly definition named
imported-flags (on line 8), which references the global scoped flag definition
global-flag (on line 12). It also declares the globally scoped flag definition named
global-flag (on line 20).
The following file is the
This file imports the
shadow-imported_metaschema.xml (on line 8). It also declares a global scoped assembly definition named
importing-A (on line 10), which references the flag definition
global-flag (on line 15). It also declares the globally scoped flag definition named
global-flag (on line 32).
Both files contain globally scoped flag definitions named
According to the rules above, the following is true.
- The assembly named
imported-flagsuses the flag named
shadow-imported_metaschema.xml. This is because definition names are resolved in the local context of each model.
- The assembly named
importing-Auses the flag named
shadow-importing_metaschema.xml. This is because definitions declared in the current module shadow imported definitions.