Top-down review of models

[wendellpiez]

User Story:

As the Metaschema has been refined, the models have changed somewhat to take advantage of new features. Now the Metaschema feature set is mainly stable, we have an opportunity to bring the models closer to "final" status. A top-down review of the metaschemas (and their schemas) is appropriate.

Goals:

Review the metaschemas to see that they take full advantage of available features in the Metaschema, and ensure their consistency internally and with one another.

In particular, we should review the following:

• Review group-as values to make sure the naming, cardinality, and XML/JSON bindings are consistent with the concept being described.
• Check cardinality constraints on fields and assemblies
• Assigned data types (to flags and field values)
• Which flags should be declared locally instead of globally? candidates for globals include anything with really global semantics
  • @id
  • @href
  • @rel
    anything else should be local including control-id and all the rest - especially those to which we intend to bind referential/key constraints
• Features enabling more concise JSON are being used appropriately:
  • json-key to address (label) an object using a flag value (Adding JSON value keys to fields in Catalog and Profile models #466)
  • json-value-key to provide meaningful labels for field values
• Review the name and definition of all flags, fields, and assemblies to make sure their naming is consistent and the definition/usage guidance is contextualized.

Additionally, we can take the opportunity to add any rules checking to the Metaschema Schematron to help ensure consistency going forward.

nb This includes a Metaschema check against using group-as when @max-occurs is 1 or not given (i.e., is 1 by default).

Finally, we can use this review as an opportunity to capture, organize and prioritize new Metaschema feature requests. such as being able to declare fields (not only flags) locally.

Dependencies:

We should be able to perform this review and make improvements without making any XML source data invalid: after these changes XML source data should still be valid to XSDs produced from revised metaschemas. However, JSON will have to be generated fresh to conform to new JSON schemas where json-key and json-value-key have been introduced.

Acceptance Criteria

• Models have been inspected and reviewed with respect to the questions above and any questions that arise during review
• As decided by consensus, adjustments / improvements to models have been made accordingly in the metaschemas, or planned for future work
• Any new rules for the Metaschema (syntax or semantic representation) have been implemented and tested, and all metaschemas pass; and/or
• New feature requests for Metaschema (semantics) have been captured on one or more (new) Issues as appropriate, referencing this Issue (and noted below).
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR

Note that changes to source data are not in scope for this Issue.

[david-waltermire]

I am starting a branch for changes based on this issue and #466. Please submit PRs against this branch for any changes.

[iMichaela]

9/5/2019

We will park this issue for another week to catch up on other issues that need to be reviewed as part of this top-down review of the model.

[wendellpiez]

Also see #307, which could be folded into this effort.

[wendellpiez]

I would like in particular to examine use of elements desc and description.

These could perhaps be consolidated, except one has text contents, the other has element (paragraph) contents.

We might consider collapsing this distinction or renaming for less confusion. desc, for example, could be short-desc where it's meant to be a one-liner (not containing paragraphs).

[david-waltermire]

While some review has been completed in PR #493, this review was not completed. This work is still ongoing. Adding to sprint 25.

[wendellpiez]

Note: the SSP model has an element set-param. For consistency with the profile model, it should be called set.

[wendellpiez]

Also noting that the responsible-role and responsible-party elements look very similar and should potentially be consolidated. (responsibility?) They also both look very similar to role...

[wendellpiez]

Similarly I wonder if there is not clarification possible among (between) party, role and user.

[brian-ruf]

@wendellpiez, yes I noticed when developing the Guide to OSCAL-based FedRAMP SSPs, there were a few places where responsible-role and responsible-party were confusingly similar - especially when working with components and inventory.
It is responsible-role in the component assembly, but responsible-party in the inventory-items assembly. It appears to have all of the same data elements, except the party-id field is farther down with the component assembly.

As much as any change like this forces me to change that documentation, I think it's worth simplifying the syntax if they are truly intended to be the same.

[brian-ruf]

@wendellpiez I agree the lines between party, role, and user are blurry, and could benefit from clarification.

First, party/role is defined in the metadata and is intended to be used broadly throughout any OSCAL layer, where the user assembly is just in the SSP syntax, added to capture system-specific user information, which includes several details not modeled for parties in metadata.

Likewise, even being involved in the discussions and understanding the rationale between role, party, and responsible-role in metadata, I find it cumbersome and a little confusing to implement. Especially when adding responsible-role/responsible-party in other assemblies, and especially when trying to use these assemblies in convert with the users assembly.

There is a lot of content in the FedRAMP Guide that is either already generic or could be made generic fairly easily, if it's worth re-using the content to inform non-FedRAMP uses of OSCAL.

[wendellpiez]

Yes, let's look at all these. If the model for user is a superset of the model for role they could potentially be consolidated. Even more so for responsible-party and responsible-role based on what you report.

Essentially what we have here is a network of dependent (one-way) relations between the system, its components, requirements, users/roles, designated responsibilities, and parties. Maybe we should sketch that out as a way of reducing it to its essentials.

[wendellpiez]

Noting today that we should consider making description optional wherever it can appear.

[david-waltermire]

This review is complete in PR #758.

[david-waltermire]

This issue was addressed by PR #758.