From 8d628a8eff77518a12cb6dfe811908519d2b8725 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Thu, 28 Apr 2022 13:55:35 -0400 Subject: [PATCH] Correctly pruning unused definitions in metaschema composition (#199) * Metaschema composition XSpecs * Adding 'a8' prune-unused-definitions filter for comparison (most advanced yet). * Added new prune filter with slight adjustments to interface; new test for running it standalone * Removing noisy XSpec result * More tuning up v9 pruning step for #198 * Cleanup; restoring top-level compose XSLT * Updating files before merge * First draft of testing approach with current WIP prune phase transform. * Fix tests to align with Wendell exception msg check. * Move pruning tests back to their own folder. * Refactor test input XML docs into separate files * Make the tests more reusable across implementations. * Relocate input files to subdir per convo with @wendellpiez. * Slight improvement to prototype * Much cleanup and rearrangement; readme docs * Updating readme plus entry (shell) XSLT and XProc to current * Removing obsolete XSpec reports * Adding .gitignore to exclude XSpec results * More rearrangement and cleanup; adding step 4 XSpec * New filter detecting and removing unused definitions passes unit tests * Removing early copy of remedied step 4 XSLT * Updating Metaschema Schematron XSpecs to functional state: they are now stable, addressing #47 * More adjustments prepping to M4 unit tests - #81 #186 #201 - now everything is green or grey (pending) no pink * Added more clarification to pruning XSpec * Edits in response to feedback from @aj-stein-nist thanks AJ! * adding blank lines at end of files Co-authored-by: Alexander Stein Co-authored-by: David Waltermire --- test-suite/README.md | 8 +- .../nestedmessy_metaschema-composed.xml | 151 + .../input/nestedmessy_metaschema.xml | 64 + .../composition/input/pruning001.xml | 9 + .../composition/input/pruning002.xml | 16 + .../composition/input/pruning003.xml | 14 + .../composition/metaschema-composition.xspec | 20 + .../metaschema-prune-unused-definitions.xspec | 41 + .../metaschema-xspec/composition/readme.md | 15 + .../metaschema-basic-schematron-result.html | 679 ---- ...aschema-composition-schematron-result.html | 643 ---- .../metaschema-test-helper.xsl | 49 + test-suite/metaschema-xspec/readme.md | 37 + .../{ => schematron}/included_metaschema.xml | 5 +- .../{ => schematron}/including_metaschema.xml | 1 + .../metaschema-basic-schematron.xspec | 4 +- .../metaschema-composition-schematron.xspec | 9 +- .../problem01-module_metaschema.xml | 2 + .../{ => schematron}/problem01_metaschema.xml | 1 + .../metaschema-xspec/schematron/readme.md | 12 + .../scope-local-imported_metaschema.xml | 5 +- .../scope-local-importing_metaschema.xml | 3 +- .../oscal_catalog_metaschema-COMPOSED.xml | 3099 ----------------- .../metaschema-test-coverage.md | 2 + .../xslt-M4/compose/metaschema-collect.xsl | 2 +- .../xslt-M4/compose/metaschema-compose.xpl | 3 +- .../metaschema-prune-unused-definitions.xsl | 174 +- toolchains/xslt-M4/compose/readme.md | 68 +- toolchains/xslt-M4/compose/testing/.gitignore | 4 + .../testing/1_collected/collect-report.html | 650 ---- .../testing/1_collected/collect-result.html | 921 ----- .../compose/testing/1_collected/collect.xspec | 6 +- .../working_metaschema-COLLECTED.xml | 103 +- .../testing/2_reduced1/reduce1-result.html | 589 ---- .../compose/testing/2_reduced1/reduce1.xspec | 64 - .../working_metaschema-REDUCED1.xml | 69 - .../testing/3_digested/digested-result.html | 563 --- .../compose/testing/3_digested/digested.xspec | 16 - .../4_pruning/prune-unused-definitions.xspec | 52 + .../testing/7_digesting/digested.xspec | 34 + .../working_metaschema-DIGESTED.xml | 0 toolchains/xslt-M4/compose/testing/readme.md | 32 + .../compose/testing/working_metaschema.xml | 1 + 43 files changed, 795 insertions(+), 7445 deletions(-) create mode 100644 test-suite/metaschema-xspec/composition/expected/nestedmessy_metaschema-composed.xml create mode 100644 test-suite/metaschema-xspec/composition/input/nestedmessy_metaschema.xml create mode 100644 test-suite/metaschema-xspec/composition/input/pruning001.xml create mode 100644 test-suite/metaschema-xspec/composition/input/pruning002.xml create mode 100644 test-suite/metaschema-xspec/composition/input/pruning003.xml create mode 100644 test-suite/metaschema-xspec/composition/metaschema-composition.xspec create mode 100644 test-suite/metaschema-xspec/composition/metaschema-prune-unused-definitions.xspec create mode 100644 test-suite/metaschema-xspec/composition/readme.md delete mode 100644 test-suite/metaschema-xspec/metaschema-basic-schematron-result.html delete mode 100644 test-suite/metaschema-xspec/metaschema-composition-schematron-result.html create mode 100644 test-suite/metaschema-xspec/metaschema-test-helper.xsl create mode 100644 test-suite/metaschema-xspec/readme.md rename test-suite/metaschema-xspec/{ => schematron}/included_metaschema.xml (92%) rename test-suite/metaschema-xspec/{ => schematron}/including_metaschema.xml (97%) rename test-suite/metaschema-xspec/{ => schematron}/metaschema-basic-schematron.xspec (92%) rename test-suite/metaschema-xspec/{ => schematron}/metaschema-composition-schematron.xspec (77%) rename test-suite/metaschema-xspec/{ => schematron}/problem01-module_metaschema.xml (96%) rename test-suite/metaschema-xspec/{ => schematron}/problem01_metaschema.xml (96%) create mode 100644 test-suite/metaschema-xspec/schematron/readme.md rename test-suite/metaschema-xspec/{ => schematron}/scope-local-imported_metaschema.xml (89%) rename test-suite/metaschema-xspec/{ => schematron}/scope-local-importing_metaschema.xml (95%) delete mode 100644 test-suite/oscal/v1.0.0/oscal_catalog_metaschema-COMPOSED.xml rename test-suite/{ => schema-generation}/metaschema-test-coverage.md (98%) create mode 100644 toolchains/xslt-M4/compose/testing/.gitignore delete mode 100644 toolchains/xslt-M4/compose/testing/1_collected/collect-report.html delete mode 100644 toolchains/xslt-M4/compose/testing/1_collected/collect-result.html delete mode 100644 toolchains/xslt-M4/compose/testing/2_reduced1/reduce1-result.html delete mode 100644 toolchains/xslt-M4/compose/testing/2_reduced1/reduce1.xspec delete mode 100644 toolchains/xslt-M4/compose/testing/2_reduced1/working_metaschema-REDUCED1.xml delete mode 100644 toolchains/xslt-M4/compose/testing/3_digested/digested-result.html delete mode 100644 toolchains/xslt-M4/compose/testing/3_digested/digested.xspec create mode 100644 toolchains/xslt-M4/compose/testing/4_pruning/prune-unused-definitions.xspec create mode 100644 toolchains/xslt-M4/compose/testing/7_digesting/digested.xspec rename toolchains/xslt-M4/compose/testing/{3_digested => 7_digesting}/working_metaschema-DIGESTED.xml (100%) create mode 100644 toolchains/xslt-M4/compose/testing/readme.md diff --git a/test-suite/README.md b/test-suite/README.md index 15b706cf0..c381f8659 100644 --- a/test-suite/README.md +++ b/test-suite/README.md @@ -8,17 +8,15 @@ An example metaschema for mocking up documentation generation. ### `schema-generation` +Unit testing over handmade mini metaschemas. Due for maintenance. + To use: under Bash, run ./run-tests.sh in folder schema-generation ./run-tests --help gives help. ./run-tests.sh [testdir] runs tests only in a particular test directory. -### `schema-generation` - -Unit testing over handmade mini metaschemas. Due for maintenance. - -### `worked-exaples` +### `worked-examples` With one more testing metaschemas exercising different features. diff --git a/test-suite/metaschema-xspec/composition/expected/nestedmessy_metaschema-composed.xml b/test-suite/metaschema-xspec/composition/expected/nestedmessy_metaschema-composed.xml new file mode 100644 index 000000000..5453287a2 --- /dev/null +++ b/test-suite/metaschema-xspec/composition/expected/nestedmessy_metaschema-composed.xml @@ -0,0 +1,151 @@ + + Seeing assembly#nestedmessy:box, assembly#nestedmessy:envelope, field#nestedmessy:page, flag#nestedmessy:no, assembly#nestedmessy:folder + Nested Reference Test + 1.0 + nestedmessy + http://csrc.nist.gov/metaschema/ns/nested + http://csrc.nist.gov/metaschema/ns/nested + +

If any 'unused' definition appears in a schema, we have a bug.

+ + REMOVING unused assembly definition for 'unused-assembly' from nestedmessy. + + PAGE + PAGE + + + + REMOVING unused field definition for 'unused-field' from nestedmessy. + + ENVELOPE + ENVELOPE + + + + + + BOX + BOX + BOX + + + + + + + FOLDER + FOLDER + + + + + + + diff --git a/test-suite/metaschema-xspec/composition/input/nestedmessy_metaschema.xml b/test-suite/metaschema-xspec/composition/input/nestedmessy_metaschema.xml new file mode 100644 index 000000000..bb4122a60 --- /dev/null +++ b/test-suite/metaschema-xspec/composition/input/nestedmessy_metaschema.xml @@ -0,0 +1,64 @@ + + + + + Nested Reference Test + 1.0 + nestedmessy + http://csrc.nist.gov/metaschema/ns/nested + http://csrc.nist.gov/metaschema/ns/nested + + +

If any 'unused' definition appears in a schema, we have a bug.

+ + + + Unused + Unused + + + + + + + PAGE + PAGE + + + + + + + Unused field + Unused field + + + + ENVELOPE + ENVELOPE + + + + + + + + BOX + BOX + BOX + + + + + + + + FOLDER + FOLDER + + + + + + + diff --git a/test-suite/metaschema-xspec/composition/input/pruning001.xml b/test-suite/metaschema-xspec/composition/input/pruning001.xml new file mode 100644 index 000000000..f70fe0014 --- /dev/null +++ b/test-suite/metaschema-xspec/composition/input/pruning001.xml @@ -0,0 +1,9 @@ + + + + BOX + Just a box, no relationship to anything else. + BOX + + diff --git a/test-suite/metaschema-xspec/composition/input/pruning002.xml b/test-suite/metaschema-xspec/composition/input/pruning002.xml new file mode 100644 index 000000000..4139800cd --- /dev/null +++ b/test-suite/metaschema-xspec/composition/input/pruning002.xml @@ -0,0 +1,16 @@ + + + + BOX + Just a box, no relationship to anything else. + BOX + + + + + + Folder + One or more folders belong in a box. + + diff --git a/test-suite/metaschema-xspec/composition/input/pruning003.xml b/test-suite/metaschema-xspec/composition/input/pruning003.xml new file mode 100644 index 000000000..ead94eedf --- /dev/null +++ b/test-suite/metaschema-xspec/composition/input/pruning003.xml @@ -0,0 +1,14 @@ + + + + BOX + Just a box, no relationship to anything else. + BOX + + + + Folder + One or more folders belong in a box. + + diff --git a/test-suite/metaschema-xspec/composition/metaschema-composition.xspec b/test-suite/metaschema-xspec/composition/metaschema-composition.xspec new file mode 100644 index 000000000..e68f98144 --- /dev/null +++ b/test-suite/metaschema-xspec/composition/metaschema-composition.xspec @@ -0,0 +1,20 @@ + + + + + + + + + + + + + diff --git a/test-suite/metaschema-xspec/composition/metaschema-prune-unused-definitions.xspec b/test-suite/metaschema-xspec/composition/metaschema-prune-unused-definitions.xspec new file mode 100644 index 000000000..41ff9d683 --- /dev/null +++ b/test-suite/metaschema-xspec/composition/metaschema-prune-unused-definitions.xspec @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + REMOVING unused assembly definition for 'folder' from pruning003. + + + + + + + + + + diff --git a/test-suite/metaschema-xspec/composition/readme.md b/test-suite/metaschema-xspec/composition/readme.md new file mode 100644 index 000000000..1cbbf15bb --- /dev/null +++ b/test-suite/metaschema-xspec/composition/readme.md @@ -0,0 +1,15 @@ +# Metaschema processing XSpec testing - Metaschema Composition end-to-end (E2E) + +To run XSpec, we suggest either an XML IDE or a command line tool as described in [XSpec documentation in Github](https://github.com/xspec/xspec/wiki). + +* `composition/metaschema-composition.xspec` + +Tests XSLT `../../../toolchains/xslt-M4/nist-metaschema-COMPOSE.xsl` + +Currently checks if unused definitions are correctly filtered away from a metaschema source instance, in composition. + +(This prevents result schemas from including unused models.) + +* `composition/metaschema-prune-unused-definitions.xspec` + +Also testing the same bug, but using standoff instances, with a start on more comprehensive tests. diff --git a/test-suite/metaschema-xspec/metaschema-basic-schematron-result.html b/test-suite/metaschema-xspec/metaschema-basic-schematron-result.html deleted file mode 100644 index 357888f43..000000000 --- a/test-suite/metaschema-xspec/metaschema-basic-schematron-result.html +++ /dev/null @@ -1,679 +0,0 @@ - - - - Test Report for C:/Users/davidwal/git/github/david-waltermire-nist/OSCAL/build/metaschema/toolchains/xslt-M4/validate/metaschema-simple-check.sch (passed: 2 / pending: 0 / failed: 0 / total: 2) - - - -

Test Report

-

Schematron: C:/Users/davidwal/git/github/david-waltermire-nist/OSCAL/build/metaschema/toolchains/xslt-M4/validate/metaschema-simple-check.sch

-

XSpec: C:/Users/davidwal/git/github/david-waltermire-nist/OSCAL/build/metaschema/test-suite/metaschema-xspec/metaschema-basic-schematron.xspec

-

Tested: 29 April 2021 at 09:08

-

Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
passed: 2pending: 0failed: 0total: 2
poc-on-remote-file1001
poc-locally1001
-
-

poc-on-remote-filepassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - - - - - -
poc-on-remote-filepassed: 1 / pending: 0 / failed: 0 / total: 1
An example of a pre-publication QA steppassed: 1 / pending: 0 / failed: 0 / total: 1
The string does not start with 'oscal-', which we really want assert shortname-format-says-oscal - /m:METASCHEMA/m:short-nameSuccess
-
-
-

poc-locallypassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - - - - - -
poc-locallypassed: 1 / pending: 0 / failed: 0 / total: 1
An example of a pre-publication QA steppassed: 1 / pending: 0 / failed: 0 / total: 1
The string does not start with 'oscal-', which we really want assert shortname-format-says-oscalSuccess
-
- - \ No newline at end of file diff --git a/test-suite/metaschema-xspec/metaschema-composition-schematron-result.html b/test-suite/metaschema-xspec/metaschema-composition-schematron-result.html deleted file mode 100644 index 7c94aafb6..000000000 --- a/test-suite/metaschema-xspec/metaschema-composition-schematron-result.html +++ /dev/null @@ -1,643 +0,0 @@ - - - - Test Report for C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/validate/metaschema-composition-check.sch (passed: 1 / pending: 0 / failed: 0 / total: 1) - - - -

Test Report

-

Schematron: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/validate/metaschema-composition-check.sch

-

XSpec: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/test-suite/metaschema-xspec/metaschema-composition-schematron.xspec

-

Tested: 28 April 2021 at 17:02

-

Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - -
passed: 1pending: 0failed: 0total: 1
poc-on-remote-file1001
-
-

poc-on-remote-filepassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - - - - - -
poc-on-remote-filepassed: 1 / pending: 0 / failed: 0 / total: 1
Seeing any name clashespassed: 1 / pending: 0 / failed: 0 / total: 1
No name clash found not assert detect-xml-sibling-name-clashSuccess
-
- - \ No newline at end of file diff --git a/test-suite/metaschema-xspec/metaschema-test-helper.xsl b/test-suite/metaschema-xspec/metaschema-test-helper.xsl new file mode 100644 index 000000000..877ea99d3 --- /dev/null +++ b/test-suite/metaschema-xspec/metaschema-test-helper.xsl @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + + + + + + + + diff --git a/test-suite/metaschema-xspec/readme.md b/test-suite/metaschema-xspec/readme.md new file mode 100644 index 000000000..40c62b2e8 --- /dev/null +++ b/test-suite/metaschema-xspec/readme.md @@ -0,0 +1,37 @@ +# Metaschema processing XSpec testing + +XSpec testing is offered for various aspects of metaschema processing including processing relating to composition (which includes preprocessing/annotation) and validation of metaschemas for constraints related to structural integrity. + +To run XSpec, we suggest either an XML IDE or a command line tool as described in [XSpec documentation in Github](https://github.com/xspec/xspec/wiki). + +See each subdirectory for status updates. + +NOT ALL TESTS ARE OPERATIONAL / FUNCTIONAL + +(See CI/CD configuration). + + +### Tests here are FUNCTIONAL: + +* `composition/metaschema-composition.xspec` + +Tests XSLT `../../../toolchains/xslt-M4/nist-metaschema-COMPOSE.xsl` + +Currently checks if unused definitions are correctly filtered away from a metaschema source instance, in composition. + +(This prevents result schemas from including unused models.) + +* `composition/metaschema-prune-unused-definitions.xspec` + +Also testing the same bug, but using standoff instances, with a start at to some more comprehensive tests. + +### REQUIRING REFRESH / EXTENSION + +* XSpec `metaschema-basic-schematron.xspec` testing Schematron: `../../toolchains/xslt-M4/validate/metaschema-simple-check.sch` + +*Needs updating and pointing to Schematron in its new location.* + +* XSpec `metaschema-composition-schematron.xspec` testing Schematron: `../../toolchains/xslt-M4/validate/metaschema-composition-check.sch` + +*Needs updating and pointing to Schematron in its new location* + diff --git a/test-suite/metaschema-xspec/included_metaschema.xml b/test-suite/metaschema-xspec/schematron/included_metaschema.xml similarity index 92% rename from test-suite/metaschema-xspec/included_metaschema.xml rename to test-suite/metaschema-xspec/schematron/included_metaschema.xml index adac6640b..77c6144ed 100644 --- a/test-suite/metaschema-xspec/included_metaschema.xml +++ b/test-suite/metaschema-xspec/schematron/included_metaschema.xml @@ -1,14 +1,15 @@ Included Metaschema 1.0 included http://csrc.nist.gov/ns/oscal/1.0 - + http://csrc.nist.gov/ns/oscal/1.0 + Assembly that includes global and local flags This assembly includes a flag defined in this included metaschema module. diff --git a/test-suite/metaschema-xspec/including_metaschema.xml b/test-suite/metaschema-xspec/schematron/including_metaschema.xml similarity index 97% rename from test-suite/metaschema-xspec/including_metaschema.xml rename to test-suite/metaschema-xspec/schematron/including_metaschema.xml index c5c459098..954692550 100644 --- a/test-suite/metaschema-xspec/including_metaschema.xml +++ b/test-suite/metaschema-xspec/schematron/including_metaschema.xml @@ -8,6 +8,7 @@ 1.0 including http://csrc.nist.gov/ns/oscal/1.0 + http://csrc.nist.gov/ns/oscal/1.0 diff --git a/test-suite/metaschema-xspec/metaschema-basic-schematron.xspec b/test-suite/metaschema-xspec/schematron/metaschema-basic-schematron.xspec similarity index 92% rename from test-suite/metaschema-xspec/metaschema-basic-schematron.xspec rename to test-suite/metaschema-xspec/schematron/metaschema-basic-schematron.xspec index 407645e4b..682da85db 100644 --- a/test-suite/metaschema-xspec/metaschema-basic-schematron.xspec +++ b/test-suite/metaschema-xspec/schematron/metaschema-basic-schematron.xspec @@ -1,12 +1,12 @@ + schematron="../../../toolchains/xslt-M4/validate/metaschema-simple-check.sch"> - + true - - OSCAL Control Catalog Model - 1.0.0 - oscal-catalog - http://csrc.nist.gov/ns/oscal/1.0 - http://csrc.nist.gov/ns/oscal - -

The OSCAL Control Catalog format can be used to describe a collection of security controls and related control enhancements, along with contextualizing documentation and metadata. The root of the Control Catalog format is catalog.

- - - Catalog - A collection of controls. - catalog - - Catalog Universally Unique Identifier - A globally unique identifier for this catalog instance. This UUID should be changed when this document is revised. - - - - - - - - - - - - - - -

Back matter including references and resources.

- - - - - - - -

Catalogs may use one or more group objects to subdivide the control contents of a catalog.

-

An OSCAL catalog model provides a structured representation of control information.

- - - A small catalog with a single control - - A Miniature Catalog - - A Single Control - - - - - - Control Group - A group of controls, or of groups of controls. - - Group Identifier - A unique identifier for a specific group instance that can be used to reference the group within this and in other OSCAL documents. This identifier's uniqueness is document scoped and is intended to be consistent for the same group across minor revisions of the document. - - - Group Class - A textual label that provides a sub-type or characterization of the group. - -

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

-

A class can also be used in an OSCAL profile as a means to target an alteration to control content.

- - - - - Group Title - A name given to the group, which may be used by a tool for display and navigation. - - - - - - - - - - - - - - - - - - - - - - - - - A human-readable label for the parent context. - An alternative identifier, whose value is easily sortable among other such values in the document. - - - -

Catalogs can use a group to collect related controls into a single grouping. That can be useful to group controls into a family or other logical grouping.

-

A group may have its own properties, statements, parameters, and references, which are inherited by all members of that group.

- - - - My Group - - - Control - - - - - - Control - A structured information object representing a security or privacy control. Each security or privacy control within the Catalog is defined by a distinct control instance. - - Control Identifier - A unique identifier for a specific control instance that can be used to reference the control in other OSCAL documents. This identifier's uniqueness is document scoped and is intended to be consistent for the same control across minor revisions of the document. - - - Control Class - A textual label that provides a sub-type or characterization of the control. - -

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

-

A class can also be used in an OSCAL profile as a means to target an alteration to control content.

- - - - - Control Title - A name given to the control, which may be used by a tool for display and navigation. - - - - - - - - - - - - - - - - - - - - - A human-readable label for the parent context. - An alternative identifier, whose value is easily sortable among other such values in the document. - The status of a control. For example, a value of 'withdrawn' can indicate that the control has been withdrawn and should no longer be used. - - - The control is no longer used. - - - The link cites an external resource related to this control. - The link identifies another control with bearing to this control. - The link identifies another control that must be present if this control is present. - The link identifies other control content where this control content is now addressed. - - - -

Controls may be grouped using group, and controls may be partitioned using part or further enhanced (extended) using control.

-

A control must have a part with the name "statement", which represents the textual narrative of the control. This "statement" part must occur only once, but may have nested parts to allow for multiple paragraphs or sections of text.

- - - - Control 1 - - - - - Part - A partition of a control's definition or a child of another part. - - Part Identifier - A unique identifier for a specific part instance. This identifier's uniqueness is document scoped and is intended to be consistent for the same part across minor revisions of the document. - - - Part Name - A textual label that uniquely identifies the part's semantic type. - - - An introduction to a control or a group of controls. - A set of control implementation requirements. - An individual item within a control statement. - Additional information to consider when selecting, implementing, assessing, and monitoring a control. - Describes a set of assessment objectives. - Describes a method-based assessment over a set of assessment objects. - Provides a list of assessment objects. - - - - - Part Namespace - A 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.

- - - - Part Class - A textual label that provides a sub-type or characterization of the part's name. This can be used to further distinguish or discriminate between the semantics of multiple parts of the same control with the same name and ns. - -

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

-

A class can also be used in an OSCAL profile as a means to target an alteration to control content.

- - - - - Part Title - A name given to the part, which may be used by a tool for display and navigation. - - - - - - Part Text - Permits multiple paragraphs, lists, tables etc. - - - - - - - - - - - A human-readable label for the parent context. - An alternative identifier, whose value is easily sortable among other such values in the document. - - - - The assessment method to use. This typically appears on parts with the name "assessment". - - - - The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence. - The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities). - The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior. - - - - -

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.

