From 8739b60e3d591b1a45f836c70c007aaae23a72e3 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 16:04:12 -0400 Subject: [PATCH 01/16] [skip ci] Start up ADR 9 from template for #720 --- .../adr/0009-constraint-based-help-docs.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 documents/adr/0009-constraint-based-help-docs.md diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md new file mode 100644 index 000000000..ecc6e1ab7 --- /dev/null +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -0,0 +1,20 @@ +_This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). In each ADR file, write these sections_: + +# Title +Provide a title following this format - {ADR Number} {Brief ADR Title} + +## Status + +What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Decision + +What is the change that we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? From c51c98b89e1c84908d277fe730b02df5085e7e31 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 17:33:20 -0400 Subject: [PATCH 02/16] [skip ci] Add context for decision in #720 --- documents/adr/0009-constraint-based-help-docs.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index ecc6e1ab7..ca8887af6 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -1,15 +1,18 @@ -_This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). In each ADR file, write these sections_: +# 9. Add URL Hints to Metaschema Constraints for SARIF-Based Constraint Results Output -# Title -Provide a title following this format - {ADR Number} {Brief ADR Title} +Date: 2024-09-26 ## Status -What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? +Proposed ## Context -What is the issue that we're seeing that is motivating this decision or change? +Currently, the FedRAMP Automation Team provides [the machine-readable rules for OSCAL-based FedRAMP digital authorization packages](https://github.com/GSA/fedramp-automation/blob/2974ae32195263b5a33d641e35854b58f675e18d/src/validations/constraints/fedramp-external-constraints.xml) in [the Metaschema constraint format](https://pages.nist.gov/metaschema/specification/syntax/constraints/). They also maintain supporting documentation at [automate.fedramp.gov](https://automate.fedramp.gov) separately. + +The team's developers, and the community of downstream developer and engineers building software for stakeholders in the FedRAMP ecosystem, must manually cross-reference that documentation if they wish to use the `oscal-cli` and constraints' result output to inform changes to target content. This tool, using the constraints, will emit the information in [the SARIF format](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) and emit a constraint's `message` element, but not additional metadata. + +This decision record proposes a solution to add machine-readable metadata to FedRAMP's constraints to always complement a failing constraint's `message` field with a URL to the official documentation. ## Decision From 68d958a90390e90b6ac8b059c7910e50c7505fe5 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 17:41:52 -0400 Subject: [PATCH 03/16] [skip ci] Add possible solutions for #720 --- documents/adr/0009-constraint-based-help-docs.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index ca8887af6..4f6bddced 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -14,6 +14,16 @@ The team's developers, and the community of downstream developer and engineers b This decision record proposes a solution to add machine-readable metadata to FedRAMP's constraints to always complement a failing constraint's `message` field with a URL to the official documentation. +## Possible Solutions + +There are multiple approaches for the team and larger community to consider. + +1. Do nothing, keep the development and use of constraints as-is, encourage users to manually reference documentation to help correct or improve OSCAL-based content for FedRAMP packages. +1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of the existing Metachema `message` element in each constraint. +1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of a mandatory Metachema property in each constraint. +1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text for help information to interpolate into SARIF results. +1. Always embed a new custom Metaschema assembly, `help`, with its own custom nested fields and flags, and enhance Metaschema specification and tools to interpolate that data into SARIF results. + ## Decision What is the change that we're proposing and/or doing? From 440f624a6ec8f020b69cbc664081c8f62b1af30f Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 22:55:20 -0400 Subject: [PATCH 04/16] [skip ci] Hyperlink oscal-cli for bg in #720 PR --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 4f6bddced..170f3a9a6 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -10,7 +10,7 @@ Proposed Currently, the FedRAMP Automation Team provides [the machine-readable rules for OSCAL-based FedRAMP digital authorization packages](https://github.com/GSA/fedramp-automation/blob/2974ae32195263b5a33d641e35854b58f675e18d/src/validations/constraints/fedramp-external-constraints.xml) in [the Metaschema constraint format](https://pages.nist.gov/metaschema/specification/syntax/constraints/). They also maintain supporting documentation at [automate.fedramp.gov](https://automate.fedramp.gov) separately. -The team's developers, and the community of downstream developer and engineers building software for stakeholders in the FedRAMP ecosystem, must manually cross-reference that documentation if they wish to use the `oscal-cli` and constraints' result output to inform changes to target content. This tool, using the constraints, will emit the information in [the SARIF format](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) and emit a constraint's `message` element, but not additional metadata. +The team's developers, and the community of downstream developer and engineers building software for stakeholders in the FedRAMP ecosystem, must manually cross-reference that documentation if they wish to use the [`oscal-cli`](https://github.com/metaschema-framework/oscal-cli) and constraints' result output to inform changes to target content. This tool, using the constraints, will emit the information in [the SARIF format](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) and emit a constraint's `message` element, but not additional metadata. This decision record proposes a solution to add machine-readable metadata to FedRAMP's constraints to always complement a failing constraint's `message` field with a URL to the official documentation. From 42572682f096f66809a68352323fcc60d9cf07ca Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 23:29:54 -0400 Subject: [PATCH 05/16] [skip ci] Fix Metachema->Metaschema typos for #720 --- documents/adr/0009-constraint-based-help-docs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 170f3a9a6..d03c5a124 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -19,8 +19,8 @@ This decision record proposes a solution to add machine-readable metadata to Fed There are multiple approaches for the team and larger community to consider. 1. Do nothing, keep the development and use of constraints as-is, encourage users to manually reference documentation to help correct or improve OSCAL-based content for FedRAMP packages. -1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of the existing Metachema `message` element in each constraint. -1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of a mandatory Metachema property in each constraint. +1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of the existing Metaschema `message` element in each constraint. +1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of a mandatory Metaschema property in each constraint. 1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text for help information to interpolate into SARIF results. 1. Always embed a new custom Metaschema assembly, `help`, with its own custom nested fields and flags, and enhance Metaschema specification and tools to interpolate that data into SARIF results. From a0d3d2faca425aacaebdb573c7a4436fd01f72f8 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 23:52:13 -0400 Subject: [PATCH 06/16] [skip ci] Add consequences of decisions for #720 --- documents/adr/0009-constraint-based-help-docs.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index d03c5a124..f1d693790 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -30,4 +30,14 @@ What is the change that we're proposing and/or doing? ## Consequences -What becomes easier or more difficult to do because of this change? +There are positive and negative impacts to each of the five solutions above. Below is a summary analysis for each solution, weighing the pros and cons of each approach. + +1. This approach has the lowest risk and effort for the FedRAMP Automation Team and maintainers of tool and data dependencies. However, it assures increased effort for developers of FedRAMP software and amplifies that same effort on downstream stakeholders who understand program requirements through those tools. This effort and friction will increase as the number of constraints increases over time. Operationally, tools will operate as they currently do at the time of this writing, so there will be no change in speed or performance characteristics of the tools. + +1. This approach requires moderate effort for FedRAMP Automation Team developers maintaining constraints and developers of software for the FedRAMP ecosystem. The former will have to carefully editing new and existing constraints to track inserting additional information into the `message` field of a constraint. Downstream developers of software for the FedRAMP ecosystem will have to customize their tools to parse each message and extract different kinds of error information from the Metaschema modules or SARIF output without consistency and added complexity. It will, however, require little to no additional effort for maintainers of data and tool dependencies. Operationally, this may increase the size of constraint files and resulting results output in SARIF if guidance requires them to be output in all cases. + +1. This approach requires a nominal increase in effort for FedRAMP Automation Team developers, but for certain edge cases complicates design and implementation as such a property will be required. It will also cause a nominal increase in effort developers of software for the FedRAMP ecosystem, but give them a consistent way to extract necessary help documentation without ad-hoc parsing of the message field. Operationally, this approach will increase the size of constraint files and may increase resulting results output in SARIF if guidance requires them to be output in all cases. + +1. This approach requires a nominal increase in effort for FedRAMP Automation Developers, but unlike the approach in Solution 3, allows flexibility to provide help text by URL address, unformatted text, or more complex help text with Markdown formatting. For developers of software for the FedRAMP ecosystem, it provides full flexibility to consider a progressive downgrade or upgrade path to help text by looking solely at fields in the already standardized SARIF results output. For developers of tool dependencies, and to a lesser extent data, this change will not require changes for processing constraint inputs, but does require adding to likely existing functionality to map constraint inputs to fields in the SARIF standard for result output. Operationally, this approach may have a minor impact on speed and other performance characteristics of tools that process constraints and generate result output. However, this approach provides multiple options can allow for multiple approaches in constraints files to decrease size or increase them accordingly for solutions without access to help text addresses. This flexibility will benefit stakeholders using the software to understand FedRAMP requirements for different use cases. + +1. This approach, although like Solution 4, does benefit FedRAMP Automation Team developers maintaining constraints, developers of software for the FedRAMP ecosystem, and downstream stakeholders using that software in similar ways, it will place more burden on dependency maintainers who make Metaschema-based constraint tooling. The Metaschema specification will also need to be updated, further delaying the delayed for design and implementation. So although it is similar to Solution 4, it will increase delay. From f2ad73d46462aa695e0ef295d08e258fd867e722 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 23:52:46 -0400 Subject: [PATCH 07/16] [skip ci] Spacing and style guide for S4 in #720 --- documents/adr/0009-constraint-based-help-docs.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index f1d693790..ac3b2c7bd 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -19,9 +19,13 @@ This decision record proposes a solution to add machine-readable metadata to Fed There are multiple approaches for the team and larger community to consider. 1. Do nothing, keep the development and use of constraints as-is, encourage users to manually reference documentation to help correct or improve OSCAL-based content for FedRAMP packages. + 1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of the existing Metaschema `message` element in each constraint. + 1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of a mandatory Metaschema property in each constraint. -1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text for help information to interpolate into SARIF results. + +1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text for help information to interpolate into SARIF results. Require one, some, or all of these properties in a constraint style guide per [GSA/fedramp-automation#675](https://github.com/GSA/fedramp-automation/issues/675). + 1. Always embed a new custom Metaschema assembly, `help`, with its own custom nested fields and flags, and enhance Metaschema specification and tools to interpolate that data into SARIF results. ## Decision From 47c468698291a2d2c053971b56c09a8092008d5e Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 26 Sep 2024 23:53:23 -0400 Subject: [PATCH 08/16] [skip ci] Recommend Solution 4 for #720 --- .../adr/0009-constraint-based-help-docs.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index ac3b2c7bd..1bd2ade9c 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -30,7 +30,27 @@ There are multiple approaches for the team and larger community to consider. ## Decision -What is the change that we're proposing and/or doing? +The team proposes Solution 4: using the existing property (`prop`) assembly of Metaschema constraint models: one for a URL address, another for help text, and another for hep text with Markdown formatting. A FedRAMP constraint style guide should recommend or require one, some, or all of them to provide a flexible, yet consistent approach. + +Below is an example of how these properties can look in an example constraints files. + +```xml + + + + + + + + + Each data center address must contain a country code. + + + + +``` + +The FedRAMP Team will request the maintainers of metaschema-java and oscal-cli to implement code to map these props to the SARIF `helpUri` and `help` fields for constraints result outputs. ## Consequences From 486a7586e1995a494ddafe1918401bd142aad5c3 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Fri, 27 Sep 2024 00:00:40 -0400 Subject: [PATCH 09/16] [skip ci] Reorg and improve decision rec for #720 --- documents/adr/0009-constraint-based-help-docs.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 1bd2ade9c..a113a7359 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -30,9 +30,11 @@ There are multiple approaches for the team and larger community to consider. ## Decision -The team proposes Solution 4: using the existing property (`prop`) assembly of Metaschema constraint models: one for a URL address, another for help text, and another for hep text with Markdown formatting. A FedRAMP constraint style guide should recommend or require one, some, or all of them to provide a flexible, yet consistent approach. +The team proposes Solution 4. To implement this solution, we will commit to steps below. -Below is an example of how these properties can look in an example constraints files. +1. The FedRAMP Team will request the maintainers of [metaschema-java](https://github.com/metaschema-framework/metaschema-java) and [oscal-cli](https://github.com/metaschema-framework/oscal-cli) to implement code to map props `help-url`, `help-text`, and `help-text-markdown` to the SARIF `helpUri` and `help` fields for constraints result outputs. + +2. After Step 1 is complete, A FedRAMP constraint style guide should recommend or the use of `help-url`, `help-text`, and `help-text-markdown` props. Below is an example of how these properties can look in an example constraints files. ```xml @@ -41,8 +43,8 @@ Below is an example of how these properties can look in an example constraints f - - + + Each data center address must contain a country code. @@ -50,7 +52,7 @@ Below is an example of how these properties can look in an example constraints f ``` -The FedRAMP Team will request the maintainers of metaschema-java and oscal-cli to implement code to map these props to the SARIF `helpUri` and `help` fields for constraints result outputs. +3. The team will update backport the props, as required by the style guide completed for Step 2, to existing constraints and correct and enhance documentation at [automate.fedramp.gov](https://automate.fedramp.gov) accordingly to deep-link to precise information for each constraint. ## Consequences From c2fea9278f678100730f439ce3f4b27d8a48d0ad Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Fri, 27 Sep 2024 00:10:27 -0400 Subject: [PATCH 10/16] [skip ci] Missed or required for decision in #720 --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index a113a7359..85e9f6dc2 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -34,7 +34,7 @@ The team proposes Solution 4. To implement this solution, we will commit to step 1. The FedRAMP Team will request the maintainers of [metaschema-java](https://github.com/metaschema-framework/metaschema-java) and [oscal-cli](https://github.com/metaschema-framework/oscal-cli) to implement code to map props `help-url`, `help-text`, and `help-text-markdown` to the SARIF `helpUri` and `help` fields for constraints result outputs. -2. After Step 1 is complete, A FedRAMP constraint style guide should recommend or the use of `help-url`, `help-text`, and `help-text-markdown` props. Below is an example of how these properties can look in an example constraints files. +2. After Step 1 is complete, A FedRAMP constraint style guide should recommend or require the use of `help-url`, `help-text`, and `help-text-markdown` props. Below is an example of how these properties can look in an example constraints files. ```xml From b050ce7a0e1e368e59317d93c331097f69371f67 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Fri, 27 Sep 2024 00:12:20 -0400 Subject: [PATCH 11/16] [skip ci] Clarify backporting and new dev for #720 --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 85e9f6dc2..1d4d92486 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -52,7 +52,7 @@ The team proposes Solution 4. To implement this solution, we will commit to step ``` -3. The team will update backport the props, as required by the style guide completed for Step 2, to existing constraints and correct and enhance documentation at [automate.fedramp.gov](https://automate.fedramp.gov) accordingly to deep-link to precise information for each constraint. +3. The team will backport the props, as required by the style guide completed for Step 2, to existing constraints and correct and enhance documentation at [automate.fedramp.gov](https://automate.fedramp.gov) accordingly to deep-link to precise information for each constraint. New constraints will add these props to be successfully reviewed and merged in the team's normal development cycle. ## Consequences From fd6331622e8d69915db758149bccc4e1bec45f64 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Fri, 27 Sep 2024 17:43:17 -0400 Subject: [PATCH 12/16] [skip ci] Clarify Metaschema data-types and structure per out-of-band PR review --- documents/adr/0009-constraint-based-help-docs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 1d4d92486..a8f44d82d 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -24,7 +24,7 @@ There are multiple approaches for the team and larger community to consider. 1. Always embed help text directly into the constraints themselves for interpolation into SARIF results, in the `message` field or some other SARIF element, by use of a mandatory Metaschema property in each constraint. -1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text for help information to interpolate into SARIF results. Require one, some, or all of these properties in a constraint style guide per [GSA/fedramp-automation#675](https://github.com/GSA/fedramp-automation/issues/675). +1. Allow for Metaschema properties to optionally define a URL for help information, text for help information without formatting, and/or formatted Markdown text (conformant with the [CommonMark specification, as required by the Metaschema specification](https://pages.nist.gov/metaschema/specification/datatypes/#markup-data-types)) for help information to interpolate into SARIF results. Require one, some, or all of these properties in a constraint style guide per [GSA/fedramp-automation#675](https://github.com/GSA/fedramp-automation/issues/675). 1. Always embed a new custom Metaschema assembly, `help`, with its own custom nested fields and flags, and enhance Metaschema specification and tools to interpolate that data into SARIF results. @@ -32,9 +32,9 @@ There are multiple approaches for the team and larger community to consider. The team proposes Solution 4. To implement this solution, we will commit to steps below. -1. The FedRAMP Team will request the maintainers of [metaschema-java](https://github.com/metaschema-framework/metaschema-java) and [oscal-cli](https://github.com/metaschema-framework/oscal-cli) to implement code to map props `help-url`, `help-text`, and `help-text-markdown` to the SARIF `helpUri` and `help` fields for constraints result outputs. +1. The FedRAMP Team will request the maintainers of [metaschema-java](https://github.com/metaschema-framework/metaschema-java) and [oscal-cli](https://github.com/metaschema-framework/oscal-cli) to implement code to map props `help-url`, `help-text`, and `help-markdown` to the SARIF `helpUri` and `help` fields for constraints result outputs. The team will tunnel formatted help text data in Markdown syntax in a `prop`'s `value` with its current `string` data type as-is. We will _not_ propose a change to change its type or request an alternate Metschema structure to support inline Markdown with a [`markup-multiline`](https://pages.nist.gov/metaschema/specification/datatypes/#markup-data-types). -2. After Step 1 is complete, A FedRAMP constraint style guide should recommend or require the use of `help-url`, `help-text`, and `help-text-markdown` props. Below is an example of how these properties can look in an example constraints files. +2. After Step 1 is complete, A FedRAMP constraint style guide should recommend or require the use of `help-url`, `help-text`, and `help-markdown` props. Below is an example of how these properties can look in an example constraints files. ```xml @@ -44,7 +44,7 @@ The team proposes Solution 4. To implement this solution, we will commit to step - + Each data center address must contain a country code. From f69da1e350d063a089f96f3f9cce3bc6ae00c2cd Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Sun, 29 Sep 2024 17:32:26 -0400 Subject: [PATCH 13/16] [skip ci] Correct namespace per PR feedbacm. Co-authored-by: David Waltermire --- documents/adr/0009-constraint-based-help-docs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index a8f44d82d..85af13cdf 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -42,9 +42,9 @@ The team proposes Solution 4. To implement this solution, we will commit to step - - - + + + Each data center address must contain a country code. From f79bfe6515fec7d5940a000276fa5ade99468428 Mon Sep 17 00:00:00 2001 From: Kylie Hunter Date: Mon, 30 Sep 2024 17:56:15 -0400 Subject: [PATCH 14/16] [skip ci] Correct grammar, editing-edit per review Co-authored-by: Gabeblis --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 85af13cdf..c5d518e44 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -60,7 +60,7 @@ There are positive and negative impacts to each of the five solutions above. Bel 1. This approach has the lowest risk and effort for the FedRAMP Automation Team and maintainers of tool and data dependencies. However, it assures increased effort for developers of FedRAMP software and amplifies that same effort on downstream stakeholders who understand program requirements through those tools. This effort and friction will increase as the number of constraints increases over time. Operationally, tools will operate as they currently do at the time of this writing, so there will be no change in speed or performance characteristics of the tools. -1. This approach requires moderate effort for FedRAMP Automation Team developers maintaining constraints and developers of software for the FedRAMP ecosystem. The former will have to carefully editing new and existing constraints to track inserting additional information into the `message` field of a constraint. Downstream developers of software for the FedRAMP ecosystem will have to customize their tools to parse each message and extract different kinds of error information from the Metaschema modules or SARIF output without consistency and added complexity. It will, however, require little to no additional effort for maintainers of data and tool dependencies. Operationally, this may increase the size of constraint files and resulting results output in SARIF if guidance requires them to be output in all cases. +1. This approach requires moderate effort for FedRAMP Automation Team developers maintaining constraints and developers of software for the FedRAMP ecosystem. The former will have to carefully edit new and existing constraints to track inserting additional information into the `message` field of a constraint. Downstream developers of software for the FedRAMP ecosystem will have to customize their tools to parse each message and extract different kinds of error information from the Metaschema modules or SARIF output without consistency and added complexity. It will, however, require little to no additional effort for maintainers of data and tool dependencies. Operationally, this may increase the size of constraint files and resulting results output in SARIF if guidance requires them to be output in all cases. 1. This approach requires a nominal increase in effort for FedRAMP Automation Team developers, but for certain edge cases complicates design and implementation as such a property will be required. It will also cause a nominal increase in effort developers of software for the FedRAMP ecosystem, but give them a consistent way to extract necessary help documentation without ad-hoc parsing of the message field. Operationally, this approach will increase the size of constraint files and may increase resulting results output in SARIF if guidance requires them to be output in all cases. From 6db699c2aa9b949ba0edfbbd14ad5d50b20ee64d Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Mon, 30 Sep 2024 18:19:22 -0400 Subject: [PATCH 15/16] [skip ci] Clarify team vetted ahead of community Per valid PR feedback, we should clarify that AJ and the team drafted and reviewed the PR ahead of soliciting community review and feedback. --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index c5d518e44..5de99a111 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -16,7 +16,7 @@ This decision record proposes a solution to add machine-readable metadata to Fed ## Possible Solutions -There are multiple approaches for the team and larger community to consider. +The team considered multiple approaches listed below. 1. Do nothing, keep the development and use of constraints as-is, encourage users to manually reference documentation to help correct or improve OSCAL-based content for FedRAMP packages. From 9c3ef1be18fc8ea6407f50243d5c2e573e94945c Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 1 Oct 2024 15:15:17 -0400 Subject: [PATCH 16/16] [skip ci] Add newlines for `help-markdown` per final feedback Co-authored-by: David Waltermire --- documents/adr/0009-constraint-based-help-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/0009-constraint-based-help-docs.md b/documents/adr/0009-constraint-based-help-docs.md index 5de99a111..4d3b4a124 100644 --- a/documents/adr/0009-constraint-based-help-docs.md +++ b/documents/adr/0009-constraint-based-help-docs.md @@ -44,7 +44,7 @@ The team proposes Solution 4. To implement this solution, we will commit to step - + Each data center address must contain a country code.