Merge pull request #9 from david-waltermire-nist/wendellpiez-rc3-docs…

…-enhancements-3 Compose improvements
usnistgov · Apr 30, 2021 · 40dc810 · 40dc810
2 parents fabe812 + 7e4c8a4
commit 40dc810
Show file tree

Hide file tree

Showing 13 changed files with 371 additions and 111 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,4 @@
 
 # other generated files
 nohup.out
+/toolchains/xslt-M4/validate/xspec/metaschema-composition-schematron-result.html
diff --git a/toolchains/xslt-M4/compose/metaschema-build-refs.xsl b/toolchains/xslt-M4/compose/metaschema-build-refs.xsl
@@ -36,13 +36,25 @@
     <xsl:key name="assembly-by-name" match="METASCHEMA/define-assembly[@scope='global']" use="@name"/>
     <xsl:key name="field-by-name"    match="METASCHEMA/define-field[@scope='global']"    use="@name"/>
     <xsl:key name="flag-by-name"     match="METASCHEMA/define-flag[@scope='global']"     use="@name"/>
+
+    <xsl:template match="METASCHEMA">
+        <xsl:copy>
+            <xsl:copy-of select="@*"/>
+            <xsl:variable name="my-short-name" select="short-name"/>
+            <xsl:variable name="clashing-modules" select="descendant::METASCHEMA[short-name=$my-short-name]"/>
+            <xsl:if test="exists($clashing-modules)" expand-text="true">
+                <EXCEPTION problem-type="metaschema-short-name-clash">The metaschema short-name '{ short-name }' is the same as the short-name of imported { if (count($clashing-modules)=1) then 'module' else 'modules'} '{ ($clashing-modules/@_base-uri => string-join(', ')) }'. Each module's short-name must be unique.</EXCEPTION>
+            </xsl:if>
+            <xsl:apply-templates/>
+        </xsl:copy>
+    </xsl:template>
 
     <xsl:template match="METASCHEMA/define-assembly">
         <xsl:copy>
             <xsl:copy-of select="@*"/>
             <xsl:variable name="shadows" select="key('assembly-by-name', @name, parent::METASCHEMA) except ."/>
             <xsl:if test="exists($shadows)" expand-text="true">
-                <EXCEPTION level="warning">Assembly definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'this definition' else 'these definitions'}: { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }</EXCEPTION>
+                <EXCEPTION problem-type="definition-shadowing">Assembly definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'this definition' else 'these definitions'}: { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }</EXCEPTION>
             </xsl:if>
             <xsl:apply-templates/>
         </xsl:copy>
@@ -53,7 +65,7 @@
             <xsl:copy-of select="@*"/>
             <xsl:variable name="shadows" select="key('field-by-name', @name, parent::METASCHEMA) except ."/>
             <xsl:if test="exists($shadows)" expand-text="true">
-                <EXCEPTION level="warning">Field definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'this definition' else 'these definitions'}: { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }</EXCEPTION>
+                <EXCEPTION problem-type="definition-shadowing">Field definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'this definition' else 'these definitions'}: { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }</EXCEPTION>
             </xsl:if>
             <xsl:apply-templates/>
 
@@ -65,7 +77,7 @@
             <xsl:copy-of select="@*"/>
             <xsl:variable name="shadows" select="key('flag-by-name', @name, parent::METASCHEMA) except ."/>
             <xsl:if test="exists($shadows)" expand-text="true">