-

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 "https://fedramp.gov", while DoD will 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.

- - - Multiple Parts with Different Organization-Specific Names - - Something FedRAMP Cares About - Something DoD Cares About - - - - - Parameter - Parameters provide a mechanism for the dynamic assignment of value(s) in a control. - param - - Parameter Identifier - A unique identifier for a specific parameter instance. This identifier's uniqueness is document scoped and is intended to be consistent for the same parameter across minor revisions of the document. - - - Parameter Class - A textual label that provides a characterization of the parameter. - -

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

- - - - - - - - - - - - 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.

- - - - Parameter Usage Description - Describes the purpose and use of a parameter - - - constraint - - - - guideline - - - - - value - - -

A set of values provided in a catalog can be redefined at any higher layer of OSCAL (e.g., Profile).

- - - - select - -

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

- - - - - - -

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

-

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

- - - - Constraint - A formal or informal expression of a constraint or test - - - Constraint Description - A textual summary of the constraint to be applied. - - - Constraint Test - A test expression which is expected to be evaluated by a tool. - - - - Constraint test - A formal (executable) expression of a constraint - - - - - - - - Guideline - A prose statement that provides a recommendation for the use of a parameter. - - - Guideline Text - Prose permits multiple paragraphs, lists, tables etc. - - - - - Parameter Value - A parameter value or set of values. - - - Selection - Presenting a choice among alternatives - - Parameter Cardinality - Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted. - - - Only one value is permitted. - One or more values are permitted. - - - - - - Choice - A value selection among several such options - choice - value - - - - -

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

