From b7c12777df51ae7479772ec56c9adf465f6ec599 Mon Sep 17 00:00:00 2001
From: galtm <40716346+galtm@users.noreply.github.com>
Date: Mon, 31 Jan 2022 09:54:11 -0800
Subject: [PATCH 1/3] Metadata tests and way of determining top UUID

- Remove global parameter assign-uuid (note backward incompatibility - is it OK?)
- Instead, support global parameters uuid-method and top-uuid, in uuid-method-choice.xsl
- Support global parameter hide-source-profile-uri
- Stub of opr:oscal-version function
- Stub of message handler template, using xsl:message for now
- Add XSpec tests
---
 .../example-set.xspec                         |   3 +-
 .../resolver-pipeline/message-handler.xsl     |  19 +
 .../oscal-profile-RESOLVE.xsl                 |  49 +-
 .../oscal-profile-resolve-metadata.xsl        |  76 ++-
 .../testing/2_metadata/metadata.xspec         | 437 +++++++++++++-----
 .../2_metadata/uuid-method-choice.xspec       |  86 ++++
 .../testing/2_metadata/uuid-value.txt         |   1 +
 .../resolver-pipeline/uuid-method-choice.xsl  |  89 ++++
 8 files changed, 589 insertions(+), 171 deletions(-)
 create mode 100644 src/utils/util/resolver-pipeline/message-handler.xsl
 create mode 100644 src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec
 create mode 100644 src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt
 create mode 100644 src/utils/util/resolver-pipeline/uuid-method-choice.xsl

diff --git a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec
index b5d8326d73..e17d79042b 100644
--- a/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec
+++ b/src/specifications/profile-resolution/profile-resolution-examples/example-set.xspec
@@ -3,7 +3,8 @@
     xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
     stylesheet="../../../utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl"
     run-as="external">
-    <!--<x:param name="assign-uuid">00000000-0000-4000-A000-000000000000</x:param>-->
+    <!--<x:param name="top-uuid">00000000-0000-4000-A000-000000000000</x:param>
+        <x:param name="uuid-method" select="'user-provided'"/>-->
     
 <!-- x:description/@run-as='external' permits the context item to be determined dynamically per scenario
     cf https://github.com/xspec/xspec/wiki/External-Transformation#global-context-item
diff --git a/src/utils/util/resolver-pipeline/message-handler.xsl b/src/utils/util/resolver-pipeline/message-handler.xsl
new file mode 100644
index 0000000000..7b0420fbb7
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/message-handler.xsl
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
+    xmlns:mh="http://csrc.nist.gov/ns/message"
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    exclude-result-prefixes="#all"
+    version="3.0">
+    
+    <xsl:template name="mh:message-handler">
+        <xsl:param name="text" as="xs:string"/>
+        <xsl:param name="message-type" as="xs:string?"/><!-- e.g., 'Error', 'Warning' -->
+        <xsl:param name="error-code" as="xs:string?"/>
+        <xsl:param name="terminate" as="xs:boolean" select="false()"/>
+        <xsl:message expand-text="yes" terminate="{$terminate}">{
+            string-join(($message-type, $error-code, $text),': ')
+            }</xsl:message>
+    </xsl:template>
+
+</xsl:stylesheet>
\ No newline at end of file
diff --git a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
index 025a5785a9..169a7bd841 100644
--- a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
+++ b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
@@ -1,11 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
+    xmlns:u="http://csrc.nist.gov/ns/uuid"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     exclude-result-prefixes="#all"
-    xmlns:javaUUID="java.util.UUID"
-    xmlns:r="http://csrc.nist.gov/ns/random"
     xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0">
 
     <!--
@@ -22,8 +21,10 @@
 
     <xsl:output method="xml" indent="yes"/>
 
-    <xsl:import href="random-util.xsl"/>
-    
+    <!-- uuid-method-choice.xsl has global parameters
+        $uuid-method, $top-uuid, and $uuid-service. -->
+    <xsl:import href="uuid-method-choice.xsl"/>
+
     <xsl:strip-space
         elements="catalog group control param guideline select part
         metadata back-matter annotation party person org rlink address resource role responsible-party citation
@@ -35,36 +36,8 @@
 
     <xsl:param name="trace" as="xs:string">off</xsl:param>
     
-    <!-- Provide a top-level UUID for the result catalog as $assign-uuid,
-         or assign-uuid=make-uuid for a native (XSLT 3.0) function call. -->
-    <xsl:param name="assign-uuid" as="xs:string?"/>
-    <!-- Alternatively, call a web site if the processor supports it -->
-    <xsl:param name="uuid-service" select="'https://www.uuidgenerator.net/api/version4'"/>
-    
-    <!-- For checking a UUID before assigning it. -->
-    <xsl:variable name="uuid-v4-regex" as="xs:string">^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$</xsl:variable>
-    
     <xsl:param name="uri-stack" as="xs:anyURI*" select="()"/>
