Add documentation re well-formedness and validation.

[aj-stein-nist]

Committer Notes

Publish documentation re well-formedness and validation of OSCAL document instances. This implements part of #1153, but does not complete it. Additional PR to follow.

All Submissions:

• Have you selected the correct base branch per Contributing guidance?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you squashed any non-relevant commits and commit messages? [instructions]
• Do all automated CI/CD checks pass?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you included examples of how to use your new feature(s)?
• Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

[GaryGapinski]

Minor observation: lack of well-formed precludes schema validation, so well-formedness should precede schema validation.

[aj-stein-nist]

Don't we cover that later in the document?

What OSCAL tools help you check well-formedness?

NIST's OSCAL tools do not explicitly check that JSON, XML, or YAML is well-formed. If you are a tool developer, we expect you to use your language runtime and libraries to parse JSON, XML, and YAML and check for the well-formed data. This must occur before validating an OSCAL document. (Emphasis add here by me for context.)

[wendellpiez]

Well-formedness is logically prior but not temporally prior; indeed a big reason for grammar-based validation is that it can be performed at (concurrently with) the parse. To parse and then to validate is one way to do it; but there is nothing wrong with attempting validation and seeing what happens in the parse.

Suggest a little tweakage. In a runtime or in a workflow generally, validation may occur early and often, or only at system boundaries. What we are defining here is not how to validate, but what constitutes conformance ("valid to X schema"). We do not define XML, JSON or validation; only the OSCAL schemas.

[aj-stein-nist]

I can see your point, but I do not say whether it is logically or temporally before (if we are addressing the snippet where I copied from).

What do you recommend we add or take away?

I only added this bit to address the question in the section header: Q: What OSCAL tools [from NIST] check well-formedness? A: NIST's OSCAL tools do not provide tools to check well-formedness, because if you are a tool developer it is on you to check that before (logically or temporally) using schemas to validate. [This implies: do not report issues back to NIST with problems in schema validation when it is easy to spot the document isn't well-formed. These are not schema issues, it should be obvious but you ought to check the doc is well-formed somewhere in your code.]

So, how can we write that better?

[david-waltermire]

Looks like there is one bad link that is causing the build to fail:

git-content/oscal/docs/content/concepts/layer/_index.md
error: bad link validation at line 137

[aj-stein-nist]

OK, @david-waltermire-nist, pulled in all your feedback and squashed all the commits. Let me know what you want to do with the last comment, that is the only thing that requires further discussion and not immediate editorial changes.

[aj-stein-nist]

@david-waltermire-nist and @wendellpiez, I added some content and a suggestion from Wendell around using a SVG-based Venn diagram to clarify things. Colors, orientation, size (pre-render or during layout with stylesheet), any feedback, let me know.

[aj-stein-nist]

OK, now with more touchups and a much simpler and prettier SVG thanks to @wendellpiez. Demo from localhost below.

[david-waltermire]

Thanks for addressing the feedback!