- - - - Depends on - Another parameter invoking this one - - - Control Identifier Reference - A reference to a control with a corresponding id value. - - - Publication metadata - Provides information about the publication and availability of the containing document. - - - Document Title - A name given to the document, which may be used by a tool for display and navigation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

- - - - Indicates the organization that created this content. - Indicates the organization for which this content was created. - Indicates the organization responsible for all content represented in the "document". - - - The link identifies the authoritative location for this file. Defined by RFC 6596. - The link identifies an alternative location or format for this file. Defined by the HTML Living Standard - - This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - - - - - Revision History Entry - An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first). - - - Document Title - A name given to the document revision, which may be used by a tool for display and navigation. - - - - - - - - - - - - - - - - - The link identifies the authoritative location for this file. Defined by RFC 6596. - The link identifies an alternative location or format for this file. Defined by the HTML Living Standard - - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - - - -

While published, last-modified, oscal-version, and version are not required, values for these entries should be provided if the information is known. For a revision entry to be considered valid, at least one of the following items must be provided: published, last-modified, version, or a link with a rel of source.

- - - - Location - A location, with associated metadata that can be referenced. - - Location Universally Unique Identifier - A unique identifier that can be used to reference this defined location elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. - - - - Location Title - A name given to the location, which may be used by a tool for display and navigation. - - - -