-
-    <xsl:variable name="use-uuid" as="xs:string">
-        <xsl:choose>
-            <xsl:when test="matches($assign-uuid,$uuid-v4-regex)">
-                <xsl:sequence select="$assign-uuid"/>
-            </xsl:when>
-            <xsl:when use-when="function-available('random-number-generator')" test="$assign-uuid = 'make-uuid'">
-                <!-- seed splices a timestamp with a given @uuid -->
-                <xsl:sequence select="r:make-uuid( /*/@uuid || '-' || replace( string(current-dateTime()),'\D','') )"/>
-            </xsl:when>
-            <xsl:when use-when="function-available('javaUUID:randomUUID')" test="function-available('javaUUID:randomUUID')">
-                <xsl:sequence select="javaUUID:randomUUID()"/>
-            </xsl:when>
-            <xsl:when test="unparsed-text-available($uuid-service)">
-                <xsl:sequence select="unparsed-text($uuid-service)"/>
-            </xsl:when>
-            <xsl:otherwise>00000000-0000-4000-B000-000000000000</xsl:otherwise>
-        </xsl:choose>
-    </xsl:variable>
-
+    
     <!-- $path-to-source should point back to the location of the source catalog (or profile) from its result,
          so '..' is appropriate when writing results down a directory. -->
     <xsl:param name="path-to-source" as="xs:string?"/>
@@ -73,6 +46,10 @@
 
     <xsl:param name="home" select="/"/>
 
+    <!-- If true, do not record profile URI in output catalog's source-profile
+        metadata, due to privacy or security concerns. -->
+    <xsl:param name="hide-source-profile-uri" as="xs:boolean" select="false()"/>
+
     <!-- The $transformation-sequence declares transformations to be applied in order. -->
     <xsl:variable name="transformation-sequence">
         <opr:transform version="2.0">oscal-profile-resolve-select.xsl</opr:transform>
@@ -109,8 +86,10 @@
     <xsl:template mode="opr:provide-parameters" match="opr:transform"/>
     
     <xsl:template mode="opr:provide-parameters" match="opr:transform[.='oscal-profile-resolve-metadata.xsl']">
-        <!-- Since the fallback is not a valid URI the processor will try Java -->
-        <xsl:map-entry key="QName('','assign-uuid')" select="$use-uuid"/>
+        <xsl:map-entry key="QName('','top-uuid-computed')">
+            <xsl:call-template name="u:determine-uuid"/>
+        </xsl:map-entry>
+        <xsl:map-entry key="QName('','hide-source-profile-uri')" select="$hide-source-profile-uri"/>
     </xsl:template>
     
     <!-- for opr:transformation, the semantics are "apply this XSLT" -->
diff --git a/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl b/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl
index 2f45c909bd..da67371d88 100644
--- a/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl
+++ b/src/utils/util/resolver-pipeline/oscal-profile-resolve-metadata.xsl
@@ -6,29 +6,53 @@
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:math="http://www.w3.org/2005/xpath-functions/math"
     xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
-    exclude-result-prefixes="xs math o opr"
+    xmlns:u="http://csrc.nist.gov/ns/uuid"
+    exclude-result-prefixes="xs math o opr u"
     xpath-default-namespace="http://csrc.nist.gov/ns/oscal/1.0" >
-
+    
     <!-- XSLT 2.0 so as to validate against XSLT 3.0 constructs -->
+    
+    <!-- How to specify top-level UUID for result catalog:
+
+        a) When oscal-profile-RESOLVE.xsl invokes this transform,
+        it passes in a precomputed value for $top-uuid-computed.
+
+        b) Any other caller of this transform should pass in
+        $uuid-method and, if applicable, $top-uuid and $uuid-service,
+        but not $top-uuid-computed. As a result, this transform
+        will compute $top-uuid-computed.
+        -->
+
+    <!-- uuid-method-choice.xsl has global parameters
+        $uuid-method, $top-uuid, and $uuid-service. -->
+    <xsl:import href="uuid-method-choice.xsl"/>
+
+    <!-- Top-level UUID for result catalog. -->
+    <xsl:param name="top-uuid-computed"  as="xs:string">
+        <xsl:call-template name="u:determine-uuid"/>
+    </xsl:param>
 
     <xsl:param name="profile-origin-uri">urn:UNKNOWN</xsl:param>
 
-    <!-- Accepts a uuid as $assign-uuid, or provides a dummy UUID. A calling application can provide a 'random' UUID.  -->
-    <xsl:param name="assign-uuid"  as="xs:string?"/>
-    
-    <xsl:variable name="uuid-v4-regex" as="xs:string">^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$</xsl:variable>
+    <!-- If true, do not record profile URI in output catalog's source-profile
+        metadata, due to privacy or security concerns. This parameter is
+        passed from oscal-profile-RESOLVE.xsl and the end user can override it. -->
+    <xsl:param name="hide-source-profile-uri" as="xs:boolean" select="false()"/>
     
-    <xsl:variable name="use-uuid" as="xs:string"
-        select="( $assign-uuid[matches(.,$uuid-v4-regex)], '00000000-0000-4000-B000-000000000000' )[1]"/>
-       
-    <xsl:template match="* | @*" mode="#all">
+    <!-- Version of this resolution tool -->
+    <xsl:variable name="tool-oscal-version" as="xs:string" select="'1.1.0'"/>
+
+    <xsl:variable name="source-profile" as="xs:string"
+        select="if ($hide-source-profile-uri) then 'profile' else $profile-origin-uri"/>
+
+    <xsl:template match="/ | * | @*" mode="#all">
         <xsl:copy>
             <xsl:apply-templates mode="#current" select="node() | @*"/>
         </xsl:copy>
     </xsl:template>
 
     <xsl:template match="profile" priority="1">
-        <catalog uuid="{ $use-uuid }">
+        <catalog uuid="{ $top-uuid-computed }">
             <!-- Rewriting top-level @id -->
             <!--<xsl:if test="function-available('uuid:randomUUID')" xmlns:uuid="java:java.util.UUID">
                 <xsl:attribute name="uuid" select="uuid:randomUUID()"/>
