Consistency of grouping names

[wendellpiez]

User Story:

In order to review consistency of the grouping names given to objects in OSCAL ...

Doing some analysis of the current OSCAL metaschema files, this path will return all the grouping names for arrays or compound objects in JSON or object notation (YAML) OSCAL variants:

( distinct-values(//group-as/@name) ) ! ('`' || . || '`') => string-join(', ')

... executed over the file set (allowing for namespaces), returns a list of hits in oXygen. I save out this result (report) in oXygen. I then performed a bit of XQuery over this file (actually this is still XPath):

declare default element namespace 'http://www.oxygenxml.com/ns/report';

//incident /
( '**' || replace(systemID,'.*\\','') || '**:  ' || description || '
' )

to receive this output (pasted directly, so with Markdown rendered):

oscal_assessment-common_metaschema.xml: properties, annotations, links, control-group, control-objective-group, objectives, assessment-methods, include-controls, exclude-controls, include-objectives, exclude-objectives, subject-references, parts, components, test-methods, include-activities, exclude-activities, test-steps, role-ids, party-uuids, tasks, activity-uuids, location-uuids, findings, observations, threat-ids, risks, observation-methods, observation-types, assessors, origins, relevant-evidence-group, risk-metrics, mitigating-factors, remediation-group, tracking-entries, requirements
oscal_assessment-plan_metaschema.xml: includes, excludes, components, inventory-items, users
oscal_assessment-results_metaschema.xml: results_group, includes, excludes, components, inventory-items, users
oscal_catalog_metaschema.xml: parameters, controls, groups, properties, annotations, links, parts
oscal_component_metaschema.xml: import-component-definitions, components, capabilities, properties, annotations, links, responsible-roles, protocols, control-implementations, incorporates-components, implemented-requirements, set-parameters, statements
oscal_control-common_metaschema.xml: properties, annotations, parts, links, constraints, guidelines, values, tests, choice
oscal_framework-common_metaschema.xml: implemented-requirements, properties, annotations, links, statements
oscal_implementation-common_metaschema.xml: properties, annotations, links, responsible-roles, protocols, port-ranges, role-ids, authorized-privileges, functions-performed, responsible-parties, implemented-components, party-uuids, values
oscal_metadata_metaschema.xml: revision-history, document-ids, properties, annotations, links, roles, locations, parties, responsible-parties, email-addresses, telephone-numbers, urls, external-ids, addresses, location-uuids, member-of-organizations, resources, rlinks, hash-values, party-uuids, postal-address
oscal_poam_metaschema.xml: components, inventory-items, properties, annotations, poam-item-group, observations, threat-ids, risks, party-uuids
oscal_profile_metaschema.xml: imports, groups, id-selectors, pattern-selectors, parameters, properties, annotations, links, parts, parameter-settings, alterations, constraints, guidelines, values, removals, additions
oscal_ssp_metaschema.xml: system-ids, properties, annotations, links, responsible-parties, information-types, information-type-ids, diagrams, leveraged-authorizations, users, components, inventory-items, implemented-requirements, by-components, responsible-roles, parameter-settings, statements, provided-group, responsibilities, inherited-group, satisfied-group

Goals:

Review this list for consistency and correctness.

For example, I can see several names with underscores _ do we want those?

Dependencies:

None known: this is independent of other Metaschema checks.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• 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.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[wendellpiez]

Relates to #717

[david-waltermire]

Can you provide a listing similar to the above which shows single-element-name -> group-property-name?

[wendellpiez]

Here is a comprehensive listing of definition references each with its given name, the "used name" if given on the reference (usually the same) and its grouping name. (Used names declared on definitions at the top level are not included as that would not be a one-liner.)

All the grouping names are given, including multiplicates, since they each have a group name and in theory it could be different. They are sorted alphabetically within each module for legibility and comparison.

Here is the XPath to produce a Markdown table listing the definitions or references designated with grouping names in each of the metaschema modules. The listing was produced from metaschemas in the metaschema-m4-integration branch and they should be reasonably current.

//group-as !
( '| ' || (../@name|../@ref) || ' | ' || ../(use-name,@name,@ref)[1] || ' | **' || @name || '** |' ) =>
sort() =>
string-join('
')

Catalog

name	use-name	group name
activity-uuid	activity-uuid	activity-uuids
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
assessment-method	assessment-method	assessment-methods
assessment-method	assessment-method	assessment-methods
assessment-part	assessment-part	parts
assessment-part	assessment-part	parts
assessor	assessor	assessors
control-objectives	control-objectives	control-objective-group
controls	controls	control-group
exclude-activity	exclude-activity	exclude-activities
exclude-control	exclude-control	exclude-controls
exclude-objective	exclude-objective	exclude-objectives
finding	finding	findings
include-activity	include-activity	include-activities
include-control	include-control	include-controls
include-objective	include-objective	include-objectives
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
location-uuid	location-uuid	location-uuids
location-uuid	location-uuid	location-uuids
location-uuid	location-uuid	location-uuids
mitigating-factor	mitigating-factor	mitigating-factors
objective	objective	objectives
observation	observation	observations
observation-method	method	methods
observation-type	type	types
origin	origin	origins
origin	origin	origins
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
relevant-evidence	relevant-evidence	relevant-evidence-group
remediation	remediation	remediation-group
required	required	requirements
risk	risk	risks
risk-metric	risk-metric	risk-metrics
role-id	role-id	role-ids
role-id	role-id	role-ids
role-id	role-id	role-ids
role-id	role-id	role-ids
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
system-component	component	components
task	task	tasks
test-method	test-method	test-methods
test-step	test-step	test-steps
threat-id	threat-id	threat-ids
tracking-entry	entry	entries

Control common

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
link	link	links
link	link	links
parameter-choice	choice	choice
parameter-constraint	constraint	constraints
parameter-guideline	guideline	guidelines
parameter-value	value	values
part	part	parts
property	prop	properties
property	prop	properties
test	test	tests

Metadata

name	use-name	group name
addr-line	addr-line	addr-lines
address	address	addresses
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
document-id	document-id	document-ids
document-id	document-id	document-ids
email-address	email-address	email-addresses
email-address	email-address	email-addresses
external-id	external-id	external-ids
hash	hash-value	hash-values
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
location	location	locations
location-uuid	location-uuid	location-uuids
member-of-organization	member-of-organization	member-of-organizations
party	party	parties
party-uuid	party-uuid	party-uuids
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
resource	resource	resources
responsible-party	responsible-party	responsible-parties
revision	revision	revision-history
rlink	rlink	rlinks
role	role	roles
telephone-number	telephone-number	telephone-numbers
telephone-number	telephone-number	telephone-numbers
url	url	urls

Profile

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
authorized-privilege	authorized-privilege	authorized-privileges
component-implemention-reference	implemented-component	implemented-components
function-performed	function-performed	functions-performed
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
parameter-value	value	values
party-uuid	party-uuid	party-uuids
port-range	port-range	port-ranges
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
protocol	protocol	protocols
responsible-party	responsible-party	responsible-parties
responsible-party	responsible-party	responsible-parties
responsible-role	responsible-role	responsible-roles
role-id	role-id	role-ids

SSP

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
by-component	by-component	by-components
by-component	by-component	by-components
categorization	categorization	categorizations
diagram	diagram	diagrams
diagram	diagram	diagrams
diagram	diagram	diagrams
implemented-requirement	implemented-requirement	implemented-requirements
information-type	information-type	information-types
information-type-id	information-type-id	information-type-ids
inherited	inherited	inherited-group
inventory-item	inventory-item	inventory-items
leveraged-authorization	leveraged-authorization	leveraged-authorizations
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
provided	provided	provided-group
responsibility	responsibility	responsibilities
responsible-party	responsible-party	responsible-parties
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
satisfied	satisfied	satisfied-group
set-parameter	set-parameter	parameter-settings
set-parameter	set-parameter	parameter-settings
set-parameter	set-parameter	parameter-settings
statement	statement	statements
system-component	component	components
system-id	system-id	system-ids
system-user	user	users

Component

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
capability	capability	capabilities
control-implementation	control-implementation	control-implementations
control-implementation	control-implementation	control-implementations
defined-component	component	components
implemented-requirement	implemented-requirement	implemented-requirements
import-component-definition	import-component-definition	import-component-definitions
incorporates-component	incorporates-component	incorporates-components
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
protocol	protocol	protocols
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
responsible-role	responsible-role	responsible-roles
set-parameter	set-parameter	set-parameters
statement	statement	statements

POA&M

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
inventory-item	inventory-item	inventory-items
observation	observation	observations
party-uuid	party-uuid	party-uuids
poam-item	poam-item	poam-item-group
prop	prop	properties
prop	prop	properties
risk	risk	risks
system-component	component	components
threat-id	threat-id	threat-ids

Implementation common

name	use-name	group name
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
authorized-privilege	authorized-privilege	authorized-privileges
component-implemention-reference	implemented-component	implemented-components
function-performed	function-performed	functions-performed
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
parameter-value	value	values
party-uuid	party-uuid	party-uuids
port-range	port-range	port-ranges
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
protocol	protocol	protocols
responsible-party	responsible-party	responsible-parties
responsible-party	responsible-party	responsible-parties
responsible-role	responsible-role	responsible-roles
role-id	role-id	role-ids

Assessment plan

name	use-name	group name
exclude-subject	exclude-subject	excludes
include-subject	include-subject	includes
inventory-item	inventory-item	inventory-items
system-component	component	components
system-user	user	users

Assessment results

name	use-name	group name
exclude-subject	exclude-subject	excludes
include-subject	include-subject	includes
inventory-item	inventory-item	inventory-items
results	results	results_group
system-component	component	components
system-user	user	users

Assessment common

name	use-name	group name
activity-uuid	activity-uuid	activity-uuids
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
annotation	annotation	annotations
assessment-method	assessment-method	assessment-methods
assessment-method	assessment-method	assessment-methods
assessment-part	assessment-part	parts
assessment-part	assessment-part	parts
assessor	assessor	assessors
control-objectives	control-objectives	control-objective-group
controls	controls	control-group
exclude-activity	exclude-activity	exclude-activities
exclude-control	exclude-control	exclude-controls
exclude-objective	exclude-objective	exclude-objectives
finding	finding	findings
include-activity	include-activity	include-activities
include-control	include-control	include-controls
include-objective	include-objective	include-objectives
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
link	link	links
location-uuid	location-uuid	location-uuids
location-uuid	location-uuid	location-uuids
location-uuid	location-uuid	location-uuids
mitigating-factor	mitigating-factor	mitigating-factors
objective	objective	objectives
observation	observation	observations
observation-method	method	methods
observation-type	type	types
origin	origin	origins
origin	origin	origins
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
party-uuid	party-uuid	party-uuids
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
property	prop	properties
relevant-evidence	relevant-evidence	relevant-evidence-group
remediation	remediation	remediation-group
required	required	requirements
risk	risk	risks
risk-metric	risk-metric	risk-metrics
role-id	role-id	role-ids
role-id	role-id	role-ids
role-id	role-id	role-ids
role-id	role-id	role-ids
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
subject-reference	subject-reference	subject-references
system-component	component	components
task	task	tasks
test-method	test-method	test-methods
test-step	test-step	test-steps
threat-id	threat-id	threat-ids
tracking-entry	entry	entries

[david-waltermire]

We need to take a look at the following:

Metadata

name	use-name	group name	proposed group name
revision	revision	revision-history	revisions?

SSP

name	use-name	group name	proposed group name
inherited	inherited	inherited-group	inherited?
provided	provided	provided-group	provided?
satisfied	satisfied	satisfied-group	satisfied?

POA&M

name	use-name	group name	proposed group name
poam-item	poam-item	poam-item-group	poam-items

Assessment plan

name	use-name	group name	proposed group name
exclude-subject	exclude-subject	excludes	exclude-subjects
include-subject	include-subject	includes	include-subjects

Assessment results

name	use-name	group name	proposed group name
exclude-subject	exclude-subject	excludes	exclude-subjects
include-subject	include-subject	includes	include-subjects
results	results	results_group	use "result"/"results"?

Assessment common

name	use-name	group name	proposed use name	proposed group name
assessment-part	assessment-part	parts	part	parts (see 1 below)
assessment-part	assessment-part	parts	part	parts (see 1 below)
control-objectives	control-objectives	control-objective-group	objective-selection	objective-selections (see 2 below)
controls	controls	control-group	control-selection	control-selections (see 2 below)
relevant-evidence	relevant-evidence	relevant-evidence-group	{same}	relevant-evidence (see 3 below)
remediation	remediation	remediation-group	{same}	remediations

1. This is a false positive as the use-name is already "part". Should the initial part be 1-many?
2. Should "controls" be renamed to "control-selection", with a group name of "control-selections"?
   • The parent "objectives" is single valued and should not be plural. Maybe rename this to "reviewed-controls"?
   • Should the "control-objectives" be renamed to "objective-selection" and "objective-selections"?
3. "evidence" is both singular and plural.

[david-waltermire]

PR #794 addresses the changes I posted above.