Typically, the physical address of the location will be used here. If this information is sensitive, then a mailing address can be used instead.

- - - - - -

This is a contact email associated with the location.

- - - - - -

A phone number used to contact the location.

- - - - Location URL - The uniform resource locator (URL) for a web site or Internet presence associated with the location. - - - - - - - - - - - - - Characterizes the kind of location. - - - A location that contains computing assets. A class can be used to indicate a subclass of data-center. - - - The location is a data-center used for normal operations. - The location is a data-center used for fail-over or backup operations. - - - - - Location Reference - References a location defined in metadata. - - - - - - - - Location Reference - References a location defined in metadata. - - - - - - - - Party (organization or person) - A responsible entity which is either a person or an organization. - - Party Universally Unique Identifier - A unique identifier that can be used to reference this defined location elsewhere in an OSCAL document. A UUID should be consistently used for a given party across revisions of the document. - - - Party Type - A category describing the kind of party the object describes. - - - An individual. - A group of individuals formed for a specific purpose. - - - - - - Party Name - The full name of the party. This is typically the legal name associated with the party. - - - Party Short Name - A short common name, abbreviation, or acronym for the party. - - - Party External Identifier - An identifier for a person or organization using a designated scheme. e.g. an Open Researcher and Contributor ID (ORCID) - id - - - External Identifier Schema - Indicates the type of external identifier. - - - The identifier is Open Researcher and Contributor ID (ORCID). - - - - - - - - - - - - - -

This is a contact email associated with the party.

- - - - - -

A phone number used to contact the party.

- - - - - - - - - - - - Organizational Affiliation - Identifies that the party object is a member of the organization associated with the provided UUID. - - - - - - - -

Parties of both the person or organization type can be associated with an organization using the member-of-organization.

- - - - - - - A mail stop associated with the party. - The name or number of the party's office. - The formal job title of a person. - - - - - Party Reference - References a party defined in metadata. - - - - - - - - Role - Defines a function assumed or expected to be assumed by a party in a specific situation. - - Role Identifier - A unique identifier for a specific role instance. This identifier's uniqueness is document scoped and is intended to be consistent for the same role across minor revisions of the document. - -

OSCAL has defined a set of standardized roles for consistent use in OSCAL documents. This allows tools consuming OSCAL content to infer specific semantics when these roles are used. These roles are documented in the specific contexts of their use (e.g., responsible-party, responsible-role). When using such a role, it is necessary to define these roles in this list, which will then allow such a role to be referenced.

- - - - - Role Title - A name given to the role, which may be used by a tool for display and navigation. - - - Role Short Name - A short common name, abbreviation, or acronym for the role. - - - Role Description - A summary of the role's purpose and associated responsibilities. - - - - - - - - - - -

Permissible values to be determined closer to the application (e.g. by a receiving authority).

- - - - Role Identifier Reference - A reference to the roles served by the user. - - - - - - - - Back matter - A collection of resources, which may be included directly or by reference. - - - Resource - A resource associated with content in the containing document. A resource may be directly included in the document base64 encoded or may point to one or more equivalent internet resources. - - - Resource Universally Unique Identifier - A globally unique identifier that can be used to reference this defined resource elsewhere in an OSCAL document. A UUID should be consistently used for a given resource across revisions of the document. - - - - Resource Title - A name given to the resource, which may be used by a tool for display and navigation. - - - Resource Description - A short summary of the resource used to indicate the purpose of the resource. - - - - - - - - - Citation - A citation consisting of end note text and optional structured bibliographic data. - - - Citation Text - A line of citation text. - - - - - - - - - -

The text is used to define the endnote text, without any required bibliographic structure. If structured bibliographic data is needed, then the biblio can be used for this purpose.

-

A biblio can be used to capture a structured bibliographical citation in an appropriate format.

- - - - Resource link - A pointer to an external resource with an optional hash for verification and change detection. - - - Hypertext Reference - A resolvable URI reference to a resource. - - - - - - -

When appearing as part of a resource/rlink, the hash applies to the resource referenced by the href.

- - - - -

This construct is different from link, which makes no provision for a hash or formal title.

-

Multiple rlink can be included for a resource. In such a case, all provided rlink items are intended to be equivalent in content, but may differ in structure. A media-type is used to identify the format of a given rlink, and can be used to differentiate a items in a collection of rlinks. The media-type also provides a hint to the OSCAL document consumer about the structure of the resource referenced by the rlink.

- - - - Base64 - The Base64 alphabet in RFC 2045 - aligned with XSD. - value - - File Name - Name of the file before it was encoded as Base64 to be embedded in a resource. This is the name that will be assigned to the file when the file is decoded. - - - - - - - - Identifies the type of resource represented. - For resources representing a published document, this represents the version number of that document. - For resources representing a published document, this represents the publication date of that document. - - - - Indicates the resource is an organization's logo. - Indicates the resource represents an image. - Indicates the resource represents an image of screen content. - Indicates the resource represents an applicable law. - Indicates the resource represents an applicable regulation. - Indicates the resource represents an applicable standard. - Indicates the resource represents applicable guidance. - Indicates the resource provides a list of relevant acronyms. - Indicates the resource cites relevant information. - Indicates the resource is a policy. - Indicates the resource is a procedure. - Indicates the resource is guidance document related to the subject system of an SSP. - Indicates the resource is guidance document a user's guide or administrator's guide. - Indicates the resource is guidance document a administrator's guide. - Indicates the resource represents rules of behavior content. - Indicates the resource represents a plan. - Indicates the resource represents an artifact, such as may be reviewed by an assessor. - Indicates the resource represents evidence, such as to support an assessment findiing. - Indicates the resource represents output from a tool. - Indicates the resource represents machine data, which may require a tool or analysis for interpretation or presentation. - Indicates the resource represents notes from an interview, such as may be collected during an assessment. - Indicates the resource is a set of questions, possibly with responses. - Indicates the resource is a report. - Indicates the resource is a formal agreement between two or more parties. - - - - - -

Ensures that each rlink item references a unique resource.

- - - - - -

Ensures that all base64 resources have a unique filename.

- - - - - -

A title is required when a citation is provided.

- - - - - -

