From 436f255b08a39b306e2d0f18c2c4b7dc381c8f5e Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Fri, 12 Aug 2022 12:57:44 -0400 Subject: [PATCH] Proposed metaschema docs updates (#50) * Feedback based on #1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. Co-authored-by: David Waltermire --- src/metaschema/metaschema-author.css | 114 +++++++++++++++ .../oscal_control-common_metaschema.xml | 24 +++- src/metaschema/oscal_profile_metaschema.xml | 135 +++++++++++++++--- 3 files changed, 246 insertions(+), 27 deletions(-) create mode 100644 src/metaschema/metaschema-author.css diff --git a/src/metaschema/metaschema-author.css b/src/metaschema/metaschema-author.css new file mode 100644 index 0000000000..333e9fb9e0 --- /dev/null +++ b/src/metaschema/metaschema-author.css @@ -0,0 +1,114 @@ +METASCHEMA { font-family: Georgia, serif } + +* { display: block } + +pre { color: darkgrey } + +tag { color: black; font-family: monospace; font-size: 80%; font-weight: bold } + +METASCHEMA { } + +title { } + +define-assembly, +define-field, +define-flag { margin-top: 1ex; margin-bottom: 1ex; border: thin inset black; padding: 0.5em } + + +define-assembly:before, +define-field:before, +define-flag:before + { content: + oxy_name() + oxy_textfield(edit, '@name', columns, 12) + } + + +define-assembly[group-as]:before, +define-field[group-as]:before, +define-flag[group-as]:before + { content: + oxy_name() + oxy_textfield(edit, '@name', columns, 12) } +define-assembly *, +define-field *, +define-flag * { margin: 0em } + +define-assembly > * { margin-top: 1em } + +allowed-values:before { content: "Allowed values" } +allowed-values { border: thin solid black; padding: 1em } + +enum:before { display: list-item } +enum:before { content: "enum" } + +pre { padding: 0.5em; background-color: gainsboro } + +define-assembly { } + +define-field { } + +define-flag { } + +flag { } + +formal-name { font-size: 120%; font-weight: bold; margin: 0.5em 0em } + +description, remarks { max-width: 60em } + +remarks { border-left: thin solid black; padding-left: 1em; margin-left: 1em } +remarks p { margin-top: 1em } + + +example { } + +prose { } + + +p { } + +code { display: inline; font-family: monospace } +q { display: inline; background-color: lemonchiffon } +em, i { display: inline; font-style: italic } +strong, b { display: inline; font-weight: bold } + +example { background-color: lavender; white-space: pre; } + +example *:before { content: '<' oxy_name() '>'; font-family: monospace; font-size: 80% } +example *:after { content: ''; font-family: monospace; font-size: 80% } + +model { padding-left: 0.5em; border-left: medium solid blue; font-size: 80%; padding-right: 2em } + +flag:before { content: + oxy_name() + ' ref: ' oxy_textfield(edit, '@ref', columns, 12) + } + +assembly:before, field:before { + content: + oxy_name() ' named ' + oxy_textfield(edit, '@ref', columns, 12) } + +group-as { margin-left: 2em } + +group-as:before { content: 'group as ' + oxy_textfield(edit, '@name', columns, 12) } + + +choice:before { content: + 'a choice between' + } + +prose:before { font-weight: bold; content: + 'prose' + } + +choice > * { margin-left: 2em } + +enum { display: block; font-size: 90%; padding-left: 1em } +enum:before { content: oxy_textfield(edit, '@value', columns, 24); } + +a { display: inline; color: blue } +a:before { content: oxy_urlChooser( + edit, "@href", + columns 42); } diff --git a/src/metaschema/oscal_control-common_metaschema.xml b/src/metaschema/oscal_control-common_metaschema.xml index e202be6317..7b0703775d 100644 --- a/src/metaschema/oscal_control-common_metaschema.xml +++ b/src/metaschema/oscal_control-common_metaschema.xml @@ -5,6 +5,7 @@ ]> + OSCAL Control Catalog Format -- Common Models @@ -35,7 +36,7 @@ Part Namespace An optional namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name. - +

Provides a means to segment the value space for the name, so that different organizations and individuals can assert control over the allowed names and associated text used in a part. This allows the semantics associated with a given name to be defined on an organization-by-organization basis.

An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.

When a ns is not provided, its value should be assumed to be http://csrc.nist.gov/ns/oscal and the name should be a name defined by the associated OSCAL model.

@@ -89,7 +90,11 @@

A part provides for logical partitioning of prose, and can be thought of as a grouping structure (e.g., section). A part can have child parts allowing for arbitrary nesting of prose content (e.g., statement hierarchy). A part can contain prop objects that allow for enriching prose text with structured name/value information.

-

A part can be assigned an optional id, which allows for internal and external references to the textual concept contained within a part. A id provides a means for an OSCAL profile, or a higher layer OSCAL model to reference a specific part within a catalog. For example, an id can be used to reference or to make modifications to a control statement in a profile.

+

A part can be assigned an optional id, which allows references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

+
    +
  • Referencing a part by id to tailor (make modifications to) a control statement in a profile.
    • +
  • Referencing a control statement represented by a part in a system security plan implemented-requirement where a statement-level response is desired.
    • +

Use of part and prop provides for a wide degree of extensibility within the OSCAL catalog model. The optional ns provides a means to qualify a part's name, allowing for organization-specific vocabularies to be defined with clear semantics. Any organization that extends OSCAL in this way should consistently assign a ns value that represents the organization, making a given namespace qualified name unique to that organization. This allows the combination of ns and name to always be unique and unambiguous, even when mixed with extensions from other organizations. Each organization is responsible for governance of their own extensions, and is strongly encouraged to publish their extensions as standards to their user community. If no ns is provided, the name is expected to be in the "OSCAL" namespace.

To ensure a ns is unique to an organization and naming conflicts are avoided, a URI containing a DNS or other globally defined organization name should be used. For example, if FedRAMP and DoD both extend OSCAL, FedRAMP will use the ns http://fedramp.gov/ns/oscal, while DoD might use the ns https://defense.gov for any organization specific name.

Tools that process OSCAL content are not required to interpret unrecognized OSCAL extensions; however, OSCAL compliant tools should not modify or remove unrecognized extensions, unless there is a compelling reason to do so, such as data sensitivity.

@@ -119,14 +124,15 @@ Parameter Class - A textual label that provides a characterization of the parameter. + A textual label that provides a characterization of the type, + purpose, use or scope of the parameter.

A class can be used in validation rules to express extra constraints over named items of a specific class value.

 Depends on - **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used. + (deprecated) Another parameter invoking this one. This construct has been deprecated and should not be used. @@ -140,7 +146,7 @@ Parameter Label A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned. -

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

+

The label value is intended use when rendering a parameter in generated documentation or a user interface when a parameter is referenced. Note that labels are not required to be distinctive, which means that parameters within the same control may have the same label.

 @@ -166,7 +172,9 @@ select -

A set of parameter value choices, that may be picked from to set the parameter value.

+

The OSCAL parameter value construct can be used to prescribe a specific parameter value in a catalog or profile. In cases where a prescriptive value is not possible in a catalog or profile, it may be possible to constrain the set of possible values to a few options. Use of select in a parameter instead of value is a way of defining value options that may be set.

+

A set of allowed parameter values expressed as a set of options which may be selected. These options constrain the permissible values that may be selected for the containing parameter. When the value assignment is made, such as in an OSCAL profile or system security plan, the actual selected value can be examined to determine if it matches one of the permissible choices for the parameter value.

+

When the value of how-many is set to "one-or-more", multiple values may be assigned reflecting more than one choice.

 @@ -178,7 +186,9 @@ An alternate to the value provided by the parameter's label. This will typically be qualified by a class. - The parent parameter provides an aggregation of 2 or more other parameters, each described by this property. + The parent parameter provides an + aggregation of two or more other parameters, each described + by this property. depends-on is deprecated diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index 7bf65b4fbe..5e9db88dfc 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -3,7 +3,7 @@ ]> - + OSCAL Profile Model @@ -13,8 +13,9 @@ http://csrc.nist.gov/ns/oscal

In OSCAL a profile represents a baseline of selected controls from one or more control catalogs. An OSCAL profile is used in an OSCAL system security plan (SSP) to determine the baseline of controls that must be implemented by the information system. The effective set of controls is generated through profile resolution.

-

A profile declares a set of selections and possible modifications of controls from one or more imported catalogs and/or profiles. When a profile is resolved, controls are selected from the imported catalog(s) for use by another profile or SSP. A profile may also be used for other purposes, such as documentation generation.

-

When a profile is used as input to the profile resolution process, it describes how the resulting catalog, representing a baseline, is structured and any alteration or tailoring to the resulting catalog structure and controls.

+

In OSCAL a profile represents a set of selected controls from one or more control catalogs. Such a set of controls can be referenced by an OSCAL system security plan (SSP) to establish a control baseline. This effective set of controls is produced from an OSCAL profile using a deterministic, predictable process called profile resolution.

+

A profile references one or more OSCAL catalogs or profiles to import controls from for control selection and tailoring. A profile can also describe how a resulting catalog is structured. When the profile is resolved, these selections and modifications are processed to produce a resulting OSCAL catalog.

+

OSCAL profiles have uses beyond establishing a baseline, such as documentation generation or as reference tables for validations.

 @@ -45,7 +46,7 @@ Import resource - The import designates a catalog or profile to be included (referenced and potentially modified) by this profile. The import also identifies which controls to select using the include-all, include-controls, and exclude-controls directives. + Designates a catalog or profile that defines controls for selection and tailoring by the profile. Catalog or Profile Reference A resolvable URL reference to the base catalog or profile that this profile is tailoring. @@ -92,7 +93,7 @@ Merge controls - A Merge element provides structuring directives that drive how controls are organized after resolution. + Provides directives for how controls are to be organized in the resulting catalog. Combination rule @@ -112,23 +113,20 @@ -

Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control).