-                <EXCEPTION level="warning">Flag definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'the definition' else 'these definitions:'} { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }.</EXCEPTION>
+                <EXCEPTION problem-type="definition-shadowing">Flag definition '{ @name }' in module '{ @module }' shadows { if (count($shadows) eq 1) then 'the definition' else 'these definitions:'} { ($shadows ! ('''' || @name || ''' in module ''' || @module || '''') ) => string-join('; ') }.</EXCEPTION>
             </xsl:if>
             <xsl:apply-templates/>
 
@@ -82,7 +94,7 @@
             <xsl:attribute name="_key-ref" select="@_key-name"/>
         </xsl:for-each>
         <xsl:if test="empty($all-defs)" expand-text="true">
-            <EXCEPTION level="error">Target definition not found for assembly reference '{ $me }'.</EXCEPTION>
+            <EXCEPTION problem-type="instance-invalid-reference">Target definition not found for assembly reference '{ $me }'.</EXCEPTION>
         </xsl:if>
     </xsl:template>
 
@@ -96,7 +108,7 @@
           <xsl:attribute name="_key-ref" select="@_key-name"/>
         </xsl:for-each>
         <xsl:if test="empty($all-defs)" expand-text="true">
-            <EXCEPTION level="error">Target definition not found for field reference '{ $me }'.</EXCEPTION>
+            <EXCEPTION problem-type="instance-invalid-reference">Target definition not found for field reference '{ $me }'.</EXCEPTION>
         </xsl:if>
     </xsl:template>
 
@@ -110,7 +122,7 @@
             <xsl:attribute name="_key-ref" select="@_key-name"/>
         </xsl:for-each>
         <xsl:if test="empty($all-defs)" expand-text="true">
-            <EXCEPTION level="error">Target definition not found for flag reference '{ $me }'.</EXCEPTION>
+            <EXCEPTION problem-type="instance-invalid-reference">Target definition not found for flag reference '{ $me }'.</EXCEPTION>
         </xsl:if>
     </xsl:template>
 

diff --git a/toolchains/xslt-M4/compose/metaschema-collect.xsl b/toolchains/xslt-M4/compose/metaschema-collect.xsl
@@ -30,7 +30,7 @@
     <xsl:template match="/">
         <xsl:comment expand-text="true">{ name(/*) }</xsl:comment>
         <xsl:if test="empty(/METASCHEMA)" expand-text="true">
-            <EXCEPTION level="error">No Metaschema found in namespace 'http://csrc.nist.gov/ns/oscal/metaschema/1.0' : instead we have a document '{ */name() }' in namespace '{ /*/namespace-uri(.) }'</EXCEPTION>
+            <EXCEPTION problem-type="not-a-metaschema">No Metaschema found in namespace 'http://csrc.nist.gov/ns/oscal/metaschema/1.0' : instead we have a document '{ */name() }' in namespace '{ /*/namespace-uri(.) }'</EXCEPTION>
         </xsl:if>
         <xsl:apply-templates mode="acquire" select="/METASCHEMA">
             <xsl:with-param name="so-far" tunnel="true" select="document-uri(/)"/>
@@ -76,22 +76,31 @@
     <xsl:template match="import" mode="acquire">
         <xsl:param name="so-far" tunnel="yes" required="yes"/>
         <xsl:variable name="uri" select="resolve-uri(@href,base-uri(parent::METASCHEMA))"/>
-        <xsl:choose expand-text="true">
-            <xsl:when test="$uri = $so-far">
-                <EXCEPTION level="error">Circular import of { $uri } skipped.</EXCEPTION>
-            </xsl:when>
-            <xsl:when test="not(doc-available($uri))">
-                <EXCEPTION level="error">Error: No metaschema module is found at { $uri }.</EXCEPTION>
-            </xsl:when>
-            <xsl:when test="empty(document($uri)/METASCHEMA)">
-                <EXCEPTION level="error">Error: No metaschema module is found at { $uri } (it is not named METASCHEMA in namespace 'http://csrc.nist.gov/ns/oscal/metaschema/1.0').</EXCEPTION>
-            </xsl:when>
-            <xsl:otherwise>
-                <xsl:apply-templates select="document($uri)/METASCHEMA" mode="acquire">
-                    <xsl:with-param name="so-far" select="$so-far,$uri"/>
-                </xsl:apply-templates>
-            </xsl:otherwise>
-        </xsl:choose>
+            <xsl:choose expand-text="true">
+                <xsl:when test="$uri = $so-far">
+                    <xsl:copy>
+                        <xsl:copy-of select="@* except @xsi:*"/>
+                        <EXCEPTION problem-type="circular-import">Circular import of { $uri } in this file (or one of its children) skipped.</EXCEPTION>
+                    </xsl:copy>
+                </xsl:when>
+                <xsl:when test="not(doc-available($uri))">
+                    <xsl:copy>
+                        <xsl:copy-of select="@* except @xsi:*"/>
+                        <EXCEPTION problem-type="broken-import">Error: No metaschema module is found at { $uri }.</EXCEPTION>
+                    </xsl:copy>
+                </xsl:when>
+                <xsl:when test="empty(document($uri)/METASCHEMA)">
+                    <xsl:copy>
+                        <xsl:copy-of select="@* except @xsi:*"/>
+                        <EXCEPTION problem-type="import-not-a-metaschema">Error: No metaschema module is found at { $uri } (it is not named METASCHEMA in namespace 'http://csrc.nist.gov/ns/oscal/metaschema/1.0').</EXCEPTION>
+                    </xsl:copy>
+                </xsl:when>
+                <xsl:otherwise>
+                    <xsl:apply-templates select="document($uri)/METASCHEMA" mode="acquire">
+                        <xsl:with-param name="so-far" select="$so-far,$uri"/>
+                    </xsl:apply-templates>
+                </xsl:otherwise>
+            </xsl:choose>
     </xsl:template>
 
     <xsl:template priority="60" mode="assign-defaults" match="field | assembly | model//define-field | model//define-assembly">

diff --git a/toolchains/xslt-M4/compose/metaschema-compose.xpl b/toolchains/xslt-M4/compose/metaschema-compose.xpl
@@ -100,23 +100,31 @@
 
   <p:identity name="input"/>
 
-  <!-- pull modules together
-       and mark all top-level definitions with key-names
-       add scope='global' unless it is given -->
-
   <p:xslt name="collect">
+    <!-- - Inlines each imported metaschema, checking for circular references.
+         - Adds default values for metaschema attributes and elements.
+         - Tracks source metaschema using @_base-uri.
+         - Adds @_key-name for all top-level definitions, which provides a key lookup in future transforms.
+    -->
     <p:input port="stylesheet">
       <p:document href="metaschema-collect.xsl"/>
     </p:input>
+    <!-- With EXCEPTION problem-type="not-a-metaschema" if the processed document is not a metaschema -->
+    <!-- With EXCEPTION problem-type="broken-import" for broken imports -->
+    <!-- With EXCEPTION problem-type="import-not-a-metaschema" for imports that are not a metaschema -->
+    <!-- With EXCEPTION problem-type="circular-import" for circular imports -->
   </p:xslt>
-  <!--  With EXCEPTION for broken or circular imports -->
 
   <p:xslt name="build-refs">
+    <!-- Generates @_key-ref entries for all assembly, field, and flag instances. -->
     <p:input port="stylesheet">
       <p:document href="metaschema-build-refs.xsl"/>
     </p:input>
+    <!-- With EXCEPTION for broken references (error) or shadowing definitions (warning) -->
+    <!-- With EXCEPTION problem-type="definition-shadowing" when a definition in an importing module clashes with an definition of the same type (i.e., flag, field, assembly) in an imported module or another downstream import -->
+    <!-- With EXCEPTION problem-type="instance-invalid-reference" when an instance references a non-existant or out-of-scope definition -->
   </p:xslt>
-  <!--  With EXCEPTION for broken references (error) or shadowing definitions (warning) -->
+  <!-- WITH EXCEPTION problem-type="metaschema-short-name-clash" when an imported modules short-name clashes with the importing module -->
 
   <p:xslt name="trim-extra-modules">
     <p:input port="stylesheet">
@@ -130,25 +138,20 @@
       <p:document href="metaschema-prune-unused-definitions.xsl"/>
     </p:input>
     <p:with-param name="show-warnings" select="'yes'"/>
+    <!-- With EXCEPTION problem-type="missing-root" for no roots found when the metaschema is not abstract -->
+    <!-- With EXCEPTION problem-type="unused-definition" for definitions removed as unused -->
   </p:xslt>
-<!-- With EXCEPTION for no roots found, also
-     when @show-warnings='yes'
-       EXCEPTION level='warning' for definitions removed as unused
-       TRACE listing all references found -->
-
-  <!-- New @sibling-name will show names to check among siblings within models -->
 
-  <!-- New @using-name exposes the name-in-use, whether given or derived -->
   <p:xslt name="add-use-names">
+    <!-- - @using-name exposes the name-in-use, whether given or derived -->
     <p:input port="stylesheet">
       <p:document href="metaschema-resolve-use-names.xsl"/>
     </p:input>
+    <!-- No exceptions produced (everything gets a @using-name) -->
   </p:xslt>
-  <!-- No exceptions produced (everything gets a @using-name) -->
 
-  <!-- New @in-xml-name and @in-json-name will show exposed names
-       for checking among siblings within models -->
   <p:xslt name="add-sibling-names">
+    <!-- New @in-xml-name and @in-json-name will show exposed names for checking among siblings within models -->
     <p:input port="stylesheet">
       <p:document href="metaschema-resolve-sibling-names.xsl"/>
     </p:input>