A resource can be used in two ways. 1) it may point to an specific retrievable network resource using a rlink, or 2) it may be included as an attachment using a base64. A resource may contain multiple rlink and base64 entries that represent alternative download locations (rlink) and attachments (base64) for the same resource. Both rlink and base64 allow for a media-type to be specified, which is used to distinguish between different representations of the same resource (e.g., Microsoft Word, PDF). When multiple rlink and base64 items are included for a given resource, all items must contain equivalent information. This allows the document consumer to choose a preferred item to process based on a the selected item's media-type. This is extremely important when the items represent OSCAL content that is represented in alternate formats (i.e., XML, JSON, YAML), allowing the same OSCAL data to be processed from any of the available formats indicated by the items.

-

When a resource includes a citation, then the title and citation properties must both be included.

- - - - - - - - - -

Provides a collection of identified resource objects that can be referenced by a link with a rel value of "reference" and an href value that is a fragment "#" followed by a reference to a reference identifier. Other specialized link "rel" values also use this pattern when indicated in that context of use.

- - - Use of link, citation, and resource - -

The following is a contrived example to show the use of link, citation, and resource.

- - - - My citation - - - - - - - - - - - Property - An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values. - prop - - Property Name - A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object. - - - A label or descriptor that is tied to a sensitivity or classification marking system. An optional class can be used to define the specific marking system used for the associated value. - - - - - Property Universally Unique Identifier - A unique identifier that can be used to reference this property elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. - - - Property Namespace - A namespace qualifying the property'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 values used in a property. This allows the semantics associated with a given name/value pair 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.

- - - - Property Value - Indicates the value of the attribute, characteristic, or quality. - - - Property Class - A textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. - -

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

- - - - - - -

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

-

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

- - - - Link - A reference to a local or remote resource - - Hypertext Reference - A resolvable URL reference to a resource. - -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

-

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

- - - - Relation - Describes the type of relationship provided by the link. This can be an indicator of the link's purpose. - - - Reference - - - - - -

The media-type provides a hint about the content model of the referenced resource. A valid entry from the IANA Media Types registry SHOULD be used.

- - - - - Link Text - A textual label to associate with the link, which may be used for presentation in a tool. - - - - - - - - - - - - - - - - -

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

-

The OSCAL link is a roughly based on the HTML link element.

- - - Providing for link integrity - -

The following is a contrived example to show the use of link, citation, and resource.

- - - My Hashed Resource - ...snip... - - - - C2E9C1..snip..F88D2E - - - - - - - - Responsible Party - A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object. - - Responsible Role - The role that the party is responsible for. - - - - - -

Specifies one or more parties that are responsible for performing the associated role.

- - - - - - - - - - - - - - - - - - - - - Responsible Role - A reference to one or more roles with responsibility for performing a function relative to the containing object. - - Responsible Role ID - The role that is responsible for the business function. - - - - - - - - - - - - - - - - Hash - A representation of a cryptographic digest generated over a resource using a specified hash algorithm. - value - - Hash algorithm - Method by which a hash is derived - - - The SHA-224 algorithm as defined by NIST FIPS 180-4. - - The SHA-256 algorithm as defined by NIST FIPS 180-4. - - The SHA-384 algorithm as defined by NIST FIPS 180-4. - - The SHA-512 algorithm as defined by NIST FIPS 180-4. - - The SHA3-224 algorithm as defined by NIST FIPS 202. - - The SHA3-256 algorithm as defined by NIST FIPS 202. - - The SHA3-384 algorithm as defined by NIST FIPS 202. - - The SHA3-512 algorithm as defined by NIST FIPS 202. - - - - -

Any other value used MUST be a value defined in the W3C XML Security Algorithm Cross-Reference Digest Methods (W3C, April 2013) or RFC 6931 Section 2.1.5 New SHA Functions.

- - - -

A hash value can be used to authenticate that a referenced resource is the same resources as was pointed to by the author of the reference.

- - - - Media Type - Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry. - - - Remarks - Additional commentary on the containing object. - - - Publication Timestamp - The date and time the document was published. The date-time value must be formatted according to RFC 3339 with full time and time zone included. - -

This value represents the point in time when the OSCAL document was published. Typically, this date value will be machine generated at the time the containing document is published.

-

In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the published value should indicate when the OSCAL document was published, not the source material. Where necessary, the publication date of the original source material can be captured as a named property or custom metadata construct.

-

A publisher of OSCAL content can use this data point along with its siblings last-modified and version to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

- - - - Last Modified Timestamp - The date and time the document was last modified. The date-time value must be formatted according to RFC 3339 with full time and time zone included. - -

This value represents the point in time when the OSCAL document was last updated, or at the point of creation the creation date. Typically, this date value will be machine generated at time of creation or modification.

-

In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the last-modified value should indicate the modification time of the OSCAL document, not the source material.

-

A publisher of OSCAL content can use this data point along with its siblings published and version to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

- - - - Document Version - A string used to distinguish the current version of the document from other previous (and future) versions. - -

A version string may be a release number, sequence number, date, or other identifier suffcient to distinguish between different document versions. This version is typically set by the document owner or by the tool used to maintain the content.

-

While not required, it is recommended that OSCAL content authors use Semantic Versioning as a format for version strings. This allows for the easy identification of a version tree consisting of major, minor, and patch numbers.

-

A publisher of OSCAL content can use this data point along with its siblings published and last-modified to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

- - - - OSCAL version - The OSCAL model version the document was authored against. - -

Indicates the version of the OSCAL model to which this data set conforms, for example 1.1.0 or 1.0.0-M1. That can be used as a hint by a tool to indicate which version of the OSCAL XML or JSON schema to use for validation.

- - - - Email Address - An email address as defined by RFC 5322 Section 3.4.1. - - - Telephone Number - Contact number by telephone. - number - - type flag - Indicates the type of phone number. - - - A home phone number. - An office phone number. - A mobile phone number. - - - - - - Address - A postal address for the location. - - type - - - - - - - City - City, town or geographical region for the mailing address. - - - State - State, province or analogous geographical region for mailing address - - - Postal Code - Postal or ZIP code for mailing address - - - Country Code - The ISO 3166-1 alpha-2 country code for the mailing address. - - - - - - - - Address line - A single line of an address. - - - Address Type - Indicates the type of address. - - - A home address. - A work address. - - - - - Document Identifier - A document identifier qualified by an identifier scheme. A document identifier provides a globally unique identifier for a group of documents that are to be treated as different versions of the same document. If this element does not appear, or if the value of this element is empty, the value of "document-id" is equal to the value of the "uuid" flag of the top-level root element. - identifier - - Document Identification Scheme - Qualifies the kind of document identifier using a URI. If the scheme is not provided the value of the element will be interpreted as a string of characters. - - - A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record. - - - - -

This element is optional, but it will always have a valid value, as if it is missing the value of "document-id" is assumed to be equal to the UUID of the root. This requirement allows for document creators to retroactively link an update to the original version, by providing a document-id on the new document that is equal to the uuid of the original document.

