Document Use of Parameters in Catalog and Profile models

[david-waltermire]

User Story:

As an OSCAL catalog or profile content author, I need to understand the difference between the various elements allowed in a parameter. The documentation needs to clearly define what each element is intended to indicate.

Goals:

1. Document the use of the label, requirement, value, and selection elements provided within a parameter. This will be done in the metaschema. (@PCrayton)
2. Create simple examples in the metaschema for use of all parameter features. Use current catalog a profile content as sources of examples. (@PCrayton)
3. Ensure all example data uses the parameter elements correctly. (@wendellpiez)

Dependencies:

#193 must be completed to support this issue.

Acceptance Criteria

• Use of all profile features are clearly documented with supporting examples in the metaschema.
• The pages.nist.gov/OSCAL site is updated with this documentation.
• All XML and JSON schema are consistent with documentation.

[david-waltermire]

We noted the following during a previous design meeting, which can be used as a starting point for this issue:
- label (1)(required) - text from SP800-53rev4
- desc (0-to-many:catalog + profile) - a textual description of the parameter
- requirement (0-to-1:profile) - A textual description of a constraint on the allowed values (e.g., every 3 months)
- value (0-to-1:catalog + profile) - The actual value(s) to be used for the parameter.

[brian-ruf]

Developed a draft diagram and mapping of parameter usage, and discussed with Wendell. Revising and intend to have a final next week. Will continue to coordinate with Wendell to ensure alignment with metashema.

[wendellpiez]

Current models in both schema and metaschema for param (appears in catalogs) reflect this. The model for set-param (in profiles) is the same except that label is optional (the expectation being that it should ordinarily come from the catalog).

What needs to be determined is what happens to these elements in profile resolution. A simple semantics might be that when set for a parameter, any element given i.e. label,desc,constraint (nb: not "requirement") or value, will replace any element of the same name in the parameter being set (which thereby functions as a fallback setting). Another not as simple would be the same, except that desc would be additive, not replacing. A slightly stricter model might prohibit label from set-param, on the grounds that a label should not be overwritten even if a description is.

FWIW, current models also permit link and part inside param and set-param; their behaviors too are not specified.

[david-waltermire]

2018-06-07 Meeting Notes

@brianrufgsa and @david-waltermire-nist will meet to work on this during the week of 6/18.

[brian-ruf]

June 14 Status:
Developed draft diagram to show the evolution of a parameter from initial identification (typically in a catalog), through possible modifications and constraints (typically in a profile), and value assignment in the implementation layer. Solicited input from Wendell. Revising diagram.

[david-waltermire]

6/21/2018 Status

• Work is mostly done on documenting parameters in the catalog. Some fields remain to be documented.
• Profile documentation for parameters has not been started. This should echo what is documented at the catalog level, but should be applied to set-param.
• @kscarf1, @wendellpiez, @PCrayton , and @david-waltermire-nist need to meet to discuss the way forward.

[kscarf1]

June 27, 2018 status: Standing by to help when needed.

[wendellpiez]

Likewise. 👍 This is on tomorrow's agenda as well.

[iMichaela]

June 28 Status Meeting Update

This will be discussed again during the June 29 meeting. A decision will be made then.

[iMichaela]

July 18 Status Update (Sprint 12 Acceptance Meeting)
The issue depends on #193 which is waiting for a review from @david-waltermire-nist and/or @iMichaela

[iMichaela]

Status Meeting: 8/23/2018

Little progress was made. @PCrayton is working on the documentation and this user story will be part of the documentation.

[PCrayton]

8/30/18 Status
Working on properly documenting the use of parameters in the catalog and profile documentation as per Issue #212
Issues: None at this time

[PCrayton]

9/6/18 Status

Shared documentation efforts with @david-waltermire-nist and will include his input into the parameter documentation.

[iMichaela]

9/26/2018

@PCrayton received feedback from @wendellpiez and need just a little more time (low effort) in Sprint 14.

[david-waltermire]

10/11/18 Status

---

Will be addressed by the same PR as #212.

[wendellpiez]

Suggest tying this to #341 and closing it when we are happy with schema documentation.

[david-waltermire]

This has been completed and has been posted to pages.nist.gov in PR #326.