-

This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (e.g. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.

-

If no combine element appears, it is considered equivalent to providing a combine element with a method of value keep.

- Flat - Use the flat structuring method. + Flat Without Grouping + Use the flat structuring method in profile resolution that directs that controls appear without any grouping structure. - As-Is Structuring Directive - An As-Is element indicates that the controls should be structured in resolution as they are structured in their source catalogs. It does not contain any elements or attributes. + Group As-Is + Indicates that the controls selected should retain their original grouping as defined in the import source. - Custom grouping - A Custom element frames a structure for embedding represented controls in resolution. + Custom Grouping + Provides an alternate grouping structure that selected controls will be placed in. @@ -145,8 +143,6 @@ -

The contents of the merge element may be used to reorder or restructure controls by indicating an order and/or structure in resolution.

-

Implicitly, a merge element is also a filter: controls that are included in a profile, but not included (implicitly or explicitly) in the scope of a merge element, will not be merged into (will be dropped) in the resulting resolution.

 @@ -169,7 +165,7 @@ Group Title - A name given to the group, which may be used by a tool for display and navigation. + A name to be given to the group for use in display. @@ -375,7 +371,7 @@ - Select controls + Select Controls Specifies which controls to use in the containing context. Order @@ -410,8 +406,8 @@ - Call - Call a control by its ID + Select Control + Select a control or controls from an imported control set @@ -426,10 +422,109 @@ +

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

 +<<<<<<< HEAD +======= + + Alteration + Specifies changes to be made to an included control when a profile is + resolved. + + + + + + + + + + +

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

+

Multiple alter constructs may not apply to the same control.

+ + + + Removal + Specifies objects to be removed from a control based on specific aspects of the object that must all match. + + Reference by (assigned) name + Identify items to remove by matching their assigned name + + + Reference by class + Identify items to remove by matching their class. + + + Reference by ID + Identify items to remove indicated by their id. + + + Item Name Reference + Identify items to remove by the name of the item's information element name, e.g. title or prop + + + Item Namespace Reference + Identify items to remove by the item's ns, which is the namespace associated with a part, or prop. + + +

Use by-name, by-class, by-id, by-ns or by-item-name (potentially in combination) to indicate by appropriate matching object to remove when the profile is resolved. The control affected is indicated by the control-idon the alter construct.

+

To change contents of a control, use remove to remove an object, then add to add it back again with the changes.

+ + + + Addition + Specifies contents to be added into controls, in resolution + + Position + Where to add the new content with respect to the targeted element (beside it or inside it) + + + Preceding the id-ref target + Following the id-ref target + Inside the control or id-ref target, at the start + Inside the control or id-ref target, at the end + + + + + Reference by ID + Target location of the addition. + + + + Title Change + A name given to the control, which may be used by a tool for display and navigation. + + + + + + + + + + + + + + + + + + + &allowed-values-control-group-property-name; + + + +

When no id-ref is given, the addition is inserted into the control targeted by the alteration at the start or end as indicated by position. Only position values of "starting" or "ending" are permitted when there is no id-ref.

+

id-ref, when given, should indicate, by its ID, an element inside the control to serve as the anchor point for the addition. In this case, position value may be any of the permitted values.

+ + +>>>>>>> a8c12d91f (Proposed metaschema docs updates (#50)) Include contained controls with control When a control is included, whether its child (dependent) controls are also included.