@@ -38,12 +62,13 @@
     </xsl:template>
 
     <xsl:template match="profile/metadata">
-        <xsl:variable name="leaders" select="(title | published | last-modified | version | oscal-version | doc-id)"/>
+        <xsl:variable name="leaders" select="(title | published | last-modified | version | oscal-version | document-id)"/>
         <xsl:copy>
             <xsl:apply-templates mode="#current" select="@*"/>
             <xsl:apply-templates mode="#current" select="$leaders"/>
             <xsl:apply-templates mode="#current" select="prop"/>
-            <link href="{$profile-origin-uri}" rel="resolution-source"/>
+            <prop name="resolution-tool" value="OSCAL Profile Resolver XSLT Pipeline OPRXP"/>
+            <link href="{$source-profile}" rel="source-profile"/>
             <xsl:apply-templates mode="#current" select="* except ($leaders | prop)"/>
             <!--<xsl:apply-templates select="../selection" mode="imported-metadata"/>-->
         </xsl:copy>
@@ -55,13 +80,34 @@
         </xsl:copy>
     </xsl:template>
 
+    <xsl:template match="profile/metadata/oscal-version">
+        <xsl:copy>
+            <xsl:sequence select="opr:oscal-version(
+                .,
+                ancestor::profile/selection/metadata/oscal-version/normalize-space(),
+                $tool-oscal-version
+                )"/>
+        </xsl:copy>
+    </xsl:template>
+
+    <!-- If there is a common major version among all inputs,
+        return the most recent minor version or the tool version,
+        whichever is earlier.
+        If there is no common major version, return fatal error. -->
+    <xsl:function name="opr:oscal-version" as="xs:string">
+        <xsl:param name="source" as="xs:string"/>
+        <xsl:param name="imported" as="xs:string*"/>
+        <xsl:param name="tool" as="xs:string"/>
+        <xsl:value-of select="'TODO: Not implemented yet'"/>
+    </xsl:function>
+
     <!--<xsl:template match="selection" mode="imported-metadata">
         <resource id="{@id}-RESOURCE" rel="imported">
             <xsl:copy-of select="metadata/title" copy-namespaces="no"/>
             <rlink href="{@opr:src}"/>
         </resource>
     </xsl:template>-->
-
+    
     <xsl:template match="selection/metadata"/>
-
+    
 </xsl:stylesheet>
diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec b/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec
index a670f3b298..2cb9d2fade 100644
--- a/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec
+++ b/src/utils/util/resolver-pipeline/testing/2_metadata/metadata.xspec
@@ -1,162 +1,359 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <x:description
-    xmlns="http://csrc.nist.gov/ns/oscal/1.0" xmlns:x="http://www.jenitennison.com/xslt/xspec"
+    xmlns="http://csrc.nist.gov/ns/oscal/1.0"    
+    xmlns:o="http://csrc.nist.gov/ns/oscal/1.0"
+    xmlns:opr="http://csrc.nist.gov/ns/oscal/profile-resolution"
+    xmlns:ov="http://csrc.nist.gov/ns/oscal/xspec/variable"
+    xmlns:x="http://www.jenitennison.com/xslt/xspec"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    run-as="external"
     stylesheet="../../oscal-profile-resolve-metadata.xsl">
-    <x:scenario label="Base">
-        <x:context>
-            <profile uuid="test"/>
-        </x:context>
-
-        <x:expect label="profile becomes catalog">
-            <catalog uuid="..."/>
-        </x:expect>
-    </x:scenario>
+    
+    <!-- In this file, the purpose of run-as="external" is to enable
+        individual scenarios to specify values of global XSLT
+        parameters. -->
 
-    <x:scenario label="floor">
-        <x:context>
-            <profile uuid="test">
+    <x:variable name="ov:sample-output-from-pipeline-step-1" as="element(o:profile)">
+        <profile uuid="cb1ec926-3441-458f-8cce-ea11308c9d37">
+            <metadata>
+                <title>Test Profile</title>
+                <last-modified>2021-05-30T14:39:35.84-04:00</last-modified>
+                <version>1.3</version>
+                <oscal-version>1.0.1</oscal-version>
+            </metadata>
+            <selection uuid="6498eb6e-8653-4470-8b97-54054d3ba886" opr:src="some-value">
                 <metadata>
-                    <title>Small Profile for Testing</title>
-                    <last-modified>2019-11-13T12:13:58.517-05:00</last-modified>
+                    <title>XYZ Tiny Catalog</title>
+                    <last-modified>2020-05-30T14:51:42.355-04:00</last-modified>
                     <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
+                    <oscal-version>1.0.0</oscal-version>
+                    <prop name="catalog-required" value="some value"/>
+                    <link href="#catalog-internal"><text>Internal link within catalog</text></link>
                 </metadata>
-            </profile>
-        </x:context>
+                <group opr:id="some-id">
+                    <title>Group X of XYZ</title>
+                </group>
+            </selection>
+        </profile>
+    </x:variable>
 
