Updating docs production for 'key' and 'value-key' functionality #428
Comments
|
We have addressed most of the issues. More refactoring can happen in Sprint 22. |
wendellpiez
added a commit
to wendellpiez/OSCAL
that referenced
this issue
Jul 2, 2019
|
Making progress. Latest is XSD validation to ensure that values to be promoted to keys in the JSON, are distinct within the scope of the parent object (element). |
wendellpiez
added a commit
to wendellpiez/OSCAL
that referenced
this issue
Jul 18, 2019
wendellpiez
added a commit
to wendellpiez/OSCAL
that referenced
this issue
Jul 22, 2019
wendellpiez
added a commit
to wendellpiez/OSCAL
that referenced
this issue
Jul 24, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
pushed a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 16, 2019
david-waltermire
added a commit
that referenced
this issue
Aug 22, 2019
* Supporting enumerated value lists on flags in XSD and JSON Schema #437 * Metaschema improvements and remodeling flags support (local definitions; moving w/in the model; valid values) * More Metaschema syntax remodeling: now using max-occurs and min-occurs for cardinality indicators #441 * Updating schemas to current model (transitional); updated docs in resulting XSD per #448; some updates to markdown documentation * Small updates to authoring CSS. * Added design notes on JSON schema bindings. * Including an initial set of unit tests for group-by, some data types, etc. * Updated to new design (#436): Metaschema schema, Schematron, metaschema update XSLT - will break the build for now * Work on datatyping #436 including support in XML and JSON Schema * Addressed #451: parameter insertion syntax in Markdown * Schema documentation improvements #423 #424 #428 * Addressed feature request #438 * Improving handling of JSON 'key' and 'value-key' settings in docs #428 * Now producing XML and JSON model maps from metaschemas. * Now escaping {{ for Jekyll * Updated component metaschema based on design notes * Fixed schematron assertions to properly work with @ref. * Refactoring of component and SSP metachema. * Fixed website side navigation. Added component and SSP metaschema to site generation process. * Addressed comments in issue #445 * Added site content generation to runall.sh * Started documenting model changes in release notes. More work is still needed to complete this.
david-waltermire
added a commit
to david-waltermire/OSCAL
that referenced
this issue
Aug 26, 2019
* Supporting enumerated value lists on flags in XSD and JSON Schema usnistgov#437 * Metaschema improvements and remodeling flags support (local definitions; moving w/in the model; valid values) * More Metaschema syntax remodeling: now using max-occurs and min-occurs for cardinality indicators usnistgov#441 * Updating schemas to current model (transitional); updated docs in resulting XSD per usnistgov#448; some updates to markdown documentation * Small updates to authoring CSS. * Added design notes on JSON schema bindings. * Including an initial set of unit tests for group-by, some data types, etc. * Updated to new design (usnistgov#436): Metaschema schema, Schematron, metaschema update XSLT - will break the build for now * Work on datatyping usnistgov#436 including support in XML and JSON Schema * Addressed usnistgov#451: parameter insertion syntax in Markdown * Schema documentation improvements usnistgov#423 usnistgov#424 usnistgov#428 * Addressed feature request usnistgov#438 * Improving handling of JSON 'key' and 'value-key' settings in docs usnistgov#428 * Now producing XML and JSON model maps from metaschemas. * Now escaping {{ for Jekyll * Updated component metaschema based on design notes * Fixed schematron assertions to properly work with @ref. * Refactoring of component and SSP metachema. * Fixed website side navigation. Added component and SSP metaschema to site generation process. * Addressed comments in issue usnistgov#445 * Added site content generation to runall.sh * Started documenting model changes in release notes. More work is still needed to complete this.
|
This has been completed in PR #464. |
bradh
pushed a commit
to bradh/OSCAL
that referenced
this issue
Dec 4, 2019
* Supporting enumerated value lists on flags in XSD and JSON Schema usnistgov#437 * Metaschema improvements and remodeling flags support (local definitions; moving w/in the model; valid values) * More Metaschema syntax remodeling: now using max-occurs and min-occurs for cardinality indicators usnistgov#441 * Updating schemas to current model (transitional); updated docs in resulting XSD per usnistgov#448; some updates to markdown documentation * Small updates to authoring CSS. * Added design notes on JSON schema bindings. * Including an initial set of unit tests for group-by, some data types, etc. * Updated to new design (usnistgov#436): Metaschema schema, Schematron, metaschema update XSLT - will break the build for now * Work on datatyping usnistgov#436 including support in XML and JSON Schema * Addressed usnistgov#451: parameter insertion syntax in Markdown * Schema documentation improvements usnistgov#423 usnistgov#424 usnistgov#428 * Addressed feature request usnistgov#438 * Improving handling of JSON 'key' and 'value-key' settings in docs usnistgov#428 * Now producing XML and JSON model maps from metaschemas. * Now escaping {{ for Jekyll * Updated component metaschema based on design notes * Fixed schematron assertions to properly work with @ref. * Refactoring of component and SSP metachema. * Fixed website side navigation. Added component and SSP metaschema to site generation process. * Addressed comments in issue usnistgov#445 * Added site content generation to runall.sh * Started documenting model changes in release notes. More work is still needed to complete this.
aj-stein-nist
pushed a commit
to aj-stein-nist/OSCAL-forked
that referenced
this issue
Jan 25, 2023
* Supporting enumerated value lists on flags in XSD and JSON Schema usnistgov#437 * Metaschema improvements and remodeling flags support (local definitions; moving w/in the model; valid values) * More Metaschema syntax remodeling: now using max-occurs and min-occurs for cardinality indicators usnistgov#441 * Updating schemas to current model (transitional); updated docs in resulting XSD per usnistgov#448; some updates to markdown documentation * Small updates to authoring CSS. * Added design notes on JSON schema bindings. * Including an initial set of unit tests for group-by, some data types, etc. * Updated to new design (usnistgov#436): Metaschema schema, Schematron, metaschema update XSLT - will break the build for now * Work on datatyping usnistgov#436 including support in XML and JSON Schema * Addressed usnistgov#451: parameter insertion syntax in Markdown * Schema documentation improvements usnistgov#423 usnistgov#424 usnistgov#428 * Addressed feature request usnistgov#438 * Improving handling of JSON 'key' and 'value-key' settings in docs usnistgov#428 * Now producing XML and JSON model maps from metaschemas. * Now escaping {{ for Jekyll * Updated component metaschema based on design notes * Fixed schematron assertions to properly work with @ref. * Refactoring of component and SSP metachema. * Fixed website side navigation. Added component and SSP metaschema to site generation process. * Addressed comments in issue usnistgov#445 * Added site content generation to runall.sh * Started documenting model changes in release notes. More work is still needed to complete this.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Describe the bug
We have extended Metaschema with features to support renaming and sometimes promotion of JSON objects. They are "key" and "value-key" as described in the Metaschema XSD and as examples show.
However, the generated documentation does not describe these features or reflect their use. Because the production pipeline is out of synch with the current Metaschema model, it shows holes and lapses.
On the XML side, a key produces an attribute (like a flag), which must be documented - so the key must be documented as a special kind of flag. On the JSON side, both keys and value keys need to be described since they directly affect the JSON representation.
Note that these features may also be redesigned for simplicity but this Issue does not depend on that redesign.
Who is the bug affecting?
Anyone who tries to read the documentation and understand the data on that basis.
What is affected by this bug?
Users won't have an accurate understanding of OSCAL features.
When does this occur?
Anytime the documentation is consulted.
How do we replicate the issue?
Run the documentation pipeline including schema documentation production.
Expected behavior (i.e. solution)
At least two informed readers should agree the documentation is complete and accurate with respect to these features.
The text was updated successfully, but these errors were encountered: