Models and instances with hidden or implied roots

[aj-stein-nist]

User Story:

As a Metaschema tooling developer, to effectively model and process conforming instances for information and data models that do not have an explicit root objects, I want to be able to define an information model where there is no explicit root object, it is "hidden" or "implied." Discussion and explanation of those terms is below in the goals section.

Goals:

Background

Currently, Metaschema supports models where there is a defined root. For example, below is a simple model in the module below and a sample document.

Example model with current Metaschema

<?xml version="1.0" encoding="UTF-8"?>
<METASCHEMA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 [../../../../../../core/metaschema/schema/xml/metaschema.xsd](https://raw.githubusercontent.com/usnistgov/metaschema/develop/schema/xml/metaschema.xsd)"
 xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0">
  <schema-name>Simple Metaschema</schema-name>
  <schema-version>1.0</schema-version>
  <short-name>simple</short-name>
  <namespace>http://csrc.nist.gov/ns/metaschema/testing/simple</namespace>
  <json-base-uri>http://csrc.nist.gov/ns/metaschema/testing/simple</json-base-uri>
  
  <define-assembly name="top-level">
    <formal-name>Root</formal-name>
    <description>Root assembly</description>
    <root-name>top-level</root-name>
    <flag ref="id"/>
    <model/>
  </define-assembly>
  
  <define-flag name="id">
    <formal-name>Identifier</formal-name>
    <description>The document identifier</description>
  </define-flag>
</METASCHEMA>

{
  "top-level": {"id": "test"}
}

If we were to attempt adapting this example to not have a top-level, the specification implies by absence this is not supported and tools generate/process the models incorrectly or explicitly throw errors. Therefore, you cannot model this.

{"id": "test"}

We can say here the "top-level" (or root) should be either explicitly hidden or implied for one or more field, flags, or assemblies (this is a very simplistic example of what is "the minimal viable data," but more complex minmally viable data structures like a combination of field, flag, and/or assemblies is possible, especially given SARIF.

Recently, the Metaschema maintainer team is evaluating the SARIF spec and format for constraint validation results) in #517 as part of #516. SARIF is one such format that will be hard to model unless a hidden or implied root can be defined. Below shows a pragmatic examples SARIF example.

Inline copy of the current SARIF model in JSON Schema for reference

```json { "version": "2.1.0", "$schema": "http://json.schemastore.org/sarif-2.1.0-rtm.4", "runs": [ { "tool": { "driver": { "name": "ESLint", "informationUri": "https://eslint.org", "rules": [ { "id": "no-unused-vars", "shortDescription": { "text": "disallow unused variables" }, "helpUri": "https://eslint.org/docs/rules/no-unused-vars", "properties": { "category": "Variables" } } ] } }, "artifacts": [ { "location": { "uri": "file:///C:/dev/sarif/sarif-tutorials/samples/Introduction/simple-example.js" } } ], "results": [ { "level": "error", "message": { "text": "'x' is assigned a value but never used." }, "locations": [ { "physicalLocation": { "artifactLocation": { "uri": "file:///C:/dev/sarif/sarif-tutorials/samples/Introduction/simple-example.js", "index": 0 }, "region": { "startLine": 1, "startColumn": 5 } } } ], "ruleId": "no-unused-vars", "ruleIndex": 0 } ] } ] } ```

In the near-term, the current workaround is adding an explicit placeholder root. Medium to long-term this epic will identity design work and spec modifications to formally support a hidden and/or implied root and roll back such workarounds.

Use Case 1: Single Valued Items

Use Case 2: Grouped Values (XML Sequences, JSON Arrays)

Dependencies:

{Describe any previous issues or related work that must be completed to start or complete this issue.}

Acceptance Criteria

• 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.
• 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.}