These specifications describe how to render an OSCAL profile document in
- the form of an OSCAL catalog. We call this
This specification provides the minimal requirements for processing an OSCAL Profile to create a new OSCAL Catalog Document. This process of applying a profile to a catalog to create a new catalog is called
+
This document defines the normative requirements for an OSCAL Profile Resolver. Profile resolution is core to addressing a fundamental OSCAL requirement: + the representation of baselines separately from the control catalogs on which they depend). The requirements for resolution must therefore be well-defined and deterministic, + enabling tool developers and parties exchanging OSCAL Profiles can work from a common understanding.
+ +No requirements are placed on implementation-level details, instead, requirements are laid out as what the output of resolution must look like given a certain input. + By adhering to these requirements OSCAL producers, OSCAL consumers, and any other members of the OSCAL ecosystem can create and resolve profiles deterministically, + with repeatable results, regardless of the tool used.
+These DRAFT specifications take the form of a tag set mapping between the OSCAL
- element
and attribute
, with
- examples given using XML syntax: these however are for illustrative purposes only and
- normative only with respect to the semantic mapping, not the syntax as such. The XML
- orientation of the specification of this mapping is an expediency; in the longer term we
- plan specifications that are format-agnostic.
In these specifications there are references to
Elements in the source format are marked in these specifications to appear distinctively as
- source-element
).
Elements in the target format are marked in these specifications to appear distinctively as
- target-element
).
The term
The term
In contrast to profiles, catalogs do not contain directives but instead, representations of
- security controls and their parts, optionally gathered in groups, on which directives are
- assumed to operate. There is one exception: the OSCAL semantics
as opposed
- to the domain-specific semantics of the information it handles – requires that it express
- what is to be done and how.
correct
order of elements or
- objects as defined by an OSCAL format such as the catalog or profile models. That is, the
- respective schemas of these models enforce order to the extent it is meaningful; where it is
- not (for example, in the ordering of properties on objects in JSON), a metaschema can
- nevertheless be referenced to provide an order.
So for example, on a JSON object, a first links, then parts
,
- being defined by the model, becomes invariant across instances and thus insignificant.
Canonical order is important since there are occasions when, in order to produce valid - outputs in XML, a profile resolver must resequence items. This may happen any place where - the natural or intrinsic order resulting from splicing sequences in original order is not - correct.
-Finally, this specification describes not only (source) profiles and (target or result)
- catalogs, but
For illustrative purposes, these control selections are, like source and target formats, - also represented by tagging in examples given here, and described as intermediate targets, - even though no OSCAL processor is obliged to produce or recognize such XML at any point, as - long as it produces the same results (final outputs) from the same inputs.
-must
- required
and shall
. At present (time of writing) an editorial pass to ensure
- this consistency has not been conducted.
Additionally, in these specifications XPath notation is used to identify elements and - attributes in the XML. A summary of some lightweight XPath syntax:
+Many core OSCAL concepts are defined on the OSCAL Terminology Page. The most important are repeated in this document, but readers should verify their understanding of all core OSCAL terms before reading this document.
+Additionally, many terms in the wider domain have overloaded definitions. Unless defined otherwise by OSCAL or explicitly in this document, terms are to be understood as defined in the NIST CSRC Glossary.
+
@
) indicates an attribute named
-
+
+
val.
+
+
Examples given to illustrate targets for particular source (example) inputs are given, like
- the source, in XML notation. Sometimes, however, the expected outputs are not defined by the
- inputs given and not literally present. In these cases, a description of the dynamic
- (variable) contents in curly braces
So for example where a property is added to target
This indicates the { timestamp }
. In display, these values should also be shown with special
- formatting as shown here.
Such highlighting is also used to indicate the beginning and end of nominal or implicit
- structures described in these specifications (mainly
XML examples also indicate unspecified content using a simple …
(elision)
- character, typically for more verbose chunks of target data whose production is specified
- elsewhere in the document.
Finally, although examples are syntactically faithful to OSCAL, they are not necessarily
- always formally valid in every respect. For example, OSCAL defines permissible, recognized
- values for property names (pending, for
- example, as sometimes shown in this documentation). Examples are given for purposes of
- illustrating profile resolution semantics only, and should not be taken as normative for any
- actual use.
A catalog
and its profile
, the latter being a selection,
- adaptation and organization of controls, as distinct from the catalog from which those
- controls are derived.
However, profiles may also select controls from profiles, thus deriving them from - underlying catalogs as modified by those profiles. This feature enables an organization that - wishes to promulgate guidelines or requirements to do so by publishing a set of - customizations to an existing catalog, rather than create a catalog from scratch. Profiles - can also arrange combinations of controls from more than one catalog or profile origin, - making it possible to use them to support the creation of hybrid catalogs.
-In the general case OSCAL must support sourcing more than one catalog at once, in order to - aggregate and organize controls from disparate sources. For example, it should be routine - for a profile to acquire its controls from an authoritative standard catalog, plus a local - supplement. But multiple catalog inputs, especially when they are produced and sourced - independently of one another, may not combine without issues. In order to provide sensible - and transparent results even for incoherent inputs, this specification defines these - processes such that legible and testable results are produced even when they are formally - invalid to constraints governing the outputs. Such downstream processing errors including - validation errors are expected to be detectable and remediable. This especially applies to - situations where multiple catalogs are sourced, or where the same catalog is sourced more - than once, directly or indirectly.
-In order to support these semantics – because whatever data set is sourced by a profile, it
- must look like a catalog
– the results of resolving a single profile must be in the
- form of a single catalog. Two different OSCAL processors that promise profile resolution,
- must deliver, for the same input, the same catalog with regard to its contents: which
- controls are included; their ordering (insofar as the target format represents ordering);
- and the structure (groups) in which they are embedded. This specification is designed to
- make this possible, by defining outputs with sufficient rigor that the same
is
- meaningful and testable in this context.
A profile is a representation of a delta, a here to there
. As such, a profile might
- be conceived of as a recipe or instruction set – a sequence of steps or procedures – whereby
- to create an OSCAL catalog (set of controls describing security requirements) from an OSCAL
- catalog (set of controls describing security requirements). The primary use case for this is
- when we need to make a new catalog to apply to a system or set of systems, starting from a
- canonical, received, mandated or standard catalog with a more general scope.
This is because although catalogs - for example, the controls described in NIST SP 800-53 -
- are published, available for use, and even standardized, they can never be used exactly in
- the form in which they are acquired. They must be taken from the packaging and placed into
- operational context before they mean anything. This typically requires that a few operations
- over raw catalogs
be supported by a profiling mechanism. We must be able to select
- controls; we must be able to arrange them in order (or not); and we must be able to qualify
- or condition them by setting parameters defined for them and making adjustments to them.
By representing the steps by which a base catalog can be sliced, sifted, amended and - edited, into a (nominally) finished or ready set of control requirements, a profile makes it - easier to codify and preserve even very incidental or temporary local revisions of a control - catalog. Once expressed as a profile in OSCAL format, a set of emendations to a catalog can - be managed entirely separately and independently from the catalog. Because a conformant - processor can always create the customized catalog by resolving the profile against its - sources (executing the transformation described in this document), the profile can also be - examined and used as a proxy for that catalog for other purposes. The customized catalog can - be made available wherever and for whatever purposes it is needed, while its revision and - maintenance can be focused on the profile.
-This separation of concerns - between the originating catalog authors, who describe policy
- in only general terms, and the authors of the user manual
catalog, who must describe
- policy in very particular and local terms - is a necessary factor in supporting sustainable
- processes with the potential for automation and process improvement. An OSCAL profile
- bridges the gap between a set of general guidelines, and actionable rules. Only by examining
- the system in the context of the actual intentions appropriate to that system, can we
- properly assess its security. Profiles make this possible.
In order for this to work however we need a process that can perform the necessary - operations, to apply the delta to an unmodified catalog, to produce the local view of the - catalog as modified. This is profile resolution.
-In an XML context, document validation is available as a means of determining whether an
- arbitrary XML document entity conforms to structural and naming constraints such as must be
- assumed by processors respecting application semantics. These specifications assume that XML
- inputs for profile resolution will be schema-valid with respect to the OSCAL
- http://csrc.nist.gov/ns/oscal/1.0.
Similarly, the definition of the output format or results, is constrained by the OSCAL
-
As described above, correct
- order of elements or objects as defined by an OSCAL format such as the catalog or profile
- models. That is, the respective schemas of these models enforce order to the extent it is
- meaningful; where it is not (for example, in the ordering of properties on objects in JSON),
- a metaschema can nevertheless be referenced to restore an order.
So for example, on a JSON object, a first links, then parts
is
- defined by the model, with the consequence that it can be represented as such even when an
- underlying representation (such as a compiled JSON object) does not encode that relationship
- natively.
There are occasions especially when control contents are altered or amended, when a
- straightforward representation of elements in their original order, or in two sequences
- spliced together (say, the parts of a control, followed by new properties for the same
- control, added by the profile), would be invalid, which is to say not conformant with
- canonical order. In general the rule in these cases is, in resolution, to reorder the
- elements.
For any given element (defined as an assembly in the metaschema), the canonical order is
- given by its model. So for example the canonical order for contents of a catalog is
-
In addition to those described and enforced by the respective schemas, there are additional
- constraints over the data that this process relies on. The most important of these is
- ID-distinctiveness. Every
In this context, defined processing scope
includes a profile along with all profiles
- and all catalogs it imports, directly and indirectly. Many arrangements are possible in
- which a single catalog provides controls to more than a single branch on the import tree. In
- profiles where this occurs, distinct imports must identify discrete, non-intersecting, sets
- of controls, or clashes occur. Additionally, clashes may naturally occur through implicit
- copying of parameters from multiple imports.
OSCAL profiles provide three different modes for handling clashing controls or replicas in
- general, where keep
(also the default), use-first
and merge
.
A central problem in profile resolution is determining when two controls are both
- representations of the same
control, even when those representations have dissimilar
- contents or come to a profile through different import pathways.
For purposes of profile resolution, control identity (or parameter, group identity etc.)
- can be determined by any of several ways, depending on the
strict - control ID only - ordinary mode for well-controlled inputs
+
+
diagnostic - control ID + provenance identifier
+
+
maintenance - control ID + provenance + class (version etc)
+
+
none - no identification (each input control is distinct) - for tracing
+
+
It is frequently possible by static analysis to detect many conditions even in schema-valid
- profile documents, that will result in problematic catalogs in resolution. The most common
- issue will be clashing controls, that is more than one control in underlying catalogs with a
- given identifier (ID), making references to such controls ambiguous. The
Inasmuch as the target of profile resolution is a catalog, the resulting document is expected - to be a catalog document as specified by OSCAL, conforming to the applicable schema, XSD in - the case of OSCAL XML or JSON Schema for OSCAL object serialization formats.
-These two approaches to validation do not constrain their respective data models – although - OSCAL-equivalent – in exactly the same way. In particular, element structures in the XML may - be represented in JSON by either objects, or arrays of objects, depending on the respective object's - OSCAL definition; and where objects appear outside arrays, ordering semantics cannot be respected (whereas in XML, order among nodes is - always an intrinsic property of the graph).
-Consequently, where these specifications dictate that targets appear in order, it must be
- understood that what is described is both (a) the order in XML, and (b) the
-
The output of a profile resolution should take the form of a catalog. Catalog results (the - output of a conformant profile resolution) will be valid to the OSCAL catalog schema.
- At its base, an OSCAL
A valid catalog must have
Although the target of profile resolution takes the form of a catalog, it may not be valid
- to all constraints that define the OSCAL catalog format, whether enforced by its schema or
- by other means such as Schematron. Specifically, while a correctly implemented profile
- resolution may produce a result catalog that is structurally valid, there is a mode of
- operation, namely the
If the merge behavior is set to
Because document IDs are sometimes used to distinguish data points in processing context, a - resolved profile may not present the same ID as any of the catalogs it is importing, or the - same ID as its source profile.
-It is permitted to produce the profile’s ID in resolution via a static mapping from the ID
- of the source. For example, the resolution of profile with ID profile-X might
- have ID profile-X-RESOLVED.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in + BCP 14 + [RFC2119] + [RFC8174]when, and only when, they appear in all capitals, as shown here. +
Metadata in the target is derived directly from the source metadata, with modifications.
- With the exceptions given, elements inside
Because of options in producing metadata and especially the requirement for a timestamp,
- developers and users should note that two different resolutions of the same profile will
- not, ordinarily, be identical inside
The catalog document resulting from profile resolution may have a new timestamp,
- reflecting its time of resolution (when the process was invoked, or executed, or when
- its outputs were serialized). This is captured in the required element
-
Processors have the option of assigning this value sensibly in operational context. In
- general, the earliest "actual" (i.e., not predated) time warranted by the facts, is to
- be preferred. For example, a profile resolver that periodically refreshes a catalog of
- baselines, may determine that a profile is unchanged (despite changes in underlying
- catalogs), and does not require a new
Optionally, a source-profile-last-modified
may be added to the resolution target metadata with
- a valid timestamp capturing the stated
The presence of this property with a valid timestamp may be taken as an indicator that
- an OSCAL
The new link should have two flags (attributes):
-resolution-source
OSCAL supports a variety of serialization formats, each of which having it's own benefits and drawbacks. In this document, YAML (YAML Ain't Markup Language) is used to represent the various objects of the
+
YAML maps cleanly to JSON, thus allowing easy use of existing JSON/XML transformers where needed. With that in mind, the + OSCAL Complete JSON Referenceis a valuable resource for understanding the YAML-based information structures used in this document. All JSON properties and objects defined in the reference equate to a YAML mapping, list, or dictionary. +
The construction of the body of the target catalog is described in the next section.
The body of the target
YAML is a particularly human-readable format. For those unfamiliar with the format, the basics:
If no no merge
. Note that the same
- no
- merge
, as is
or custom
) can work with any combination method
- (keep
, use-first
or merge
).
Conforming with canonical order, the target catalog has a content model as follows
- (metadata, param*, control*,
- back-matter?)
Each line is a key-value pair, presented as
+ key:value, or as
+ key:with any number of list items on the following lines.
+
If
Conforming with canonical order, the target catalog has the content model
- (metadata, param*, control*, group*, back-matter?) where
- group has the model (title?, prop*, part*, param*, control*,
- group*).
Indentation, spacing, and white space matters. Items below a key and indented one level in are members (or children) of that key.
If
List items are represented with a preceding dash
+ - listitemkey:value.
+
Unless it be for special purposes in a debugging or tracing mode, profile results may not
- show any groups or structures in the form of elements not described here. Depending on the
- merge directive, all groups will be given either by the catalog source(s)
- (
The YAML specification is freely available here: + YAML 1.2. +
+Additionally, in order to unambiguously express information, this specification uses additional conventions, as described below.
+There are some objects whose values must be determined dynamically at processing time. The most common example of this is timestamping output as it is processed. In this case, and any other dynamic-value cases, the expression
+ ${{ }}is used.
+
For example:
+Indicates the
+
Some examples may elide content to enhance readability or save space. In these cases, a YAML comment (any line that starts with
+ #) will be used to explain the elision.
+
Finally, although examples are syntactically faithful to OSCAL, they are not necessarily always formally valid in every respect. For example, OSCAL defines allowed property names (
+
The back matter in target catalogs is assembled from the back matter of their source
- profiles in combination with the back matter of source catalogs. In both catalogs and
- profiles, <resource id="document-X>
- may be referenced from inside its containing document by <link
- href="#document-X"> appearing elsewhere. Whether an element inside back matter must
- be included in the target, depends on whether such a cross-reference has also been included
- in the same target.
Specifically, any
The specification is broken into the following major sections:
The element (
+
The element is referenced from a link or anchor (#id, where id is the value of the
-
+
The assembly of the target
Additionally, combination rules (see next section) will affect whether and how duplicate or
- competing
+
The overall intent of this document, in addition to defining strict requirements, is to provide rough guidelines on implementing an OSCAL Profile Resolution Tool. To this end, each phase of resolution will be framed as a series of transformations applied to an internal data structure that is persistent throughout the process. We call this "the intermediate".
+Any examples that are labelled as "Intermediate" are pseudo-code, designed to represent how this data structure might look as we apply different operations to it. The example intermediates are often not valid OSCAL, and are not to be taken as guidance, but rather a useful visualization tool for implementers.
+The authors believe that applying the steps of resolution in order against this intermediate representation is the simplest way to achieve full compliance with the specification. However, there is no requirement to implement profile resolution in this way. Requirements are given as rules on the output of resolution, and as such, tools can operate any way they would like internally.
Considered as a document
or integrated data set (object), a profile has three
- sections, each of which corresponds to a conceptual step in resolution. To resolve a catalog
- fully is to perform all these steps.
While the steps are described in this specification as occurring in sequence, a profile
- processor is not obliged to perform them in the order described. Conformance to these
- specifications is determined by whether the results of processing (
The three steps are
An OSCAL Profile has three major sections, each which correspond to a phase of profile resolution. In order to complete the profile resolution process, each section must be fully parsed and a catalog output created.
+It is strongly RECOMMENDED that implementations execute the following steps in the order that they are provided here. While it is possible to achieve compliance with a non-standard approach, the iterative nature of profile resolution lends itself to linear processing.
+The three steps are
+
+
+
+
The
The no merge option
). In source data (a valid profile document), a
-
The
As described in the previous section, when resolved, an OSCAL profile takes the form of an - OSCAL catalog. The merge semantics described below will produce outputs conforming to this - organization.
-A profile begins by importing catalogs, all of whose controls are made available. The - catalogs it references may be available as static resources, or they may be produced - dynamically on request; accordingly a profile may also import profiles, to be resolved as - catalogs, instead of or in addition to catalogs as such. Imports are given in sequence after - the metadata:
-The resource indicated can be either an OSCAL catalog or an OSCAL profile. A catalog - provides controls in their native form. An imported profile is resolved on import, using the - same rules for profile resolution, so a catalog is presented to the importing profile.
-(The result of importing other endpoints or resources besides valid OSCAL catalogs and - profiles is not defined by this specification.)
-No profile may import itself either directly or indirectly. An import directive that - indicates either the profile itself, or a profile into which it is being (currently) - imported, must be ignored. Optionally, a processor may issue a warning.
-In an import directive, the reference to the resource to be imported appears on an
-
An external reference appears as an absolute or relative URL
-Indicating a file available via
A catalog or profile to be imported can also be indicated using an internal link via a
- URI fragment identifier (starting with #). If an import href resolves to a
- resource elsewhere in the profile (typically in back matter), that resource
- can be retrieved to provide the source catalog.
A reference from an import to a resource that does not reference a catalog or profile, or
- a cross-reference to something other than a resource, is inoperative for purposes of
- importing. It may be signaled as an error [or warning] by a processor.
As described in the previous section, when resolved, an OSCAL Profile takes the form of an OSCAL Catalog. The phases described below will produce outputs conforming to the catalog model.
+A profile begins by listing a set of catalogs and/or profiles to be imported. Each is represented by a resolvable resource URI and a directive specifying which controls to import from that resource. These resources may be available as static resources, or they may be produced dynamically on request; such as is the case when a profile is imported. Imports are given in sequence after the metadata:
+In an import directive, the reference to the resource to be imported appears on an
+
An external reference appears as an absolute or relative URL:
+While an internal reference appears as below (see
+
All import directives will contain either
+
The following section contains requirements for processing the
+
Tools MUST resolve URIs by following
+ Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be resolved as defined in
+
The rules of XSLT document() apply to the traversal of any URI: that is, it
- is assumed that all calls to a given (resolved) URI reference, will return the same
- result.
If documents called for import are determined to be unavailable, the processor may drop
- them along with a warning, both or either out of band (e.g. through STDERR)
- or in the catalog results.
URIs are used as a widely supported, global address with broad utility. A processor is - not obliged, when requested for a resource, to use the given URI in an http request to - produce it. Processors may offer fallback behaviors for URI requests that fail; conversely - a processor may be able to avoid a URI request in favor of a better way to provide - resources identified by URI.
+Tools MUST acquire resources at the resolved URI by following
+ Section 5 of RFC3986, with the exception of URI Fragments (URIs that start with "#"). URI Fragments MUST instead be acquired as defined in
+
For the purposes of resolving URIs using the above specification, the Base URI MUST be considered to be the absolute URI of the containing profile.
+In the case that acquiring a resource fails, the tool MUST cease processing and provide an error. In order to ensure profile resolution results in the same catalog regardless of which tool resolves it, all imports must successfully resolve. While this may cause inconvenience if resources are frequently not available, it ensures interoperability.
+Note that receiving a cached version of an import, or resolving an import that is otherwise unavailable through some other (but automatic) means still satisfies the above requirement. This specification does not put requirements on the precise function of the import, as long as the correct document is retrieved.
An import that does not reference either an OSCAL catalog, or an OSCAL profile that can - be resolved as a catalog, is dropped.
-Optionally, a processor may produce a comment indicating the lapse:
-In this context, an OSCAL profile that makes direct or indirect reference (via its own
- imports) to the importing catalog, is also dropped as unavailable. See below under
- Circular Imports
.
URI Fragments in OSCAL represent internal references to other OSCAL objects in the same document. These references follow the pattern of "#{{objectID}}". For example, the URI Fragment "#param1" is referencing the Parameter with unique ID "param1".
+In the context of the Import Phase, internal references will only appear as a reference to a profile or catalog that is in the
If the object fetched cannot be found or is not a valid OSCAL object, the tool MUST cease processing and provide an error.
+When a profile imports a profile, the subordinate profile is resolved into a catalog - using the same rules. This presents a possibility of circular imports, when a profile is - directed to import itself either directly or indirectly.
-A
Note that an import can only be circular within the context of processing a particular - profile. In the last example, C’s import would not be circular if invoked in the context - of resolving B by itself (without being imported by A), or of resolving some other profile - that did not import A. (D importing B importing C importing A would not be a problem.)
-Circular imports are inoperative, and may be reported as an error
An import that is not circular (refers to a document not already imported) results in a - control selection, subject to merging with other control selections in the merge - phase.
-A profile identified as home_profile.xml imports another one identified as
- circular_profile.xml:
In turn this file invokes home_profile.xml:
No control selection is produced for the circular import:
-Optionally, a processor may produce a comment indicating the lapse:
-If the resource acquired is an OSCAL Profile, the tool MUST apply this specification to resolve it, then continue processing having imported the resulting catalog.
+When a profile imports a profile, the subordinate profile SHOULD be resolved first into a catalog using this specification, before it is imported. This presents the possibility of circular imports, when a profile is directed to import itself either directly or indirectly.
+A
+
Note that an import can only be circular within the context of processing a particular profile. In the last example, C’s import would not be circular if invoked in the context of resolving B by itself.
+If a processor encounters a
+
A profile identified as
+ home_profile.yamlimports another one identified as
+ circular_profile.yaml:
+
In turn this file invokes
+ home_profile.xml:
+
Once detected, this circular import will result in an error and no further processing will take place.
+In the selection phase, each import directive is processed to produce a set of controls
- and (when they are referenced) parameters. These controls and parameters are represented
- in the form of a control selection. Note that this occurs in the selection phase even if
- the same catalog (resource) is imported multiple times: each distinct import collects
- controls into a
The control selections are combined and collapsed in the next phase of processing,
-
Multiple imports may result in outputs with clashing controls (see below). Typically this - will be because a control has been selected twice (in selection or in the selections of - underlying profiles), and no merge behavior has been indicated to resolve the clash.
-Typical cases of multiple imports of the same (underlying) resource will be when a - profile A imports another profile B, which calls catalog Z, and then profile A calls - catalog Z again to acquire other controls not included in profile B, or in an original - form unmodified by profile B.
+Each import directive is processed to produce a set of controls. Note that this occurs even if the same catalog is imported multiple times: each distinct import collects controls into a separate
+
The control inclusions are combined and collapsed in the next phase of processing,
+
Multiple imports against the same resource are allowed, and would most commonly occur when the profile author is using
Imports can specify controls by inclusion and exclusion, either or both in - combination.
-Using inclusion, all or some controls may be selected from a catalog.
-Select individual controls or controls by groups using
Controls may also be selected using match patterns against their IDs. This is useful - because related controls (either in a hierarchy, or together in a group) frequently - have related IDs as well.
- -Select all controls from a catalog by using an
In OSCAL, controls may contain controls. For example, in SP 800-53 many controls are - supplemented with control enhancements; in OSCAL these are represented as child - controls within parent controls. So parent AC-2 (in a given catalog) has children - AC-2(1) through AC-2(13), for example.
-Child controls can be included by the same mechanism as controls, i.e. by means of an - ID call. Alternatively a match can frequently be applied (at least given most ID - assignment schemes) to match controls and child controls together.
-Additionally, a
Furthermore,
Calls and matches may be combined in a single import. Their effect is cumulative; any
- control that is selected by both calling and matching from a given
-
Exclusions work the same way as inclusions, except with the opposite effect - the - indicated control(s) do not appear in the target catalog.
-Additionally, there is no such thing as
Any control designated to be both included and excluded, is excluded. This holds
- irrespective of the specificity of the selection for inclusion or exclusion. For
- example, if AC-1 is included by id ac-1 and excluded by matching
- ac.*, it is excluded. Selection for exclusion prevails.
Because controls may be organized in the subsequence merge phase, order of controls
- returned in the selection step is unimportant in most circumstances. If no merge
- directive is applied, however, or the no merge
combination rule is used (see
- below), controls are returned for an import in the order of their appearance in their
- catalog of origin.
The optional
+
The Mapping section consists of 5 optional subsections, each covering a particular type of object. Each subsection is a list of ID mappings to be applied for objects that are the parent object type.
+When encountering a given mapping instruction, processors:
+MUST change the distinctive ID of that object to be equal to the value of the
+
MUST update all known references to the old ID in other included content, allowing the new ID to be used in subsequent profile sections.
+Since mapping is a self contained process inside each import, the rest of this specification will continue to reference IDs with the assumption that mapping has already been applied if it was present. Since mapping is most commonly used to avoid clashing IDs, processors should take care to not handle duplicate IDs until after mapping is complete.
+Below is a simple example of mapping. The second
+
Using the intermediate approach, an internal data structure resembling the following would result from the above profile:
+Unlike controls, parameters are copied implicitly. Whether a parameter in the source
- catalog is copied into the target depends on two factors: its location, and whether it is
- referenced by an
Any parameter (
Each import contains directives on which controls from the imported catalog are to be fetched and used for further processing. Throughout the rest of the document we will refer to this as "inclusion". + If a control is included, and the source profile makes no other changes to it, it will be present in the output. Exclusion directives in this section, as well as directives in the following two major sections (merge and modify), + may make changes to an included control or group that could cause it to appear differently, or not at all, in the output. Using the intermediate implementation approach, any control(s) that are included would be extracted from the referenced catalogs, any applicable mappings would be applied, then the controls(s) would be stored.
+When an import provides the
+
When an import provides the
+ idmatch one of the listed
+ idvalues MUST be included:
+
Controls may also be included using match patterns against their IDs. This is useful because related controls (either in a hierarchy, or together in a group) frequently have related IDs as well.
+When an import provides the
+ idmatches one of the listed
+ patternvalues (Glob matching) MUST be included:
+
If a
+ matchingobject is provided with no
+ pattern, it MUST be treated as matching nothing. While not providing a pattern is technically valid, resolution tool implementers should be aware that it is generally undesirable, and warnings or notices to the user may be appropriate.
+
In OSCAL, controls may contain child controls. For instance, in SP 800-53 many controls are supplemented with control enhancements; in OSCAL these are represented as child controls within parent controls. So parent AC-2 (in a given catalog) has children AC-2(1) through AC-2(13), for example.
+By default, inclusion of a control also causes any of that control's ancestors (or parents) to also be included. By default, inclusion of a control DOES NOT cause the inclusion of any descendants (or children) of that control to be included. This applies to both controls and groups.
+This default behavior can be modified by the following two optional children of the
+
Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the "with-child-controls" option. "with-child-controls" appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.
+A
+
A
+
If no
+
There are two situations where parameters must be considered separately from controls,
- in which case they are considered to be loose
, appearing in the target directly
- inside inherently loose
.
- The second is when they become loose
because the control in which they appear, is
- not selected, but they are needed in the target, due to being referenced for insertion
- elsewhere.
The same parameter, however, cannot be both loose and anchored. If it is invoked from
- inside its parent control, it is considered as anchored, even if it would also be called
- (as loose) by virtue of insertions made outside the parent control, were the parent
- control not included. That is, a
In general, loose parameters (parameter declarations,
Loose parameters (that is, with
When a catalog is organized by a
Parameters that are not referenced by an
Although similar to the above
+
A
+
A
+
If no
+
Exclusions work the same way as inclusions, except with the opposite effect - the indicated control(s) do not appear in the target catalog.
+Any control designated to be both included and excluded, MUST be excluded. This holds irrespective of the specificity of the selection for inclusion or exclusion. For example, if AC-1 is included by id
+ ac-1and excluded by matching
+ ac.*, it is excluded.
+
When
+
A given
+
Note that this requirement only applies to controls included within the context of a single import. Controls with duplicate IDs included under a different
+
Any
+ loose
param.
+
All loose params from both imported documents and the profile source MUST be included. These params will be kept in the final output if document contains any references to them, and discarded otherwise. See
+
Some source catalogs use
+
In order to ensure that implementers have as much flexibility as possible, requirements in this section have purposefully been kept minimal. Below are some common issues for implementers to be aware of:
+Generally such a collision is readily detectable as long as IDs have not been modified; - in other words, constraints over uniqueness (within document scope) of IDs will be - violated in resolved instances where two (perhaps different) representations of the same - control appear. Careful profile authors will be able to detect and prevent these resulting - problems.
-Apart from handling problems and exceptions, however, for different purposes different
- profiles might wish to apply different rules. OSCAL offers three such rules: the
- directives for each are given as a value on the
If no
is the same as
-No mergecombination rule -
When a merge is indicated by no merge
combination rule is used. Clashing controls or parameters are not
- merged. (They are kept.) Their groups are merged only if another
Under this directive, colliding controls will result in invalid results, as they will - both appear in the results with the same ID. Accordingly, this setting may be useful in - ensuring integrity of references to controls as given in the profile: if any included - control is called only once, clashing controls will not be produced and validation will - succeed.
-In the target (showing control selections):
-In this case, downstream errors should be expected: the two a1 controls
- clash with each other, as do the two b1 controls. To remove the duplicates,
- either repair the source catalog to avoid the redundant invocations (usually a better
- solution) or (when that is unavoidable) use a different merge combination rule.
Processors may optionally produce warnings when clashing controls are produced due to - redundant invocations.
-Use firstmerge combination rule -
When the use first
combination rule is applied, the first reference to a given
- control, with respect to the document order of the source data, prevails over later
- references. First
is determined in reference to a top-down, depth-first traversal
- of the profile import hierarchy. So if a profile is imported before a catalog, and the
- imported profile presents a representation of a control also given in the catalog
- import, the profile’s representation (perhaps modified) is taken. However, if the import
- directive targeting the catalog appears first, the catalog's (unmodified) representation
- of the control is included.
The same logic applies to parameters in the source catalogs, as modified by
-
In the target (showing control selections):
-use first
combination rule also affects back matter,
- q.v.
Merge controlsmerge combination rule -
When the
The single unified representation is assembled by aggregating all the contents of all - the (clashing) control instances and discarding replicated branches, so that only a - single instance of each distinctive element appears in the result. The order of the - copied contents will be their original order within their controls, given in the - original order of the controls in their source catalog, then sorted into canonical order - for control contents.
-Example:
-merging with
-produces
-Note that groups are not merged by this rule; for that purpose,
Since the effect of this merge rule is to drop data silently (when it is considered to - be redundant or duplicative), it should only be used on well-understood, well-controlled - catalog and profile inputs, whose potential clashes or collisions are known in - advance.
-When profiles import from more than one resource (catalog or profile), not only is - there a potential for clashing controls, but also citation and resource elements - appearing in the back matter may clash with other citations and resources, yielding - validation errors in the result when an ID appears more than once.
-This situation is not remedied by the no merge
combination rule. Under this
- rule, any citation or resource that is referenced from an imported catalog or profile,
- is included in the resolution target. This may result in replicated contents, where the
- same element is given more than once in the target, producing violations of
- ID-uniqueness constraints. For profiles that call controls from more than one import
- pathway, the no merge
combination may be most useful for debugging.
Under the use first
rule (with
merge controls
)
- rule apply to back matter? Maybe the same as use-first. Or maybe use an approach
- similar to controls.
At this point all requirements for content importing and control inclusion have been covered. If using the intermediate approach, the processor should have an intermediate that contains: a set of included controls and all of their child informational (non-control, non-group) objects, any relevant
+
Profiles may contain a
+ mergehas two parts: a "combine" directive, and a "structuring" directive.
+
It is RECOMMENDED that tools apply the "combine" directive to the intermediate generated by the Import phase first, then apply the "structuring" directive.
+The following section contains requirements for processing the
+
+ combineis an optional child of
+ mergethat provides the rules for dealing with objects that have duplicate (or clashing) distinct IDs
+
There are two valid combination methods provided by OSCAL, provided by the
+
use-first: Use the first definition - the first control with a given ID is used; subsequent ones are discarded
+keep: Keep - controls with the same ID are kept, retaining the clash
+Note that "merge: combine" is deprecated, and MUST be considered undefined behavior when encountered.
+In order to apply the combination method, IDs of each control explicitly included are compared against one another. As IDs are unique across entire OSCAL documents, different imports or any groupings have no bearing on collision. Processing requirements for each method are described below.
+If no
+
is the same as
+The overall organization of the target document at the top level has been described
The
Profiles that have neither of these directives are resolved as unstructured catalogs, - with no groupings of controls.
-Unstructured catalog output is produced by emitting the contents of the sequence of
- control selections produced in the selection phase, seeing to it that (for validity in
- XML) they are sorted so that all loose
as is-
An
Under
This is achieved by propagating, with all controls that are included, all groups that
- they appear within, along with the groups’ IDs, titles and other contents, including
- any parameters to be referenced in the target (
Groups that do not include controls that have been included (either directly or as - descendants of contained groups), are not propagated to the target.
-This is slightly different from groups, which may in valid inputs have other contents - – besides titles, controls, or groups – that profile authors wish to see copied into - the customized catalog.
-Example:
-In this case the profile does not designate either control xyz-1 or
- control xyz-1.2 for inclusion
The unmentioned elements are included, however, with their titles, because controls
- that they contain are included. But control xyz-1.3 does not appear in
- the target.
Note that this means there may be controls that are selected implicitly by
- no merge
process.
Processors may optionally provide services for detection of nesting and structural - issues related to the importing and merging of controls, including but not limited to - validation / detection utilities (for imports regarded as incorrect, incomplete or - otherwise subject to improvement); runtime warnings; or user interfaces.
-One title only. Other contents? Elements and controls are subject to the merge
- combination rules.
The
The controls to be included must be selected in the profile's import. A call or match
- appearing inside
The structures given inside the as-is
merging, there is no implicit inclusion of controls by virtue of
- including descendant controls. Instead, all controls are included in the target in the
- locations indicated by the custom structure.
A
Within
A
A
Within
ascending will sort all included controls, whether selected by
-
descending will sort all included controls, whether selected by
-
keep indicates that controls should be inserted in the order of
- their appearance, first among import selections, then in the order they appear in
- their (imported) catalog source.
In this example, control a2 does not appear in the target
- catalog, as a custom structure was indicated (by the presence of the source profile
-
When a custom structure references a control that is not included in any control - selection (in the import phase), the reference is inoperative. A processor may - signal a warning in this case.
-Similarly, no error occurs if a control is selected (appears in a control selection
- or even more than one), but it is never referenced from the
In this case, no b2 and c2; because they appear unwrapped before the
- c2, however, appears in a subgroup group2
- inside the group with ID group1 , again reflecting the source
- organization. Note also that
Again, no provision is made to prevent duplicate or colliding controls from
- appearing. Optionally, a processor may signal warnings when it determines that
- controls from selections are designated to appear in the results more than once, due
- to multiple colliding occurrences of
method:keep+ +
When a merge is indicated by
+ keep
combination rule is used. Any controls with the same distinctive ID
+
Under this directive, colliding controls will result in invalid results, as they will both appear in the results with the same ID. Accordingly, this setting may be useful in ensuring integrity of references to controls as given in the profile: if any included control is called only once, clashing controls will not be produced and validation will succeed.
+In the intermediate (showing control inclusions):
+In this case, downstream errors should be expected: the two
+ ac-1controls clash with each other, as do the two
+ ac-2controls.
+
Processors SHOULD provide a warning under this directive when duplicate controls are detected. The processor MAY throw an error and cease processing (short-circuiting a certain future error).
+method:use-first+ +
When the
+ use-first
combination rule is applied, and controls that share a distinctive ID are found, the first control encountered MUST be kept, the rest MUST be discarded.
+ First
MUST be determined by a top-down, depth-first traversal of the source profile's import hierarchy.
+
In the intermediate(showing control inclusions):
+Deprecated, unspecified behavior.
(Aka
There are two ways a control may need to be modified. Commonly, controls might be amended – - new material might be added. (For example, the priority marker properties P1-P3 in the - SP800-53 LOW MODERATE and HIGH baselines.) Less commonly, materials might be removed or - edited.
-OSCAL does not provide for changing
a control, but editing can be achieved by
- removing contents and adding (edited) contents back. This can be achieved at the control
- level, or, when constituent elements inside a control have distinct IDs, at more granular
- levels as well. Features make it easy both to trim (filter) and to supplement catalogs.
In addition to any modification or adjustment to controls, this section of a profile is - used to set parameter values or other properties of parameters declared in catalogs and - referenced from their text. Parameters are propagated with the profile's setting into the - target catalog for its use.
-Modification of parameter settings is indicated using
Parameters are not always given within controls. A profile resolution target must include
- copies (with or without modifications or settings) of all parameters defined within the
- source catalog, which are referenced from
Accordingly, any parameter referenced by an
However, a profile should not reproduce parameters from source catalogs, which are not
- referenced from
When parameters are propagated, they may be modified by
If more than one
This section describes how a profile may dictate the structure of the target
+
If no
+
is the same as
+Profiles with the "flat" merge directive are resolved as unstructured catalogs, with no groupings of controls.
+Unstructured catalog output MUST be produced by adhering to the following requirements:
A
All included controls are output to the target as a flat list directly under "catalog".
A
Any included "loose params" are output to the target as a flat list directly under "catalog".
An example of flat structuring is provided below
+as-is+ +
An
+
Processors MUST handle the
+
Other elements given in a
All included controls are output to the target, keeping the structure of the groups and nested controls. Any group that holds an included control MUST appear in the output with all of its non-control children intact. + If an included control has a parent control that was not included, that control's output location is "up-leveled", or made equal to the non-included parent. This applies recursively until the control is directly under either "catalog" or another included control.
The prescribed order of elements in the affected parameter is retained:
-
Any included "loose params" are output to the target as a flat list directly under "catalog".
[example]
-Note that
A
Optionally, a processor may issue a warning where such directives are found.
-Example:
+A control can be altered by an
Contents may be added to controls using an add directive inside an alter directive. - There are two forms of alteration: with implicit and explicit bindings.
-An starting and ending.
The contents of the add directive are then added to the control contents in the
- target, either after its starting, or at the end if its position is ending, or not
- given.
However, control contents in catalogs must appear in the order title, param,
- prop, link, part, control. Subsequent to adding new elements, the control
- contents are sorted to appear in the required order. As a consequence, a new
- ending, or not given,, or before any
- starting.
When add has no before and after are treated like
- starting and ending, respectively.
An addition operating on a control with implicit binding and position
- starting
Position is starting but the new
An addition operating on a control with implicit binding and position
- ending
The ending so the new
An explicit binding on an addition permits inserting new contents anywhere in a
- control, not only at the top level. It is given by a
The element with
Additionally, with an explicit binding given by a starting,
- ending, before and after.
When starting or ending, the new
- contents are added at the beginning or ending of the target element, inside that
- element, as are additions into controls (using implicit bindings).
Additionally, a before indicates the
- addition should be made directly before the target element, while after
- indicates the addition should appear directly after the target element.
An addition operating on a control with explicit binding and position
- after
Note that the a1.b1 as its target.
The after so both elements inside
-
Note that the result in this case will be schema-invalid since a
OSCAL supports control extensions inside controls in the form of
Because such a control can already be modified using implicit bindings, it is
- recommended that they not be targeted with explicit bindings. Using an implicit
- binding supports more robust alteration since contents in the target can be ordered
- properly by the resolution processor.
custom+ +
The
+
A
+
If the ID of the group matches the ID of a group that has been included during the import phase, all contents inside the group, including
+
Note that groups defined in
+
Contents inside controls can be removed from them in catalog targets. In combination - with adding new contents, this feature can be used to edit controls as well as amend - them.
-A
The
+
In order to provide clarity, controls that match the various conditions of these inclusion directives inside the
+
A
+
Because
+
Any element inside the control with the assigned
A
+
An
+
+
Any element inside the control with the assigned
+ ascendingwill sort all selected controls into ascending alphanumeric order by their ID.
+
+ descendingwill sort all selected controls into descending alphanumeric order by their ID.
+
<remove item-name='prop'/> has the effect of removing all
-
+ keepindicates that controls should be inserted in the order of their appearance, using a depth-first traversal of the source profile's imports.
+
Unlike an
To remove an control, simply avoid selecting it into the profile, or exclude it
- specifically using
As with
Finally some alterations are made automatically.
-For example,
In the case that a control selection matches none of the included controls, it MUST be ignored; a warning SHOULD be provided. If a control that was included by the Import Phase is never selected, no error occurs, that control simply does not appear in the output catalog.
In addition to selecting, merging and modifying, certainl operations - are conducted in profile resolution that occur irrespective of phases, - that is in any profile resolution. These include rewriting the profile - metadata into the resolved baseline (catalog), and filtering and - rewriting back matter.
-After the merge phase, the intermediate should now closely resemble the content and structure of the final output catalog. Controls and groups have been included, remapped, de-duplicated, then placed into their final location within the output's structure. Note: there is still an opportunity for included controls or groups to become referenced; and therefore, not eligible for pruning
+
Regardless of any merge directives, there also likely remains "loose params" that have been propagated forward; these too must be persisted.
+There are two ways profiles may further modify the results of profile resolution: setting parameters, and altering controls. These activities are defined as two child objects inside the third step of profile resolution, the Modify Phase.
+The following section contains requirements for processing the
+
Modification of parameter settings is indicated using the
+
Profile Resolution Tools MUST adhere to the following requirements for processing "set-parameter":
+First, the list of included params (among "loose params" and remaining included controls and groups) is searched for a param who has a "id" equal to this object's "param-id". This is the "target". If no such parameter is found, a warning SHOULD be issued, but processing MUST continue.
+When encountering the following objects in the source: class, depends-on, label, usage, values, select; overwrites the object of the same name in the target. If no such object exists in the target, it is created.
+When encountering the following objects in the source: props, links, constraints, guidelines; adds the contents of the source object to the contents of the target object of the same name. If no such object exists in the target, it is created. For each individual child object of "props" and "links" in the source, if an individual child inside the target object has the same distinctive ID, it is instead overwritten by the source object
+
If more than one
+
A control can be altered by an
+
Contents may be added to controls using an add directive inside an alter directive. There are two forms of alteration: with implicit and explicit bindings.
+An
+ startingand
+ ending.
+
The contents of the add directive are then added to the control contents in the target, either after its
+ starting, or at the end if its position is
+ ending, or not given.
+
However, control contents in catalogs must appear in the order
+ title, param, prop, link, part, control. Subsequent to adding new objects, the control contents are sorted to appear in the required order. As a consequence, a new
+ ending, or not given, or before any
+ starting.
+
When add has no
+ beforeand
+ afterare treated like
+ startingand
+ ending, respectively.
+
An addition operating on a control with implicit binding and position
+ starting
+
Position is
+ startingbut the new
+
An addition operating on a control with implicit binding and position
+ ending
+
The
+ endingso the new
+
An explicit binding on an addition permits inserting new contents anywhere in a control, not only at the top level. It is given by a
+
The object with
+
Additionally, with an explicit binding given by a
+ starting,
+ ending,
+ beforeand
+ after.
+
When
+ startingor
+ ending, the new contents are added at the beginning or ending of the target object, inside that object, as are additions into controls (using implicit bindings).
+
Additionally, a
+ beforeindicates the addition should be made directly before the target object, while
+ afterindicates the addition should appear directly after the target object.
+
An addition operating on a control with explicit binding and position
+ after
+
Note that the
+ a1.b1as its target.
+
The
+ afterso both objects inside
+
Note that the result in this case will be schema-invalid since a
+
OSCAL supports control extensions inside controls in the form of
+
Because such a control can already be modified using implicit bindings, it is recommended that they not be targeted with explicit bindings. Using an implicit binding supports more robust alteration since contents in the target can be ordered properly by the resolution processor.
+
Contents inside controls can be removed from them in catalog targets. In combination with adding new contents, this feature can be used to edit controls as well as amend them.
+A
+
+
Because
+
In the result catalog,
+
Any object inside the control with the assigned
+
Where always
- is given on any such
+
Any object inside the control with the assigned
+
However, resources are discarded if they are not designated as
- the target of any link (#,
- with the following exception:
Any keep and whose value is
- always.
Within a group of always keep
with that identity, are selected from,
- and the last of these (only) is propagated.
+
Marking a resource with a name='keep' and value
- always thus has a couple of uses:
Placing such a property on a resource in a catalog, has the
- effect of ensuring it will always appear in the baseline
- produced by any profile importing that catalog, even if
- nothing links to the resource. This version of the resource
- will also be the one copied, unless a later-imported catalog
- or importing profile offers its own version marked to
- always keep
.
Placing such a property on a resource in a profile, ensures - both that the resource appears (even if not cross-referenced) - in the resulting baseline catalog, and that its version is - used, unless when imported into another profile, in which case - it may be overridden by another one (also marked as always - keep).
-
+ remove: item-name: prophas the effect of removing all
+
Unlike an
+
To remove an control, simply avoid selecting it into the profile, or exclude it specifically using
+
As with
+
A null
profile – that is, with only an import and nothing
- else – does not return its imported catalog unchanged. But the changes it makes can be useful.
- This makes a null profile or its
In the target, the catalog group structure and all hierarchy is removed; its controls are - all returned in sequence. Any loose parameters in the catalog not referenced in a control, - are dropped.
+
+
Each import's backmatter is processed in order it was provided in the source profile, then the source profile's backmatter is processed.
+Each
+
If a
+
A resource with a child prop of name:keep and value:always can only be replaced following the above rule by a duplicate that also has the keep always prop.
+Tools MAY check for pruning conditions
+
Placing the keep always prop on a resource in a catalog has the effect of ensuring it will always appear in the output produced by any profile importing that catalog, even if nothing links to the resource. This version of the resource will also be the one copied, unless a later-imported catalog or importing profile offers its own version marked to keep always.
The same, except that only top-level controls are included, not descendants.
-The following requirements MUST be followed with regards to the Metadata section of the output catalog:
+The output catalog MUST have a unique top-level UUID (metadata:uuid). This UUID may be generated as seen fit by the tool, as long as it is reasonable to assume it is globally unique. It is RECOMMENDED that tools use a combination of meaningful text and a uniquely generated value (Ex.
+ {{sourceprofilename}}-RESOLVED-{{GUIDv5}}).
+
The value of metadata:version in the target MUST be set with a string that identifies the version of this document. This SHOULD be used to track updates to this specific output document.
+The value of metadata:oscal-version in the target MUST be set with a string that identifies the version of OSCAL used by this tool to resolve the profile (ex. 1.0.0). This value MUST be determined by compiling the oscal-versions from each imported document and the source profile, and taking the most recent minor version. If this version is more recent than what the resolution tool is using, then the value of the output oscal-version MUST be the version that the tool used internally. If any of the above OSCAL versions (imported document versions, source profile version, tool version) are of a different major version (the first digit differs), the tool SHOULD provide an error and cease processing.
+The value of metadata:last-modified in the target MUST be set with a valid timestamp representing the time the profile resolution completed.
+The value of metadata:source-profile in the target SHOULD be set with a valid URI that points to the profile that resulted in this catalog. If there are privacy or security concerns, the value MAY be set to anything, in which case the simple existence of the source-profile property indicates that this is a resolved profile.
+The value of metadata:resolution-tool in the target SHOULD be set with a string that represents the tool that was used to resolve this catalog.
+Beyond these requirements, tools are free to use any and all of the objects inside metadata to provide additional information downstream.
+Because of options in producing metadata and especially the requirement for a timestamp, developers and users should note that two different resolutions of the same profile will not, ordinarily, be identical inside
+
Using merge
This enables a near-null profile to define a normalization or cleanup pass on a catalog, as - it will have the result of removing dangling references and orphan parameters, without - otherwise affecting controls.
-The processor SHOULD prune the result catalog to remove unused values. A given object is considered unused if it meets ALL of the following criteria:
+The object does not have a child prop with name:keep and value:always
+The object is not explicitly included
+
There are no references to the object anywhere in the final result catalog, except in other objects that also meet all other pruning criteria. A reference to a given object exists if "#{distinctiveID}" appears anywhere, where {distinctiveID} is the distinctive ID of the object
+
Implementers should note that pruning need not take place after all other steps. As long as all above criteria are respected, pruning can happen at any time, and doing so is a likely performance and memory overhead improvement.
+Tools MUST reorder the output catalog into canonical order
+
For conformance, an OSCAL processor must deliver results of profile processing, in a basic - configuration, exactly as described in these specifications with no elaboration.
-Conformance does not preclude providing additional features, however, including elaborated
- outputs, in an optional mode. Such features could include offering warning or process
- exception handling (appropriate to workflow) not described here; outputs provided with
- comments or extra structure to support tracing or analytics; or (alternative) gateway
- and draconian
modes that would provide user assistance or refuse to deliver results for
- inputs considered erroneous in a workflow.
rendering - showing both unresolved (raw) and resolved profiles
-editing / integrity checking
-rewriting/normalization
-diffing
-deriving a profile as the delta of two catalogs (base
and tailored
)
Whenever this specification refers to
+ distinctiveness
, it MUST be interpreted as is defined in this section with regards to the object in question.
+
control,param,group - distinctiveness is defined by the value of the
+ id
child object.
+
resource - distinctiveness is defined by the value of the
+ uuid
+
Profile Resolution tools SHOULD be able to handle source profiles, imported catalogs, and imported profiles that are serialized in XML, JSON, or YAML. A different serialization format of any given input MUST NOT result in a differing output catalog.
+In order to help bootstrap this format management, the following resources are provided for implementers:
+. + +
+The following sections provide additional requirements and guidance for each format.
+See + the complete XML referencefor model requirements. +
+See the + complete JSON referencefor model requirements. +
+The JSON format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order
+
YAML is considered a simple variation on the JSON format. Beyond cosmetic differences there are no differences in the information structure between these formats. Therefore, the + complete JSON referenceprovides model requirements. +
+The YAML format, in general use, does not require the preservation of order of fields. As order matters in OSCAL, care should be taken to adhere to the canonical OSCAL order
+
In OSCAL, order of top level objects (those that are direct children of the root element) is considered important only when the XML format is used. To facilitate this, OSCAL provides the concept of
+
When the output format is XML, tools MUST use the OSCAL canonical order as described above. When using the YAML or JSON formats, order conveys no meaning, and is not considered important.
+In an XML-based profile resolution, XML comments are one straightforward way for a processor to record events or conditions without affecting the output's nominal semantics. To support this, while two processors are obliged to return the same catalog XML for the same profile XML inputs, they are not required to match one another's comments, white space usage, attribute order, or processing instructions, only each other's objects, attributes and data content.
+One consequence of this is that processes intended to compare two profile resolutions may have to accommodate differences in comments, considering them as insignificant along with other differences in serialization.
+
In an XML-based profile resolution, XML comments are one straightforward way for a - processor to record events or conditions without affecting the output's nominal semantics. - To support this, while two processors are obliged to return the same catalog XML for the - same profile XML inputs, they are not required to match one another's comments, whitespace - usage, attribute order, or processing instructions, only each other's elements, attributes - and data content.
-One consequence of this is that processes intended to compare two profile resolutions may - have to accommodate differences in comments, considering them as insignificant along with - other differences in serialization.
-