-        <x:expect label="profile becomes catalog">
-            <catalog uuid="...">
-                <metadata>
-                    <title>Small Profile for Testing</title>
-                    <last-modified>...</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
-                    <link href="urn:UNKNOWN" rel="resolution-source"/>
-                </metadata>
-            </catalog>
-        </x:expect>
+    <x:scenario label="Tests for match='/ | * | @*' template for all modes">
+        <x:variable name="ov:arbitrary-element" as="element(arbitrary-element)">
+            <arbitrary-element xmlns="" arbitrary-attribute="val">text<child/></arbitrary-element>
+        </x:variable>
+        <x:scenario label="Element">
+            <x:context select="$ov:arbitrary-element"/>
+            <x:expect label="Copy" select="$ov:arbitrary-element"/>
+        </x:scenario>
+        <x:scenario label="Attribute">
+            <x:context select="$ov:arbitrary-element/@arbitrary-attribute"/>
+            <x:expect label="Copy"
+                test="$x:result instance of attribute(arbitrary-attribute) and $x:result/string()='val'"/>
+        </x:scenario>
     </x:scenario>
-    <x:scenario label="enhance metadata">
+
+    <x:scenario label="Tests for match=profile template">
+        <x:variable name="ov:top-uuid" as="xs:string"
+            select="'12345678-90AB-4CDE-a012-bcdef0123456'"/>
+        <x:param name="profile-origin-uri" select="'urn:UNKNOWN/some-profile-filename.xml'"/>
         <x:context>
-            <profile uuid="pathological-profile">
+            <profile uuid="test"/>
+        </x:context>
+        <x:scenario label="Basic case">
+            <x:param name="top-uuid" select="$ov:top-uuid"/>
+            <x:param name="uuid-method" select="'user-provided'"/>
+            <x:expect label="Catalog uses specified uuid"
+                test="/o:catalog/@uuid/string()" select="$ov:top-uuid"/>
+        </x:scenario>
+        <x:scenario label="selection/metadata has prop and link children">
+            <x:context select="$ov:sample-output-from-pipeline-step-1"/>            
+            <x:expect label="Source catalog prop does not leak into output catalog metadata"
+                test="exists(/o:catalog/o:metadata) and
+                empty(/o:catalog/o:metadata/o:prop[@name='catalog-required'])"/>
+            <x:expect label="Source catalog link does not leak into output catalog metadata"
+                test="exists(/o:catalog/o:metadata) and
+                empty(/o:catalog/o:metadata/o:link[@href='#catalog-internal'])"/>
+        </x:scenario>
+    </x:scenario>
+
+    <x:scenario label="Tests for match=profile/metadata template">
+        <x:scenario label="Simple case">
+            <x:context select="$ov:sample-output-from-pipeline-step-1/o:metadata"/>
+            <x:expect label="Metadata includes profile version, resolution-tool prop, and source-profile link">
                 <metadata>
-                    <title>Pathological Profile</title>
-                    <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
+                    <title>Test Profile</title>
+                    <last-modified>...</last-modified>
+                    <version>1.3</version>
+                    <oscal-version>...</oscal-version>
+                    <prop name="resolution-tool" value="OSCAL Profile Resolver XSLT Pipeline OPRXP" />
+                    <link href="urn:UNKNOWN" rel="source-profile" />
                 </metadata>
-                <selection uuid="abc-full_catalog">
+            </x:expect>
+            <x:expect label="version value matches version of source profile"
+                test="/o:metadata/o:version/string()" select="'1.3'"/>
+        </x:scenario>
+        <x:scenario label="profile/metadata has additional children, 'leader' and others">
+            <x:context select="/o:profile/o:metadata">
+                <profile uuid="pathological-profile">
                     <metadata>
-                        <title>ABC Catalog</title>
-                        <last-modified>2019-11-01T10:16:22.939-04:00</last-modified>
+                        <title>Pathological Profile</title>
+                        <published>2019-11-13T12:41:07.061-05:00</published>
+                        <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
                         <version>1.0</version>
                         <oscal-version>1.0-rc2</oscal-version>
+                        <document-id scheme="https://www.doi.org/">...doi...</document-id>
+                        <party>
+                            <org>
+                                <org-name>Standing Committee</org-name>
+                            </org>
+                        </party>
                     </metadata>
-                </selection>
-            </profile>
-        </x:context>
-
-        <x:expect label="title amended, with properties and link added">
-            <catalog uuid="...">
+                </profile>
+            </x:context>            
+            <x:expect label="resolution-tool and source-profile are between last 'leader' (document-id) and 'everything else' (party)">
                 <metadata>
-                    <title>Pathological Profile</title>
+                    <title>...</title>
+                    <published>2019-11-13T12:41:07.061-05:00</published>
                     <last-modified>...</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
-                    <link href="urn:UNKNOWN"
-                        rel="resolution-source"/>
-                </metadata>
-                <selection uuid="abc-full_catalog"/>
-            </catalog>
-        </x:expect>
-    </x:scenario>
-    <x:scenario label="place link correctly">
-        <x:context>
-            <profile uuid="pathological-profile">
-                <metadata>
-                    <title>Pathological Profile</title>
-                    <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
+                    <version>...</version>
+                    <oscal-version>...</oscal-version>
+                    <document-id scheme="https://www.doi.org/">...doi...</document-id>
+                    <prop name="resolution-tool" value="..."/>
+                    <link href="urn:UNKNOWN" rel="source-profile"/>
                     <party>
                         <org>
                             <org-name>Standing Committee</org-name>
                         </org>
                     </party>
                 </metadata>
-                <selection uuid="abc-full_catalog">
+            </x:expect>
+        </x:scenario>
+        <x:scenario label="profile/metadata has prop child">
+            <x:context select="/o:profile/o:metadata">
+                <profile uuid="pathological-profile">
                     <metadata>
-                        <title>ABC Catalog</title>
-                        <last-modified>2019-11-01T10:16:22.939-04:00</last-modified>
+                        <title>Pathological Profile</title>
+                        <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
                         <version>1.0</version>
                         <oscal-version>1.0-rc2</oscal-version>