- - - diff --git a/test-suite/metaschema-test-coverage.md b/test-suite/schema-generation/metaschema-test-coverage.md similarity index 98% rename from test-suite/metaschema-test-coverage.md rename to test-suite/schema-generation/metaschema-test-coverage.md index b7ec8b4d2..e2bae54ab 100644 --- a/test-suite/metaschema-test-coverage.md +++ b/test-suite/schema-generation/metaschema-test-coverage.md @@ -1,6 +1,8 @@ ## What we are testing explicitly +Following checklist applies to work in the `schema-generation` folder. + ### Flag definitions ### Datatypes diff --git a/toolchains/xslt-M4/compose/metaschema-collect.xsl b/toolchains/xslt-M4/compose/metaschema-collect.xsl index 9391dad14..32b5c31d7 100644 --- a/toolchains/xslt-M4/compose/metaschema-collect.xsl +++ b/toolchains/xslt-M4/compose/metaschema-collect.xsl @@ -66,7 +66,7 @@ - + diff --git a/toolchains/xslt-M4/compose/metaschema-compose.xpl b/toolchains/xslt-M4/compose/metaschema-compose.xpl index 030a03a38..909c62f61 100644 --- a/toolchains/xslt-M4/compose/metaschema-compose.xpl +++ b/toolchains/xslt-M4/compose/metaschema-compose.xpl @@ -169,11 +169,12 @@ + - + diff --git a/toolchains/xslt-M4/compose/metaschema-prune-unused-definitions.xsl b/toolchains/xslt-M4/compose/metaschema-prune-unused-definitions.xsl index deea38a25..b316a1725 100644 --- a/toolchains/xslt-M4/compose/metaschema-prune-unused-definitions.xsl +++ b/toolchains/xslt-M4/compose/metaschema-prune-unused-definitions.xsl @@ -1,118 +1,134 @@ + exclude-result-prefixes="#all" version="3.0"> + elements="METASCHEMA define-flag define-field define-assembly remarks model choice assembly flag field"/> - yes - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + - + - + Seeing { $definitions => string-join(', ') } + No root found in this metaschema composition. - - { . } = { $reference-counts(.) } - - - - - - - - - - - unused-definition - REMOVING unused assembly definition for '{ @name }' from { ancestor::METASCHEMA[1]/@module - } - - + - + + - unused-definition - REMOVING unused field definition for '{ @name }' from { ancestor::METASCHEMA[1]/@module - } - - - - - - - unused-definition - REMOVING unused flag definition for '{ @name }' from { ancestor::METASCHEMA[1]/@module - } + REMOVING unused { $def-type } definition for '{ @name }' from { (ancestor::METASCHEMA[1]/@module,'[unnamed module]')[1] }. warning - - - - - + + + - \ No newline at end of file + diff --git a/toolchains/xslt-M4/compose/readme.md b/toolchains/xslt-M4/compose/readme.md index 5da0f708f..17e28fff9 100644 --- a/toolchains/xslt-M4/compose/readme.md +++ b/toolchains/xslt-M4/compose/readme.md @@ -2,49 +2,57 @@ Transformations in this subdirectory support Metaschema composition, that is the Generally, metaschema composition will be a necessary preliminary to producing a schema, documentation or analysis of a single metaschema. -### Metaschema Composition -The following transformations executed in sequence provide for composition of Metaschema inputs into a standalone metaschema instance. +### Implicit in many pipelines -- `metaschema-collect.xsl` -- `metaschema-build-refs.xsl` -- `metaschema-trim-extra-modules.xsl` -- `metaschema-prune-unused-definitions.xsl` -- `metaschema-resolve-use-names.xsl` -- `metaschema-resolve-sibling-names.xsl` -- `metaschema-digest.xsl` -- `annotate-composition.xsl` +The composition process is implicit in many (most) end-to-end metaschema processes including both schema and docs generation. -### Additional +For testing, entry points are also isolated for standalone metaschema composition. -The following are used in the documentation pipeline: +(TBD: a consistent way to unify these and keep them aligned) -- `annotate-composition.xsl` -- `make-model-map.xsl` -- `unfold-model-map.xsl` -- `annotate-model-map.xsl` +### XSLT for end-to-end -### xpl +Single metaschema input, with its imports available, produces single compose metaschema results. -#### metaschema-compose.xpl +* `../nist-metaschema-COMPOSE.xsl` +* With that XSLT as context, executing path `/*/*[@name='transformation-sequence']/*/('1. `' || replace(.,'.*/','') || '`') => string-join(' ')` we get (in Markdown): -- XProc pipeline version 1.0 (10 steps) -- **Purpose:** Produce a standalone Metaschema instance representing a data model, suitable for further processing -- **Input:** A valid and correct OSCAL Metaschema instance linked to its modules (also valid and correct) -- **Output:** A completely standalone Metaschema instance fully resolving and disambiguating links among definitions, suitable for further processing. +(NB: keeping this up to date enables us to track deltas in the documentation so please do edit/amend as this pipeline changes) -- Runtime dependency: `annotate-composition.xsl` +1. `metaschema-collect.xsl` +1. `metaschema-build-refs.xsl` +1. `metaschema-trim-extra-modules.xsl` +1. `metaschema-prune-unused-definitions.xsl` +1. `metaschema-resolve-use-names.xsl` +1. `metaschema-resolve-sibling-names.xsl` +1. `metaschema-digest.xsl` +1. `annotate-composition.xsl` -- Runtime dependency: `metaschema-build-refs.xsl` +### Additional processes -- Runtime dependency: `metaschema-collect.xsl` +The following are used in the documentation pipeline: + +- `annotate-composition.xsl` +- `make-model-map.xsl` +- `unfold-model-map.xsl` +- `annotate-model-map.xsl` -- Runtime dependency: `metaschema-digest.xsl` +### XProc for debugging (with more transparency as to step results) -- Runtime dependency: `metaschema-prune-unused-definitions.xsl` +Single metaschema input, with its imports available, run in an XPrc pipeline with configurable results (write any or none) giving greater transparency over intermediate steps. -- Runtime dependency: `metaschema-resolve-sibling-names.xsl` +* `metaschema-compose.xpl` +* With the XProc as context, execute +`/*/*:xslt/*:input/*:document/@href/('1. `' || . || '`') => string-join(' ')` -- Runtime dependency: `metaschema-resolve-use-names.xsl` +(NB: as above, please help keep this listing up to date) -- Runtime dependency: `metaschema-trim-extra-modules.xsl` +1. `metaschema-collect.xsl` +1. `metaschema-build-refs.xsl` +1. `metaschema-trim-extra-modules.xsl` +1. `metaschema-prune-unused-definitions.xsl` +1. `metaschema-resolve-use-names.xsl` +1. `metaschema-resolve-sibling-names.xsl` +1. `metaschema-digest.xsl` +1. `annotate-composition.xsl` diff --git a/toolchains/xslt-M4/compose/testing/.gitignore b/toolchains/xslt-M4/compose/testing/.gitignore new file mode 100644 index 000000000..8117c7855 --- /dev/null +++ b/toolchains/xslt-M4/compose/testing/.gitignore @@ -0,0 +1,4 @@ + +# Files generated by XSpec +*-result.html +*-report.html diff --git a/toolchains/xslt-M4/compose/testing/1_collected/collect-report.html b/toolchains/xslt-M4/compose/testing/1_collected/collect-report.html deleted file mode 100644 index 87930dcca..000000000 --- a/toolchains/xslt-M4/compose/testing/1_collected/collect-report.html +++ /dev/null @@ -1,650 +0,0 @@ - - - - - -
-

Working metaschema Run

-
-

Modules collected, no loops Show Q-Diff Diff

- - -
-
-
-

Metaschema skeleton Run

-
-

Modules collected, no loops Show Q-Diff Diff

- - -
-
-
-

Nested locals Run

-
-

Local definitions preserved with amended names Show Q-Diff Diff

- - -
-
- - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/1_collected/collect-result.html b/toolchains/xslt-M4/compose/testing/1_collected/collect-result.html deleted file mode 100644 index 4a31d014d..000000000 --- a/toolchains/xslt-M4/compose/testing/1_collected/collect-result.html +++ /dev/null @@ -1,921 +0,0 @@ - - - - Test Report for C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-collect.xsl (passed: 1 / pending: 0 / failed: 2 / total: 3) - - - -

Test Report

-

Stylesheet: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-collect.xsl

-

XSpec: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/testing/1_collected/collect.xspec

-

Tested: 26 April 2021 at 14:09

-

Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
passed: 1pending: 0failed: 2total: 3
Working metaschema1001
Metaschema skeleton0011
Nested locals0011
-
-

Working metaschemapassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - -
Working metaschemapassed: 1 / pending: 0 / failed: 0 / total: 1
Modules collected, no loopsSuccess
-
-
-

Metaschema skeletonpassed: 0 / pending: 0 / failed: 1 / total: 1

- - - - - - - - - - - - - - - -
Metaschema skeletonpassed: 0 / pending: 0 / failed: 1 / total: 1
Modules collected, no loopsFailure
-
-

Metaschema skeleton

-
-

Modules collected, no loops

-
❔
- - - - - - - - - - - - - -
ResultExpected Result
-

XPath /element() from:

- 
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
-            xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
-            module="test"
-            src="file:/C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/testing/1_collected/xspec/collect-compiled.xsl">
-   <short-name>test</short-name>
-   <define-assembly scope="global"
-                    name="root"
-                    module="test"
-                    key-name="test:root">
-      <root-name>root-assembly</root-name>
-      <flag required="no"
-            ref="top-level-flag" />
-      <define-flag required="no"
-                   as-type="string"
-                   name="local-flag">
-         <formal-name>Locally defined flag</formal-name>
-         <description>XXX</description>
-      </define-flag>
-      <model>
-         <field max-occurs="unbounded"
-                min-occurs="0"
-                ref="top-level-global-field">
-            <group-by name="top-level-global-field-sequence" />
-         </field>
-         <field max-occurs="1"
-                min-occurs="0"
-                ref="top-level-local-field" />
-         <define-field max-occurs="1"
-                       min-occurs="0"
-                       collapsible="no"
-                       as-type="string"
-                       name="local-field">
-            <formal-name>Locally defined field</formal-name>
-            <description>XXX</description>
-         </define-field>
-      </model>
-   </define-assembly>
-   <define-field collapsible="no"
-                 as-type="string"
-                 scope="global"
-                 name="top-level-global-field"
-                 module="test"
-                 key-name="test:top-level-global-field" />
-   <define-field collapsible="no"
-                 as-type="string"
-                 scope="local"
-                 name="top-level-local-field"
-                 module="test"
-                 key-name="test:top-level-local-field" />
-   <define-flag as-type="string"
-                scope="global"
-                name="top-level-flag"
-                module="test"
-                key-name="test:top-level-flag" />
-</METASCHEMA>
- 		-

