Allow flags to be defined within a field or assembly

[david-waltermire]

User Story:

As an OSCAL model developer, I need a more concise way to define flags in the various OSCAL Metaschema models.

Goals:

• Allow flag definitions to be scoped to the containing field or assembly. In most cases flag are defined and used in the context of a single field or assembly. In these cases defining a flag as a separate "object" using define-flag is a bit of overkill.

  Including flags in the docs over-complicates the generated documentation littering the docs with a bunch of flag definitions. IMHO, I would like to see the information elements displayed in the left navigation of our docs be limited to the field and assembly objects as these represent the core concepts we are modeling. This will bring out these concepts in the docs and make navigation easier with less clutter.

  Defining flags within a field or assembly will make modeling easier, avoiding the current indirection between definition and use. This indirection results in having to navigate between the define-field or define-assembly and the define-flag definition.

  Many global flags, like "name", "title", or "label", have no real global semantics, but instead are contextual within their containing object. Localizing these cases will allow a given Metamodel to be more semantically concise.

• It would be useful to define some flag definitions as global. In some cases a flag has a specific global semantic that is common across all use cases. This is the rare exception to the rule. In these cases when generating the documentation, we can flatten/copy these to the calling define-field or define-assembly to make them look the same as context-specific flags. The metaschema-compose process could do this.

• Contextualizing the use of flags will also make name collisions less likely (Same Field/Flag Names Used in Different Context #307), as a given context can have a flag with the same name as a different context, with completely different types and valid values used in each case. This is desirable IMHO. This can be implemented in our conversion process by incorporating the calling context to address context sensitive round-trip issues.

Dependencies:

This represents a partial solution to #307, for flags only.

Acceptance Criteria

• The Metaschema schema and schematron are updated to reflect all of the flag-related changes.
• XML and JSON documentation generated by the CI/CD workflow correctly represents the flags defined by the Metaschema instances.
• All metaschema defintiions are updated to use the new feature, removing unneeded global flags.
• The Metaschema definitions are updated in a way that result in no changes to associated content.
• Documentation on the use of Metaschema is updated to fully document these features.
• A single PR is approved that contains the above changes.

[wendellpiez]

Done in branch here: https://github.com/wendellpiez/OSCAL/tree/sprint22-metaschema

[iMichaela]

7/11/2019

This issue and the related ones (#440, #441, #437, #436, #442 & #448 ) for the metaschema need to be reviewed together and unitested. However more unit tests need to be created for the other features.

[david-waltermire]

This has been completed in PR #464.