+                        <prop name="required" value="some value"/>
+                        <prop name="optional" value="some other value"/>
                     </metadata>
-                </selection>
-            </profile>
-        </x:context>
-
-        <x:expect label="title amended, link added before party">
-            <catalog uuid="...">
+                </profile>
+            </x:context>            
+            <x:expect label="resolution-tool prop is after last prop from input">
                 <metadata>
-                    <title>Pathological Profile</title>
+                    <title>...</title>
                     <last-modified>...</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
-                    <link href="urn:UNKNOWN" rel="resolution-source"/>
-                    <party>
-                        <org>
-                            <org-name>Standing Committee</org-name>
-                        </org>
-                    </party>
-                </metadata>
-                <selection uuid="abc-full_catalog"/>
-            </catalog>
-        </x:expect>
-    </x:scenario>
-    <x:scenario label="place link correctly with another link">
-        <x:context>
-            <profile uuid="pathological-profile">
-                <metadata>
-                    <title>Pathological Profile</title>
-                    <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
-                    <link href="#internal"><text>Internal link</text></link>
-                    <party>
-                        <org>
-                            <org-name>Standing Committee</org-name>
-                        </org>
-                    </party>
+                    <version>...</version>
+                    <oscal-version>...</oscal-version>
+                    <prop name="required" value="some value"/>
+                    <prop name="optional" value="some other value"/>
+                    <prop name="resolution-tool" value="..."/>
+                    <link href="..." rel="source-profile"/>
                 </metadata>
-                <selection uuid="abc-full_catalog">
+            </x:expect>
+        </x:scenario>
+        <x:scenario label="profile/metadata has link">
+            <x:context select="/o:profile/o:metadata">
+                <profile uuid="pathological-profile">
                     <metadata>
-                        <title>ABC Catalog</title>
-                        <last-modified>2019-11-01T10:16:22.939-04:00</last-modified>
+                        <title>Pathological Profile</title>
+                        <last-modified>2019-11-13T12:41:07.061-05:00</last-modified>
                         <version>1.0</version>
                         <oscal-version>1.0-rc2</oscal-version>
+                        <link href="#internal"><text>Internal link</text></link>
                     </metadata>
-                </selection>
-            </profile>
-        </x:context>
-
-        <x:expect label="title amended, link added before old link">
-            <catalog uuid="...">
+                </profile>
+            </x:context>
+            <x:expect label="source-profile link is inserted before copied link">
                 <metadata>
-                    <title>Pathological Profile</title>
+                    <title>...</title>
                     <last-modified>...</last-modified>
-                    <version>1.0</version>
-                    <oscal-version>1.0-rc2</oscal-version>
-                    <link href="urn:UNKNOWN" rel="resolution-source"/>
+                    <version>...</version>
+                    <oscal-version>...</oscal-version>
+                    <prop name="resolution-tool" value="..."/>
+                    <link href="..." rel="source-profile"/>
                     <link href="#internal"><text>Internal link</text></link>
-                    <party>
-                        <org>
-                            <org-name>Standing Committee</org-name>
-                        </org>
-                    </party>
                 </metadata>