XPath /element() from:

- 
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
-            xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
-            src="..."
-            module="test">
-   <short-name>test</short-name>
-   <define-assembly name="root"
-                    module="test"
-                    key-name="test:root"
-                    scope="global">
-      <root-name>root-assembly</root-name>
-      <flag ref="top-level-flag"
-            required="no">
-         <use-name>tlf</use-name>
-      </flag>
-      <define-flag name="local-flag"
-                   as-type="string"
-                   required="no">
-         <formal-name>Locally defined flag</formal-name>
-         <description>XXX</description>
-      </define-flag>
-      <model>
-         <field ref="top-level-global-field"
-                min-occurs="0"
-                max-occurs="unbounded">
-            <group-by name="top-level-global-field-sequence" />
-         </field>
-         <field ref="top-level-local-field"
-                min-occurs="0"
-                max-occurs="1" />
-         <define-field name="local-field"
-                       as-type="string"
-                       min-occurs="0"
-                       max-occurs="1"
-                       collapsible="no">
-            <formal-name>Locally defined field</formal-name>
-            <description>XXX</description>
-         </define-field>
-      </model>
-   </define-assembly>
-   <define-field name="top-level-global-field"
-                 module="test"
-                 key-name="test:top-level-global-field"
-                 scope="global"
-                 as-type="string"
-                 collapsible="no" />
-   <define-field name="top-level-local-field"
-                 scope="local"
-                 module="test"
-                 key-name="test:top-level-local-field"
-                 as-type="string"
-                 collapsible="no" />
-   <define-flag name="top-level-flag"
-                module="test"
-                key-name="test:top-level-flag"
-                scope="global"
-                as-type="string" />
-</METASCHEMA>
-
-
-
-
-
-

Nested localspassed: 0 / pending: 0 / failed: 1 / total: 1

- - - - - - - - - - - - - - - -
Nested localspassed: 0 / pending: 0 / failed: 1 / total: 1
Local definitions preserved with amended namesFailure
-
-

Nested locals

-
-

Local definitions preserved with amended names

-
❔
- - - - - - - - - - - - - -
ResultExpected Result
-

XPath /element() from:

- 
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
-            xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
-            module="test"
-            src="file:/C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/testing/1_collected/xspec/collect-compiled.xsl">
-   <short-name>test</short-name>
-   <define-assembly scope="global"
-                    name="root"
-                    module="test"
-                    key-name="test:root">
-      <root-name>root-assembly</root-name>
-      <flag required="no"
-            ref="top-level-flag">
-         <use-name>tlf</use-name>
-      </flag>
-      <define-flag required="no"
-                   as-type="string"
-                   name="local-flag">
-         <formal-name>Locally defined flag</formal-name>
-         <description>XXX</description>
-      </define-flag>
-      <model>
-         <field max-occurs="1"
-                min-occurs="0"
-                ref="top-level-global-field" />
-         <field max-occurs="1"
-                min-occurs="0"
-                ref="top-level-local-field" />
-         <assembly max-occurs="1"
-                   min-occurs="0"
-                   ref="top-level-local-assembly" />
-         <define-field max-occurs="1"
-                       min-occurs="0"
-                       collapsible="no"
-                       as-type="string"
-                       name="local-field">
-            <formal-name>Locally defined field</formal-name>
-            <description>XXX</description>
-         </define-field>
-      </model>
-   </define-assembly>
-   <define-field collapsible="no"
-                 as-type="string"
-                 scope="global"
-                 name="top-level-global-field"
-                 module="test"
-                 key-name="test:top-level-global-field" />
-   <define-field collapsible="no"
-                 as-type="string"
-                 scope="local"
-                 name="top-level-local-field"
-                 module="test"
-                 key-name="test:top-level-local-field">
-      <formal-name>Included twice</formal-name>
-   </define-field>
-   <define-assembly scope="local"
-                    name="top-level-local-assembly"
-                    module="test"
-                    key-name="test:top-level-local-assembly">
-      <model>
-         <field max-occurs="1"
-                min-occurs="0"
-                ref="top-level-local-field" />
-         <assembly max-occurs="1"
-                   min-occurs="0"
-                   ref="top-level-local-assembly" />
-      </model>
-   </define-assembly>
-   <define-flag as-type="string"
-                scope="global"
-                name="top-level-flag"
-                module="test"
-                key-name="test:top-level-flag" />
-</METASCHEMA>
- 		-

XPath /element() from:

- 
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
-            xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
-            src="..."
-            module="test">
-   <short-name>test</short-name>
-   <define-assembly name="root"
-                    module="test"
-                    key-name="test:root"
-                    scope="global">
-      <root-name>root-assembly</root-name>
-      <flag ref="top-level-flag"
-            required="no" />
-      <define-flag name="local-flag"
-                   as-type="string"
-                   required="no">
-         <formal-name>Locally defined flag</formal-name>
-         <description>XXX</description>
-      </define-flag>
-      <model>
-         <field ref="top-level-global-field"
-                min-occurs="0"
-                max-occurs="1" />
-         <field ref="top-level-local-field"
-                min-occurs="0"
-                max-occurs="1" />
-         <assembly ref="top-level-local-assembly"
-                   min-occurs="0"
-                   max-occurs="1" />
-         <define-field name="local-field"
-                       as-type="string"
-                       min-occurs="0"
-                       max-occurs="1"
-                       collapsible="no">
-            <formal-name>Locally defined field</formal-name>
-            <description>XXX</description>
-         </define-field>
-      </model>
-   </define-assembly>
-   <define-field name="top-level-global-field"
-                 module="test"
-                 key-name="test:top-level-global-field"
-                 scope="global"
-                 as-type="string"
-                 collapsible="no" />
-   <define-field name="top-level-local-field"
-                 scope="local"
-                 module="test"
-                 key-name="test:top-level-local-field"
-                 as-type="string"
-                 collapsible="no">
-      <formal-name>Included twice</formal-name>
-   </define-field>
-   <define-assembly name="top-level-local-assembly"
-                    scope="local"
-                    module="test"
-                    key-name="test:top-level-local-assembly">
-      <model>
-         <field ref="top-level-local-field"
-                min-occurs="0"
-                max-occurs="1" />
-         <assembly ref="top-level-local-assembly"
-                   min-occurs="0"
-                   max-occurs="1" />
-      </model>
-   </define-assembly>
-   <define-flag name="top-level-flag"
-                module="test"
-                key-name="test:top-level-flag"
-                scope="global"
-                as-type="string" />
-</METASCHEMA>
-
-
-
-
- - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/1_collected/collect.xspec b/toolchains/xslt-M4/compose/testing/1_collected/collect.xspec index 53559a17d..d781929f6 100644 --- a/toolchains/xslt-M4/compose/testing/1_collected/collect.xspec +++ b/toolchains/xslt-M4/compose/testing/1_collected/collect.xspec @@ -13,10 +13,10 @@ - + - + @@ -74,7 +74,7 @@ - + diff --git a/toolchains/xslt-M4/compose/testing/1_collected/working_metaschema-COLLECTED.xml b/toolchains/xslt-M4/compose/testing/1_collected/working_metaschema-COLLECTED.xml index 7c7a1763d..97985b850 100644 --- a/toolchains/xslt-M4/compose/testing/1_collected/working_metaschema-COLLECTED.xml +++ b/toolchains/xslt-M4/compose/testing/1_collected/working_metaschema-COLLECTED.xml @@ -1,75 +1,134 @@ - + OSCAL TEST Format 0.0 oscal-test http://csrc.nist.gov/ns/metaschema/test + http://csrc.nist.gov/ns/metaschema/test

