diff --git a/test-suite/oscal/v1.0.0/readme.md b/test-suite/oscal/v1.0.0/readme.md index d0437c1db..0a95a4fee 100644 --- a/test-suite/oscal/v1.0.0/readme.md +++ b/test-suite/oscal/v1.0.0/readme.md @@ -1,79 +1,3 @@ -# OSCAL Metaschema +# OSCAL Metaschema Examples -An OSCAL Metaschema defines the the information structures that define an OSCAL model in a format-neutral form. Documentation about the meaning (semantics) and use of a given metaschema structure is provided on the Metaschema [website]. - -OSCAL Metaschemas are used to generate other OSCAL artifacts based on the metaschema description. These artifacts include: - -- XML and JSON Schemas, or *data models*, are derived from the metaschema, expressed as XSD and JSON Schema; -- Conversion scripts that can convert OSCAL content between the XML and JSON OSCAL formats, ensuring the resulting content is schema valid; -- XML and JSON [model documentation](https://pages.nist.gov/OSCAL/docs/schemas/) for use on the [OSCAL website](https://pages.nist.gov/OSCAL). - -Use of Metaschemas in OSCAL allow us to maintain seamless and consistent support for multiple OSCAL model formats, including XML and JSON. Content can also be kept up-to-date in multiple formats using generated content converters, and can be validated using generated schema. Adding support for new formats (e.g., YAML) can accomplished by extending the Metaschema tooling to produce schema and converters for other formats. - -The Metaschema syntax (an XML application) is also described and constrained with its [own schema](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd), and with a [Schematron constraints set](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-check.sch). The latter is able to enforce some of the rules described below. - -#### Enumerated values - -Additionally, flags may be constrained to a set of known values listed in advance. - -This restriction can be either strict (values must be in the list for document validity) or loose (i.e. for documentation only, no effect in schemas). - -Use the `valid-values` element to restrict the permissible values for a flag. Set its attribute `allow-other='yes'` if the list is not exclusive. - -Within it `valid-values`, a `value` element's `@name` attribute assigns the permissible value, while its data content provides documentation. For example: - -```xml - - Hash algorithm - Method by which a hash is derived - - - - - - - ... -``` -## Metaschema modeling - -In the case of field and flag objects, the modeling constraints to be imposed by the result schemas (either XSD or JSON Schema) over the data set, can be determined on the basis of how they are described. Assembly definitions, however, permit not only flags to be assigned to assemblies of the defined type; additionally, they contain a `model` element for a *mode declaration*. This declaration names the subcomponents to be permitted (in documents valid to the target schemas) within any assembly of the type being defined. - -Five elements are used within `model` to define permissible contents of assemblies (elements or objects) being defined. Each of these represents a different object type. Flags are not assigned via `model` but directly in the definition; for the model, we can choose either singles or plurals of named fields or assemblies (i.e., a binary choice between cardinality constraints to be applied). This gives us four choices; additionally, we have the opportunity to use an element `prose`, once inside any assembly's model. - -Among these elements, no single `@named` attribute value (which refers a model component to its definition) may be used more than once. Additionally, no `@group-as` (on a `fields` or `assemblies`) may be reused or be the same as any `@named`. The `prose` element may be used only once. Finally, no value of `@named` or `@group-as` must be the same as a recognized name of an element directly within prose, namely (at present) `p`, `ul`, `ol`, and `pre`. - -With these limitations, a model may be defined to contain any mix of fields and assemblies. - -* `field` refers to a field definition and permits a single occurrence of the indicated field -* `field/@required='yes'` a field component is to be required in a model by any schema based on the metaschema -* `assembly` refers to an assembly definition and permits a single occurrence of the indicated assembly. -* `fields` - same as `field`, but permits the field to be repeated. In the JSON representation the multiple values are represented as any array unless `@address` is given -* `assemblies` - same as `fields`, but for assemblies. In JSON, this construct is also presented as an array unless there is an `@address` -* `prose` refers to a "region of prose", that is, a section of prose text of unspecified length. In XML, prose is represented in conventional fashion as (a sequence of) `

` and list elements (`