-                <selection uuid="abc-full_catalog"/>
-            </catalog>
-        </x:expect>
+            </x:expect>
+        </x:scenario>
+        <x:scenario label="Option to hide source profile URI">
+            <x:param name="hide-source-profile-uri" select="true()"/>
+            <x:context select="$ov:sample-output-from-pipeline-step-1/o:metadata"/>
+            <x:expect label="link rel=source-profile has generic href value"
+                test="//o:link[@rel='source-profile']">
+                <link href="profile" rel="source-profile"/>
+            </x:expect>
+        </x:scenario>
+    </x:scenario>
+
+    <x:scenario label="Tests for match=last-modified template">
+        <x:scenario label="Typical case">
+            <x:context select="$ov:sample-output-from-pipeline-step-1/o:metadata/o:last-modified"/>
+            <x:expect label="last-modified element without attributes">
+                <last-modified>...</last-modified>
+            </x:expect>
+            <x:expect label="Element content is a time stamp"
+                test="$x:result/node() castable as xs:dateTime"/>
+            <!-- last-modified content must represent the time the profile resolution
+                completed. Sanity-check that last-modified is not a copy of the
+                last-modified timestamps from the input document. -->
+            <x:variable name="ov:inputs-last-modified" as="xs:string+"
+                select="$ov:sample-output-from-pipeline-step-1//o:last-modified/string()"/>
+            <x:expect label="last-modified content is not from input document"
+                test="not(o:metadata/o:last-modified/string() = $ov:inputs-last-modified)"/>
+        </x:scenario>
+        <x:scenario label="Empty last-modified in source document">
+            <x:context>
+                <last-modified/>
+            </x:context>
+            <x:expect label="Output still has a time stamp"
+                test="$x:result/self::o:last-modified/node() castable as xs:dateTime"/>
+        </x:scenario>
+    </x:scenario>
+
+    <x:scenario label="Tests for match=profile/metadata/oscal-version template">
+        <x:scenario label="Simple case">
+            <x:context select="/o:profile/o:metadata/o:oscal-version">
+                <profile>
+                    <metadata>
+                        <oscal-version>1.3</oscal-version>
+                    </metadata>
+                </profile>
+            </x:context>
+            <x:expect label="oscal-version">
+                <oscal-version>...</oscal-version>
+            </x:expect>
+        </x:scenario>
+        <x:scenario label="Sanity checks for calling opr:oscal-version with correct inputs: " pending="opr:oscal-version not implemented yet">
+            <x:scenario label="Most recent version is in selection metadata">
+                <x:context select="/o:profile/o:metadata/o:oscal-version">
+                    <profile>
+                        <metadata>
+                            <oscal-version>1.0.3</oscal-version>
+                        </metadata>
+                        <!-- All selections from pipeline's step 1 output
+                            are under consideration, not just first or last. -->
+                        <selection>
+                            <metadata>
+                                <oscal-version>1.0.1</oscal-version>
+                            </metadata>
+                        </selection>
+                        <selection>
+                            <metadata>
+                                <oscal-version>1.0.4</oscal-version>
+                            </metadata>
+                        </selection>
+                        <selection>
+                            <metadata>
+                                <oscal-version>1.0.2</oscal-version>
+                            </metadata>
+                        </selection>
+                    </profile>
+                </x:context>
+                <x:expect label="Most recent minor version mentioned in document">
+                    <oscal-version>1.0.4</oscal-version>
+                </x:expect>
+            </x:scenario>
+            <x:scenario label="Most recent version is in profile metadata">
+                <x:context select="/o:profile/o:metadata/o:oscal-version">
+                    <profile>
+                        <metadata>
+                            <oscal-version>1.0.4</oscal-version>
+                        </metadata>
+                        <selection>
+                            <metadata>
+                                <oscal-version>1.0.1</oscal-version>
+                            </metadata>
+                        </selection>
+                    </profile>
+                </x:context>
+                <x:expect label="Most recent minor version mentioned in document">
+                    <oscal-version>1.0.4</oscal-version>
+                </x:expect>
+            </x:scenario>
+            <x:scenario label="Tool version is older than document versions">
+                <x:context select="/o:profile/o:metadata/o:oscal-version">
+                    <profile>
+                        <metadata>
+                            <oscal-version>1.4.0</oscal-version>
+                        </metadata>
+                        <selection>
+                            <metadata>
+                                <oscal-version>1.2.0</oscal-version>
+                            </metadata>
+                        </selection>
+                    </profile>
+                </x:context>
+                <x:expect label="Tool version">
+                    <oscal-version>1.1.0</oscal-version>
+                </x:expect>
+            </x:scenario>
+        </x:scenario>
+    </x:scenario>
+
+    <x:scenario label="Tests for opr:oscal-version function" pending="opr:oscal-version not implemented yet">
+        <x:scenario label="Same major version">
+            <x:scenario label="Source profile version newer than imported document">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'1.0.1'"/>
+                    <x:param name="imported" select="('1.0.0','1.0.0')"/>
+                    <x:param name="tool" select="'1.0.1'"/>
+                </x:call>
+                <x:expect label="Newest minor version" select="'1.0.1'"/>
+            </x:scenario>
+            <x:scenario label="Source profile version older than imported document">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'1.0.0'"/>
+                    <x:param name="imported" select="('1.0.1','1.0.1')"/>
+                    <x:param name="tool" select="'1.0.1'"/>
+                </x:call>
+                <x:expect label="Newest minor version" select="'1.0.1'"/>
+            </x:scenario>
+            <x:scenario label="Tool version is older">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'1.0.1'"/>
+                    <x:param name="imported" select="('1.0.1','1.0.1')"/>
+                    <x:param name="tool" select="'1.0.0'"/>
+                </x:call>
+                <x:expect label="Tool version" select="'1.0.0'"/>
+            </x:scenario>
+        </x:scenario>
+        <x:scenario label="Different major version">
+            <x:scenario label="Source profile version newer than imported document">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'2.0.1'"/>
+                    <x:param name="imported" select="('1.0.0','1.0.0')"/>
+                    <x:param name="tool" select="'2.0.1'"/>
+                </x:call>
+                <x:expect label="Error"
+                    test="$x:result instance of map(*) and $x:result('err') instance of map(*)"/>
+            </x:scenario>
+            <x:scenario label="Source profile version older than imported document">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'1.0.0'"/>
+                    <x:param name="imported" select="('2.0.1','2.0.1')"/>
+                    <x:param name="tool" select="'2.0.1'"/>
+                </x:call>
+                <x:expect label="Error"
+                    test="$x:result instance of map(*) and $x:result('err') instance of map(*)"/>
+            </x:scenario>
+            <x:scenario label="Tool version is older">
+                <x:call function="opr:oscal-version">
+                    <x:param name="source" select="'2.0.1'"/>
+                    <x:param name="imported" select="('2.0.1','2.0.1')"/>
+                    <x:param name="tool" select="'1.0.0'"/>
+                </x:call>
+                <x:expect label="Error"
+                    test="$x:result instance of map(*) and $x:result('err') instance of map(*)"/>
+            </x:scenario>
+        </x:scenario>
+    </x:scenario>
+    
+    <x:scenario label="Tests for match=selection/metadata template">
+        <x:context select="$ov:sample-output-from-pipeline-step-1//o:selection/o:metadata"/>
+        <x:expect label="Nothing" select="()"/>
     </x:scenario>
 
 </x:description>
diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec
new file mode 100644
index 0000000000..f1a5f6b8e3
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-method-choice.xspec
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<x:description xmlns:x="http://www.jenitennison.com/xslt/xspec"
+    xmlns:ov="http://csrc.nist.gov/ns/oscal/xspec/variable"
+    xmlns:u="http://csrc.nist.gov/ns/uuid"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    stylesheet="../../uuid-method-choice.xsl">
+    
+    <x:scenario label="Tests for u:determine-uuid template">
+        <x:variable name="ov:fixed" as="xs:string" select="'00000000-0000-4000-B000-000000000000'"/>
+        <x:variable name="ov:specified" as="xs:string" select="'f0ad1e6c-5de5-44cd-b92e-a4c507805f0f'"/>
+        <x:variable name="ov:service" as="xs:string" select="resolve-uri('../uuid-value.txt')"/>
+        <x:scenario label="Valid user-provided UUID">
+            <x:call template="u:determine-uuid">
+                <x:param name="top-uuid" select="$ov:specified"/>
+                <x:param name="uuid-method" select="'user-provided'"/>
+            </x:call>
+            <x:expect label="Specified UUID" select="$ov:specified"/>
+        </x:scenario>
+        <x:scenario label="Invalid user-provided UUID">
+            <x:call template="u:determine-uuid">
+                <x:param name="top-uuid" select="'123'"/>
+                <x:param name="uuid-method" select="'user-provided'"/>
+            </x:call>
+            <x:expect label="Fixed UUID" select="$ov:fixed"/>
+        </x:scenario>
+        <x:scenario label="Random UUID using XSLT">
+            <!-- Random XSLT method requires a global context item.
+                For this test's purpose, the context item does not
+                matter, so just use this file itself. -->
+            <x:context href="uuid-method-choice.xspec"/>
+            <x:call template="u:determine-uuid">
+                <x:param name="top-uuid" select="$ov:specified"/>
+                <x:param name="uuid-method" select="'random-xslt'"/>
+            </x:call>
+            <x:expect label="Nonempty string"
+                test="$x:result instance of xs:string and $x:result != ''"/>
+            <x:expect label="UUID is neither fixed one nor specified one"
+                test="$x:result ne $ov:specified and $x:result ne $ov:fixed"/>
+        </x:scenario>
+        <x:scenario label="Random UUID using Java">
+            <x:call template="u:determine-uuid">
+                <x:param name="top-uuid" select="$ov:specified"/>
+                <x:param name="uuid-method" select="'random-java'"/>
+            </x:call>
+            <x:expect label="Nonempty string"
+                test="$x:result instance of xs:string and $x:result != ''"/>
+            <x:expect label="UUID is neither fixed one nor specified one"
+                test="$x:result ne $ov:specified and $x:result ne $ov:fixed"/>
+        </x:scenario>
+        <!-- FYI: Because the transform relies on use-when, which is evaluated at
+            compile time, the same test invocation cannot check both
+            when the XSLT and Java random number generators are available
+            and when they are unavailable. This XSpec test does not cover
+            the fallback behavior that produces the fixed UUID value. -->
+        <x:scenario label="web-service method, available">
+            <!-- To avoid having the test require access to the Internet,
+                mock the web service as a text file that XSLT reads using
+                unparsed-text(). -->
+            <x:call template="u:determine-uuid">
+                <x:param name="uuid-service" select="$ov:service"/>
+                <x:param name="uuid-method" select="'web-service'"/>
+            </x:call>
+            <x:expect label="Value from the 'web service' (in this case, a text file)"
+                select="'309deb03-491b-4677-9148-bc1b79a21c9c'"/>
+        </x:scenario>
+        <x:scenario label="web-service method, unavailable">
+            <x:call template="u:determine-uuid">
+                <x:param name="uuid-service" select="'nonexistent.txt'"/>
+                <x:param name="uuid-method" select="'web-service'"/>
+            </x:call>
+            <x:expect label="Fixed UUID" select="$ov:fixed"/>
+        </x:scenario>
+        <x:scenario label="Fixed UUID">
+            <x:call template="u:determine-uuid">
+                <x:param name="uuid-method" select="'fixed'"/>
+            </x:call>
+            <x:expect label="Fixed UUID" select="$ov:fixed"/>
+        </x:scenario>
+        <x:scenario label="Unrecognized method">
+            <x:call template="u:determine-uuid">
+                <x:param name="uuid-method" select="'junk'"/>
+            </x:call>
+            <x:expect label="Fixed UUID" select="$ov:fixed"/>
+        </x:scenario>
+    </x:scenario>
+</x:description>
diff --git a/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt
new file mode 100644
index 0000000000..a8e02be099
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/testing/2_metadata/uuid-value.txt
@@ -0,0 +1 @@
+309deb03-491b-4677-9148-bc1b79a21c9c
\ No newline at end of file
diff --git a/src/utils/util/resolver-pipeline/uuid-method-choice.xsl b/src/utils/util/resolver-pipeline/uuid-method-choice.xsl
new file mode 100644
index 0000000000..97c028fb55
--- /dev/null
+++ b/src/utils/util/resolver-pipeline/uuid-method-choice.xsl
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet
+    xmlns:javaUUID="java.util.UUID"
+    xmlns:mh="http://csrc.nist.gov/ns/message"
+    xmlns:r="http://csrc.nist.gov/ns/random"
+    xmlns:u="http://csrc.nist.gov/ns/uuid"
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    exclude-result-prefixes="#all"
+    version="3.0">
+
+    <xsl:import href="random-util.xsl"/>
+    <xsl:import href="message-handler.xsl"/>
+
+    <!-- Select an approach for assigning the top-level UUID for the 
+        result catalog. Supported values:
+        - 'random-xslt'    No parameters.
+        - 'random-java'    No parameters.
+        - 'user-provided'  Parameter $top-uuid is required in this case.
+        - 'web-service'    Parameter $uuid-service is optional.
+        - 'fixed'          No parameters.
+        -->
+    <xsl:param name="uuid-method" as="xs:string" select="'fixed'"/>
+    
+    <!-- Explicit top-level UUID for the result catalog. -->
+    <xsl:param name="top-uuid" as="xs:string?"/>
+    
+    <!-- Alternatively, call a web service if the processor supports it -->
+    <xsl:param name="uuid-service" select="'https://www.uuidgenerator.net/api/version4'"/>
+
+    <xsl:template name="u:determine-uuid" as="xs:string">
+        <xsl:param name="uuid-method" select="$uuid-method" as="xs:string"/>
+        <xsl:param name="uuid-service" select="$uuid-service" as="xs:string"/>
+        <xsl:param name="top-uuid" select="$top-uuid" as="xs:string?"/>
+        
+        <xsl:variable name="uuid-v4-regex" as="xs:string">^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$</xsl:variable>
+        <xsl:variable name="fixed-uuid" as="xs:string">00000000-0000-4000-B000-000000000000</xsl:variable>
+        <xsl:choose>
+            <xsl:when test="$uuid-method eq 'user-provided' and
+                matches($top-uuid,$uuid-v4-regex)">
+                <xsl:sequence select="$top-uuid"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'user-provided'">
+                <!-- If we reach this block, the provided value does not match the regex. -->
+                <xsl:call-template name="mh:message-handler">
+                    <xsl:with-param name="message-type">Warning</xsl:with-param>
+                    <xsl:with-param name="text" expand-text="yes">top-uuid value, '{$top-uuid}', does not meet UUID requirements. Using default UUID instead.</xsl:with-param>
+                </xsl:call-template>
+                <xsl:sequence select="$fixed-uuid"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'random-xslt'" use-when="function-available('random-number-generator')">
+                <!-- seed splices a timestamp with a given @uuid -->
+                <xsl:sequence select="r:make-uuid( /*/@uuid || '-' || replace( string(current-dateTime()),'\D','') )"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'random-java'" use-when="function-available('javaUUID:randomUUID')">
+                <xsl:sequence select="javaUUID:randomUUID()"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method = ('random-xslt','random-java')">
+                <!-- If we reach this block, the requested random method is not available. -->
+                <xsl:call-template name="mh:message-handler">
+                    <xsl:with-param name="message-type">Warning</xsl:with-param>
+                    <xsl:with-param name="text" expand-text="yes">uuid-method, '{$uuid-method}', is not available. Using default UUID instead.</xsl:with-param>
+                </xsl:call-template>
+                <xsl:sequence select="$fixed-uuid"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'web-service' and unparsed-text-available($uuid-service)">
+                <xsl:sequence select="unparsed-text($uuid-service)"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'web-service'">
+                <xsl:call-template name="mh:message-handler">
+                    <xsl:with-param name="message-type">Warning</xsl:with-param>
+                    <xsl:with-param name="text" expand-text="yes">uuid-service, '{$uuid-service}', is not available. Using default UUID instead.</xsl:with-param>
+                </xsl:call-template>
+                <xsl:sequence select="$fixed-uuid"/>
+            </xsl:when>
+            <xsl:when test="$uuid-method eq 'fixed'">
+                <xsl:sequence select="$fixed-uuid"/>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:call-template name="mh:message-handler">
+                    <xsl:with-param name="message-type">Warning</xsl:with-param>
+                    <xsl:with-param name="text" expand-text="yes">uuid-method, '{$uuid-method}', is not recognized. Using default UUID instead.</xsl:with-param>
+                </xsl:call-template>
+                <xsl:sequence select="$fixed-uuid"/>
+            </xsl:otherwise>
+        </xsl:choose>
+    </xsl:template>
+
+</xsl:stylesheet>
\ No newline at end of file

