-
Notifications
You must be signed in to change notification settings - Fork 192
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add table of parameters and clarify testing folder content
- Loading branch information
Showing
1 changed file
with
31 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,49 @@ | ||
| ## Resolver pipeline | ||
| ## Profile Resolver Pipeline | ||
|
|
||
| Profile resolution is implemented here as a set of XSLT transformations to be performed in sequence, applied to defined inputs (a **source profile** with imported **catalog** sources) to produce defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** is also used to refer to a particular profile in application, whether in its unprocessed form or its resolved, serialized form. | ||
| Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form. | ||
|
|
||
| The sequence reflects and roughly corresponds to the three steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/): | ||
| The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/): | ||
|
|
||
| - **selection** (importing catalogs or profiles and selecting controls from them) | ||
| - **selection**: importing catalogs or profiles, and selecting controls from them | ||
|
|
||
| - **organization (merging)** i.e. specifying how selected controls are to be organized in representation | ||
| - **organization (merging)**: organizing the selected controls for the output representation | ||
|
|
||
| - **modification** - setting parameters and potentially supplementing, amending or editing control text | ||
| - **modification**: setting parameters and potentially supplementing, amending or editing control text | ||
|
|
||
| For demonstration, the expected interim results for test files are kept in the testing/\* folders | ||
| ### Tests for this Implementation | ||
|
|
||
| Note that these interim results are *not always valid to any OSCAL schema* while at the same time they are quite close to OSCAL profile and catalog syntax. | ||
| The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence. | ||
|
|
||
| Testing files for profile resolution in general are kept [with the specification](../../../specifications/profile-resolution). The testing files in this subdirectory are only for this implementation. | ||
| Note that these interim results are *not necessarily valid to any OSCAL schema*, although they are quite close to OSCAL profile and catalog syntax. | ||
|
|
||
| ### Invoking the XSLT: | ||
| The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution). | ||
|
|
||
| Use a recent version of Saxon for best results -- although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery). | ||
| ### Invoking the XSLT | ||
|
|
||
| The main entry point for the transformation pipeline is the dynamic build XSLT called `oscal-profile-RESOLVE.xsl`, which invokes the core transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example): | ||
| Use a recent version of Saxon for best results — although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery). | ||
|
|
||
| The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example): | ||
|
|
||
| ```bash | ||
| > java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml | ||
| ``` | ||
|
|
||
| Alternatively, set up the bindings in an IDE or programmed environment that has XSLT 3.1 support. | ||
| You can optionally set one or more of the parameters listed in the following table, using syntax `name=value` at the end of the command above. The sequence of parameters is not significant. | ||
|
|
||
| For example, | ||
| ```bash | ||
| > java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true | ||
| ``` | ||
| | Name | Description | Default | | ||
| |---|---|---| | ||
| | `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI. | `false` | | ||
| | `path-to-source` | Path from output catalog to location of source profile. | None | | ||
| | `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None | | ||
| | `uuid-method` | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`| | ||
| | `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.| `https://www.uuidgenerator.net/api/version4`| | ||
|
|
||
| Alternatively, set up the bindings in an IDE or programming environment that has XSLT 3.1 support. | ||
|
|
||
| Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in examples. | ||
| Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples). | ||
|
|
||
| A captured and serialized profile resolution will take the form of an OSCAL catalog, and be valid to the catalog schema for correctly formed inputs. | ||
| A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema. |