For exercising Metaschema semantics with respect to modular assembly and composition.

 - + Nominal root XXX root-assembly - - + + Flag defined inline on root-assembly XXX - - - + + + Field defined inline on root-assembly XXX - + Field, defined at top level (global by default) XXX - + Field, defined in module 'oscal-test' at top level as 'local' XXX - + Flag, defined globally XXX + _base-uri="file:/C:/Users/wap1/Documents/usnistgov/metaschema/toolchains/xslt-M4/compose/testing/module_metaschema.xml"> OSCAL TEST Format Module 0.0 oscal-test-m1 http://csrc.nist.gov/ns/metaschema/test - + Assembly defined in a module XXX - + Flag defined inline XXX - - + + + min-occurs="0" + collapsible="no" + as-type="string" + name="inline-field"> Locally defined field XXX - + Field, defined in module 'oscal-test-m1' (global by default) XXX - + Field, defined in module 'oscal-test-m1' as local ZZZ - + diff --git a/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1-result.html b/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1-result.html deleted file mode 100644 index 7a336afa2..000000000 --- a/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1-result.html +++ /dev/null @@ -1,589 +0,0 @@ - - - - Test Report for C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-reduce1.xsl (passed: 2 / pending: 0 / failed: 0 / total: 2) - - - -

Test Report

-

Stylesheet: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-reduce1.xsl

-

XSpec: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1.xspec

-

Tested: 16 October 2020 at 12:56

-

Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
passed: 2pending: 0failed: 0total: 2
Working metaschema1001
Drop an extra1001
-
-

Working metaschemapassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - -
Working metaschemapassed: 1 / pending: 0 / failed: 0 / total: 1
Last definition is keptSuccess
-
-
-

Drop an extrapassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - -
Drop an extrapassed: 1 / pending: 0 / failed: 0 / total: 1
Only the second 'top-level-global-field' is keptSuccess
-
- - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1.xspec b/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1.xspec deleted file mode 100644 index 9daceffe6..000000000 --- a/toolchains/xslt-M4/compose/testing/2_reduced1/reduce1.xspec +++ /dev/null @@ -1,64 +0,0 @@ - - - - - - - - - - - - - - - root-assembly - - - - - - - - - - Discard me - - - Keep me - - - - - - - - root-assembly - - - - - - - - - - Keep me - - - - - - - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/2_reduced1/working_metaschema-REDUCED1.xml b/toolchains/xslt-M4/compose/testing/2_reduced1/working_metaschema-REDUCED1.xml deleted file mode 100644 index 119f1c513..000000000 --- a/toolchains/xslt-M4/compose/testing/2_reduced1/working_metaschema-REDUCED1.xml +++ /dev/null @@ -1,69 +0,0 @@ - - OSCAL TEST Format - 0.0 - oscal-test - http://csrc.nist.gov/ns/metaschema/test - -

For exercising Metaschema semantics with respect to modular assembly and composition.

- - - OSCAL TEST Format Module - 0.0 - oscal-test - http://csrc.nist.gov/ns/metaschema/test - - Assembly defined in a module - XXX - - Locally defined flag - XXX - - - - - Field, defined in a module as 'local', should appear as 'local' - ZZZ - - - Locally defined field - XXX - - - - - Field, defined in a module (global by default) - XXX - - - - Nominal root - XXX - root-assembly - - - Locally defined flag - XXX - - - - - Field, defined at top level as 'local' - XXX - - - Locally defined field - XXX - - - - - Field, defined at top level (global by default) - XXX - - - Flag, defined at top level - XXX - - diff --git a/toolchains/xslt-M4/compose/testing/3_digested/digested-result.html b/toolchains/xslt-M4/compose/testing/3_digested/digested-result.html deleted file mode 100644 index 0829a28e5..000000000 --- a/toolchains/xslt-M4/compose/testing/3_digested/digested-result.html +++ /dev/null @@ -1,563 +0,0 @@ - - - - Test Report for C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-digest.xsl (passed: 1 / pending: 0 / failed: 0 / total: 1) - - - -

Test Report

-

Stylesheet: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/metaschema-digest.xsl

-

XSpec: C:/Users/wap1/Documents/usnistgov/OSCAL/build/metaschema/toolchains/xslt-M4/compose/testing/4_digested/digested.xspec

-

Tested: 15 October 2020 at 16:41

-

Contents

- - - - - - - - - - - - - - - - - - - - - - - - - - -
passed: 1pending: 0failed: 0total: 1
Modular Assembly1001
-
-

Modular Assemblypassed: 1 / pending: 0 / failed: 0 / total: 1

- - - - - - - - - - - - - - - -
Modular Assemblypassed: 1 / pending: 0 / failed: 0 / total: 1
Basic metaschema compositionSuccess
-
- - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/3_digested/digested.xspec b/toolchains/xslt-M4/compose/testing/3_digested/digested.xspec deleted file mode 100644 index 9c5c7a2da..000000000 --- a/toolchains/xslt-M4/compose/testing/3_digested/digested.xspec +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/4_pruning/prune-unused-definitions.xspec b/toolchains/xslt-M4/compose/testing/4_pruning/prune-unused-definitions.xspec new file mode 100644 index 000000000..e8b8fa4db --- /dev/null +++ b/toolchains/xslt-M4/compose/testing/4_pruning/prune-unused-definitions.xspec @@ -0,0 +1,52 @@ + + + + + + + + + + Unused assembly + Should not be copied + + + + + + BOX + An empty box, the root of the model, should be copied + BOX + + + + Unused field + Unused field is used only by unused-assembly + + + + + + Seeing assembly#nestedmessy:BOX + REMOVING unused assembly definition for 'unused-assembly' from nestedmessy. + + BOX + An empty box + BOX + + + REMOVING unused field definition for 'unused-field' from nestedmessy. + + + + + + + + + diff --git a/toolchains/xslt-M4/compose/testing/7_digesting/digested.xspec b/toolchains/xslt-M4/compose/testing/7_digesting/digested.xspec new file mode 100644 index 000000000..88e24ae19 --- /dev/null +++ b/toolchains/xslt-M4/compose/testing/7_digesting/digested.xspec @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/toolchains/xslt-M4/compose/testing/3_digested/working_metaschema-DIGESTED.xml b/toolchains/xslt-M4/compose/testing/7_digesting/working_metaschema-DIGESTED.xml similarity index 100% rename from toolchains/xslt-M4/compose/testing/3_digested/working_metaschema-DIGESTED.xml rename to toolchains/xslt-M4/compose/testing/7_digesting/working_metaschema-DIGESTED.xml diff --git a/toolchains/xslt-M4/compose/testing/readme.md b/toolchains/xslt-M4/compose/testing/readme.md new file mode 100644 index 000000000..accf43648 --- /dev/null +++ b/toolchains/xslt-M4/compose/testing/readme.md @@ -0,0 +1,32 @@ +# XSLT M4 Implementation Testing + +Each folder contains one or more XSpecs, testing one or more functions or transformations specific to the XSLT M4 processing pipeline. + +In the pipeline each of the transformations is executed in turn, each one reading for its inputs the results of the transformation preceding it. Together, they accomplish the entire operation of metaschema composition. These tests exercise the separate phases in isolation from one another, so these transitions can be exposed and managed. + +See the `*.xspec` files in each folder for more details. + +End to end tests for any metaschema composition process -- not only this set of XSLT transformations -- can be found [in its own folder in this repository](../../../../test-suite/metaschema-xspec/). + +## Dev strategy + +Each step needs tests specifically tailored to the functional requirements of that step. These are in progress. + +Also, for each step we need not only standalone tests, but standoff file tests with externally maintained `expected` folders. + +With these in place, each step can have at least one test that works on inputs in the `expected` folder of the preceding branch, to help maintain alignment among the tests. + +TODO: +- update present tests +- build out more tests + - work up to three variants? skeletal, basic and pathological (showing errors/exceptions) + - also unit test any special handling or reasonable edge conditions +- pull together 'predecessor' tests that formalize the chain +- extend XSD / Schematron to support final results? + +## Entry points + +See the [readme in the parent folder](../readme.md) for details about metaschema composition. The XProcs here are designed to test one or another of the single phases of transformation that are executed in the M4 metaschema composition sequence. + +Accordingly, samples of metaschema inputs given with these tests will typically specify *intermediate* results that are not expected to persist in the system, ordinarily, after final results are delivered. + diff --git a/toolchains/xslt-M4/compose/testing/working_metaschema.xml b/toolchains/xslt-M4/compose/testing/working_metaschema.xml index 95225b531..c960dae4d 100644 --- a/toolchains/xslt-M4/compose/testing/working_metaschema.xml +++ b/toolchains/xslt-M4/compose/testing/working_metaschema.xml @@ -9,6 +9,7 @@ 0.0 oscal-test http://csrc.nist.gov/ns/metaschema/test + http://csrc.nist.gov/ns/metaschema/test

For exercising Metaschema semantics with respect to modular assembly and composition.