-
Notifications
You must be signed in to change notification settings - Fork 181
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Queries for schema documentation top-down polish #801
Queries for schema documentation top-down polish #801
Comments
Combining this with #839, at least some of these items could be supported via Schematron. |
This sounds interesting and beneficial (to me, personally). Should we not declare #1185 as a dependency and finish that before have Schematron that enforces documentation style we haven't formally documented yet? |
Sure. We could also include, or create follow-on tickets for, a couple of other items we have discussed:
|
Let's meet and float requirements, and spike a representation Schematron with relevant XPath queries to demonstrate the approach, decided to flesh and include more requirements. @aj-stein-nist will set up and coordinate the meeting. |
@Rene2mt, I am going to send you an email regarding ☝️. You are the only person for whom I cannot view a calendar, but will want to get a brief meeting on the agenda to make sure this does not slip through the cracks. Once I get that, I will book something for all of us. |
I tentatively scheduled a meeting and some pairing volunteered by Wendell on Friday. I will write some updates here on Friday. |
Example, with the m: prefix bound to Metaschema:
|
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801.
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]>
We all met as a group and tried one of the tentative items for editorial or documentation requirements beyond capitalization. We will push up the PR as proof of spike, and either merge or close with the sprint and reopen accordingly with Dave after he returns from leave. @Rene2mt had some ideas regarding the recommendation or enforcement of newer OSCAL/src/metaschema/oscal_metadata_metaschema.xml Lines 83 to 87 in d3309d3
Towards the end of the call, we experimented with SQF for adding periods to the rule in #1501 and how to extend that for recommended |
For unique identifier documentation in the Metaschemas, we should check the following:
|
@Rene2mt this is great. Almost specific enough to code to. Let me take a shot at a narrower spec:
This is good stuff, but its complexity also suggests to me we might do better with an honest "constraint definition" element applicable to such IDs. Indeed, it strikes me this might be expressed as a type of constraint: <constraint>
<constrain-id type="human-oriented" uniqueness="instance" scope="cross-instance" persistence="per-subject"/>
</constraint> If we had this instead of props, more would have to happen in back, but this would be cleaner and easier both to code and to validate, even in implementations. Thoughts? |
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]>
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]>
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug.
This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of #801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
I think we are good here but I am not sure how we further the impressions of the usefulness of the spiked code and move it forward? Thoughts. I presume later this week we will opt to close, but wanted to consider how address some of @wendellpiez and @Rene2mt's discussion. As it stands, it was reorganized, but this not only can be used in the IDE, it is enforced in CI/CD and block PRs with the small lift change. We can now consider next steps on more useful rules to help develop near real-time feedback. |
@david-waltermire-nist and I had a moment to sync on this, earlier today. Next up on this Issue, IIRC, is to finalize a punchlist of features we want for the present (in an authoring Schematron), see to it they are implemented, and put it to bed for now. We briefly discussed how this overlaps with other validations, for example under CI/CD, but how that should necessarily be a blocker. We also spoke about the idea of introducing semantics into Metaschema that translate only into Schematron -- such as the Thoughts? I think experience will show where it is nice to have the rules enforced, whether in authoring, in CI/CD or both. I could work with someone on finalizing this feature set - maybe @aj-stein-nist assuming aligning with the CI/CD setup makes sense. |
Can we set aside some time on Thursday to chat and sketch some of this out and put together some issues as a like a minimalish epic and the progression of tasks to the backlog? |
I am going to wait until we can discuss this to close this issue. That will give us time to identify any additional new issues to work. |
I dropped the ball on this. I just reviewed with Dave. For me: I need to set up a session with @david-waltermire-nist and @wendellpiez to plan out the next steps. |
Dave, Wendell, and I synced up. As we imagine future work, there are a few avenues of work, organized by category.
|
I need to add these issues ☝️ in the evening to close this out as part of Sprint 60. I will not be moving this issue forward to Sprint 61, and will then ping Dave accordingly. |
@david-waltermire-nist as agreed, I am closing this now that I have set up the relevant issues to continue this work. Apologies for the delay. |
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov/OSCAL#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov/OSCAL#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
Relocated from usnistgov/OSCAL@ef8fa01 as previously coded in usnistgov/OSCAL#1501 for usnistgov/OSCAL#801. Relocated per feedback from Dave in that PR.
* Add possible Schematron documentation checks This is the product of the meeting and spike where we pair-programmed and came up with example Schematron rules for tentative editorial standards that can be used for reviews of models and embedded docs as part of usnistgov#801. Co-authored-by: Chris Compton <[email protected]> Co-authored-by: Rene Rene Tshiteya <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Add CI/CD checking of Schematron doc standards checking. Always zip and upload Schematron validation results for potential debug. * After, show the Schematron checks passing after Metaschema def fixes. * Revert validate-metaschema.sh changes. * Revert refactored Schematron and remove from PR. * Update metaschema module to include updated Schematron in usnistgov/metaschema#246. Co-authored-by: David Waltermire <[email protected]>
User Story:
Consistency and usage of language and terminology in documentation including editorial policy can to a certain degree be supported with Schematron. For example, a Schematron rule can say 'descriptions should not be full sentences, only phrases' and then detect periods or other forbidden punctuation. More generally (and more lightweight), queries such as
//formal-name
will help us take a top-down view of the usage of this element.Goals:
Develop and apply some simple queries to run over Metaschema source, to provide editorial support and improve the level of 'polish' of the design and resulting documents. Deploy them as either/both Schematron or (documented) XPath/XQuery.
Making the actual changes is not in scope for this Issue; it can either be done as part of regular editorial work, or spun into an Issue of its own. However, this Issue can be considered done as soon as we have some means of assurance that the docs have the needed consistency, with long-term support tooling being a spin-off goal.
Example rules (for discussion / tbd):
;
(?)Dependencies:
None.
Acceptance Criteria
{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.}
The text was updated successfully, but these errors were encountered: