From 6da87a9c41b743721784faf9ac455da7eb92803d Mon Sep 17 00:00:00 2001
From: Alexander Stein <alexander.stein@nist.gov>
Date: Fri, 12 Aug 2022 09:43:52 -0400
Subject: [PATCH] AJ Stein's week 32 feedback for usnistgov/OSCAL#1331.

---
 .../oscal_control-common_metaschema.xml          | 16 ++++++++++++++++
 src/metaschema/oscal_metadata_metaschema.xml     |  7 ++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/src/metaschema/oscal_control-common_metaschema.xml b/src/metaschema/oscal_control-common_metaschema.xml
index af7afa4739..ed8f6c0b49 100644
--- a/src/metaschema/oscal_control-common_metaschema.xml
+++ b/src/metaschema/oscal_control-common_metaschema.xml
@@ -184,6 +184,14 @@
         <define-assembly name="parameter-constraint">
                 <formal-name>Constraint</formal-name>
                 <description>A formal or informal expression of a constraint or test</description>
+                <!-- 
+                        TODO: Is `@ns` flag enough or should we add system for
+                        dictating constraints?
+
+                        Use cases: RMF recommends one thing, maybe different with
+                        FedRAMP, then a contradiction or subset of constraints is
+                        required, not recommended for example FCEB agency (Important Federal Agency).
+                -->
                 <model>
                         <define-field name="description" as-type="markup-multiline" in-xml="WITH_WRAPPER">
                                 <formal-name>Constraint Description</formal-name>
@@ -205,6 +213,14 @@
         </define-assembly>
         <define-assembly name="parameter-guideline">
                 <formal-name>Guideline</formal-name>
+                <!-- 
+                        TODO: Is `@ns` flag enough or should we add system for
+                        dictating guidelines?
+
+                        Use cases: RMF recommends one thing, maybe different with
+                        FedRAMP, then a contradiction or subset of constraints is
+                        required, not recommended for example FCEB agency (Important Federal Agency).
+                -->
                 <description>A prose statement that provides a recommendation for the use of a parameter.</description>
                 <model>
                         <define-field name="prose" as-type="markup-multiline" in-xml="UNWRAPPED" min-occurs="1">
diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml
index 16c98056a7..da3cb0baa3 100644
--- a/src/metaschema/oscal_metadata_metaschema.xml
+++ b/src/metaschema/oscal_metadata_metaschema.xml
@@ -54,7 +54,12 @@
                         <enum value="alternate">The link identifies an alternative location or format for this resource. Defined by <a href="https://html.spec.whatwg.org/multipage/links.html#linkTypes">the HTML Living Standard</a></enum>
                         <enum value="predecessor-version">This link identifies a resource containing the predecessor version in the version history. Defined by  <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
                         <enum value="successor-version">This link identifies a resource containing the predecessor version in the version history. Defined by <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
+                        <enum value="version-history">This link identifies a resource containing the version history of this document. Defined by <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
                     </allowed-values>
+                    <!-- 
+                        TODO: Can we and should we add a constraint to say, if one revision exists or at least one revision of n>1 exist,
+                        the metadata/published and metadata/last-modified should match?
+                    -->
                 </constraint>
                 <remarks>
                     <p>While <code>published</code>, <code>last-modified</code>, and <code>oscal-version</code> are not required, values for these entries should be provided if the information is known. A <code>link</code> with a <code>rel</code> of <q>source</q> should be provided if the information is known.</p>
@@ -924,7 +929,7 @@
         <formal-name>OSCAL Version</formal-name>
         <description>The OSCAL model version the document was authored against and will conform to as valid.</description>
         <remarks>
-            <p>Indicates the version of the OSCAL model to which the document conforms, for example <q>1.1.0</q> or <q>1.0.0-M1</q>. That can be used as a hint for a tool indicating which version of the OSCAL XML or JSON schema to use for validation.</p>
+            <p>Indicates the version of the OSCAL model to which the document conforms, for example <q>1.1.0</q> or <q>1.0.0-milestone1</q>. That can be used as a hint for a tool indicating which version of the OSCAL XML or JSON schema to use for validation.</p>
             <p>The OSCAL version serves a different purpose from the document version and is used to represent a different concept. If both have the same value, this is coincidental.</p>
         </remarks>
     </define-field>