Prohibit field and flag names with Metapath non-terminals

[aj-stein-nist]

User Story:

As a Metaschema developer, in order to ensure I do not make models with flag names, I would like constraints for the core Metaschema syntax modules to warn me as a developer I should not use a Metapath terminal symbol as a field or flag name that cause grammar-based parsing errors in my tool.

For example, when updating a tutorial in https://github.com/usnistgov/metaschema/pull/539, I errantly created a flag with the name of namespace.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="https://raw.githubusercontent.com/usnistgov/metaschema/develop/schema/xml/metaschema.xsd" type="application/xml" schematypens="http://www.w3.org/2001/XMLSchema"?>
<METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0">
  <schema-name>Computer Model</schema-name>
  <schema-version>0.0.10</schema-version>
    <short-name>computer</short-name>
  <namespace>http://example.com/ns/computer</namespace>
  <json-base-uri>http://example.com/ns/computer</json-base-uri>
  <define-assembly name="property">
    <formal-name>Computer Property</formal-name>
    <description>A property is a key-value pair of metadata about the computer, not its parts.</description>
    <define-flag name="key" as-type="token" required="yes"/>
    <define-flag name="value" as-type="string" required="yes"/>
    <define-flag name="namespace" as-type="uri" required="yes" default="http://example-consortium.org"/>
    <constraint>
      <allowed-values target=".[@namespace='http://example-consortium.org' and @key='release-status']/@value">
        <enum value="unknown"/>
        <enum value="not-applicable"/>
        <enum value="in-development"/>
        <enum value="public"/>
        <enum value="obsolete"/>
      </allowed-values>
      <matches target=".[@namespace='http://example-consortium.org' and @key='release-date']/@value" datatype="date-with-timezone"/>
    </constraint>
...

ANTLR or othr systems build on context-free grammars, and the tool that leverage them, will fail. Metapath 1.x is targeting a subset of the XPath 3.0 specification, and A.2.2 defines "namespace" and other non-delimiting terminal symbols, with the same effect in Metapath, that will lead to runtime compile errors because the use of a such a symbol that should only be in the grammar to be extent in the document instance being parsed.

org.antlr.v4.runtime.misc.ParseCancellationException: line 1:2 mismatched input 'namespace' expecting {'@', '.', '..', '$', '-', '(', '+', '*:', '/', '//', '*', 'ancestor', 'ancestor-or-self', 'and', 'child', 'descendant', 'descendant-or-self', 'div', 'else', 'empty-sequence', 'eq', 'every', 'except', 'for', 'ge', 'gt', 'idiv', 'if', 'in', 'intersect', 'le', 'let', 'lt', 'mod', 'ne', 'or', 'parent', 'preceding', 'preceding-sibling', 'return', 'satisfies', 'self', 'some', 'then', 'union', IntegerLiteral, DecimalLiteral, DoubleLiteral, StringLiteral, URIQualifiedName, BracedURILiteral, QName, NCName}

Goals:

• [ ] Prohibit the use problematic names and
• [ ] Limit runtime errors at development and build time

Dependencies:

N/A

Acceptance Criteria

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

[david-waltermire]

Perhaps we could add a constraint in the Metaschema syntax model to warning (level="WARNING") about this issue for all flag, field, and assembly names that match a reserved keyword?

[aj-stein-nist]

Per conversation with @david-waltermire and others during a community sync meeting, I am ok with:

1. Putting a WARNING constraint on the core metaschema-module module for @name define-flag, define-field, and perhaps the value of use-name. Am I missing anything else?
2. Updating any relevant documentation in the related specs (if there is any, I am not sure there is but will peruse).
3. Leave the XML Schema alone because we are confident we cannot come up a construct for that the core Metaschema module XML schemas. Did I understand this correctly as the group verdict?

If I got this correctly, I can move on this quickly. Is this concern and the Metaschema changes 1.0 worthy? The higher-level aliasing concern, which we all agreed is not 1.0 worth is another issue and I can definitely open up another issue for that later today.