From 0d0c508f0b072a8cc2cec02893ad39a2e1322282 Mon Sep 17 00:00:00 2001
From: galtm <40716346+galtm@users.noreply.github.com>
Date: Sun, 3 Apr 2022 17:58:56 -0500
Subject: [PATCH 2/3] Add table of parameters and clarify testing folder
 content

---
 src/utils/util/resolver-pipeline/readme.md | 46 +++++++++++++++-------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/src/utils/util/resolver-pipeline/readme.md b/src/utils/util/resolver-pipeline/readme.md
index aa9cadeb67..0e8913a01b 100644
--- a/src/utils/util/resolver-pipeline/readme.md
+++ b/src/utils/util/resolver-pipeline/readme.md
@@ -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 &#8212; 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.

From e6f284c7fd8989d9fdcc1649f4947a4d8a50aa00 Mon Sep 17 00:00:00 2001
From: galtm <40716346+galtm@users.noreply.github.com>
Date: Tue, 5 Apr 2022 07:58:51 -0500
Subject: [PATCH 3/3] Change "home" from global param to global variable; does
 not need to be set from outside

---
 src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
index 169a7bd841..e4ba2066ba 100644
--- a/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
+++ b/src/utils/util/resolver-pipeline/oscal-profile-RESOLVE.xsl
@@ -44,7 +44,7 @@
 
     <xsl:variable name="louder" select="$trace = 'on'"/>
 
-    <xsl:param name="home" select="/"/>
+    <xsl:variable name="home" select="/"/>
 
     <!-- If true, do not record profile URI in output catalog's source-profile
         metadata, due to privacy or security concerns. -->