Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Document the OSCAL Catalog Schema for catalog consumers / catalog maintainers / tool vendors #111

Closed
akarmel opened this issue Feb 20, 2018 · 8 comments
Closed

Document the OSCAL Catalog Schema for catalog consumers / catalog maintainers / tool vendors #111

akarmel opened this issue Feb 20, 2018 · 8 comments
Assignees
@wendellpiez @david-waltermire @kscarf1
Labels
LoE: Medium User Story
Milestone
OSCAL 1.0 Milesto...

Comments

@akarmel
Copy link
Contributor

akarmel commented Feb 20, 2018

As a OSCAL catalog consumer, catalog maintainer or tool vendor, I have access to detailed, clear and concise documentation about the OSCAL catalog and how I can use it in my organization.

Goals:
Develop detailed, clear and concise documentation about the OSCAL catalog as started in #58

Dependencies:
Stable catalog model

Acceptance Criteria
Detailed, clear and concise documentation exists for the OSCAL catalog.
@akarmel akarmel mentioned this issue Feb 20, 2018
Closed
@kscarf1 kscarf1 assigned kscarf1 and unassigned kscarfone Feb 21, 2018
@wendellpiez
Copy link
Contributor

wendellpiez commented Feb 21, 2018 •
edited
Loading

A substantial fraction of elements in the core schema relate to OSCAL declarations. While the declarations model is not central for applications of OSCAL data (most users will not have to think about declarations), it is arguably essential for anyone having to create, maintain and support the use of catalogs, and may also be key (we will get there) to frameworks. Indeed one starting point for thinking about frameworks in OSCAL terms might be "somewhat like a catalog, but with more limited, constrained or targeted applicability, with its own local semantics (perhaps with supporting declarations) especially bearing on links and references to (controls and components in other) frameworks, profiles and catalogs".

All this suggests the importance of how we document and explain the declarations model and its utility. What is the utility of the declarations model? A set of OSCAL declarations expresses a set of extra-schema constraints over a "flavor" or template for OSCAL controls (or enhancements) or components. As such, it exposes a contract over the data that can be tested externally. It makes it possible to build a conceptual fence or "closed world" around a predefined subset of documents in OSCAL's "open world".

Yet from a user's point of view, discussion of the declarations model might be merely confusing, since the declarations for any catalog will already have been produced (by the catalog designers or encoders) and the catalog (if it's any good) already has all its data conformant to the constraints expressed in the declarations. So it is all done already, and even understanding it seems like (and may indeed be) a detour from more pressing questions. This presents an obstacle.

One way to address this might be a separate guide to OSCAL declarations with a walkthrough of the semantics of the declarations in (one of) our example catalogs. (So far three different catalogs have three different sets of declarations.) This would enable some users to set aside the questions till later, while others can learn things like how "<singleton> means there will never be more than one of those properties in that type of control" -- a useful thing to know.

Carving out the declarations model could also allow a more streamlined approach to the rest of it?

@akarmel
Copy link
Contributor Author

akarmel commented Mar 1, 2018

Sprint 8 Progress Notes

  • See above comment
  • Per David, we should not focus on the declarations piece but rather talk about everything else
  • Karen: Tomorrow (3/2) is blocked off to work on documentation and will continue on Monday.
  • Karen and David will talk tomorrow (3/2)

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 2, 2018 •
edited
Loading

I have expanded the initial OSCAL control page for users to cover OSCAL catalogs more broadly, while omitting the declarations piece. The page is in the docs branch at https://github.com/usnistgov/OSCAL/blob/docs/docs/prose/control.md. There are a few items I've marked with TBD where I wasn't sure what to say. I've asked Dave and Wendell to review the page and provide feedback.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 2, 2018

I have put together a partial page for tool and catalog creators and maintainers based on the old IMPLEMENTERS.MD page. The new page, formatted for conversion to pages.nist.gov, is in the docs branch at https://github.com/usnistgov/OSCAL/blob/docs/docs/prose/implementers.md. I will continue working on it, but feedback is welcome at any time.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 5, 2018

Based on Dave and Wendell's recommendations, I've split the catalog documentation into three pieces. The neutral content (overview of catalogs and controls) is at https://github.com/usnistgov/OSCAL/blob/docs/docs/prose/catalog.md. This material does not include any XML or JSON. I have started a detailed page for XML representation of catalogs at https://github.com/usnistgov/OSCAL/blob/docs/docs/prose/catalog-xml.md and asked Dave to review the work so far to confirm the direction is good. I will finish the XML draft for this sprint and will do a similar JSON draft in a future sprint.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 6, 2018

The documentation files have been moved to the slate branch (thanks Andrew!) and I am currently working on refining them. Most of the catalog XML schema has been documented at a high level; more detail and some polishing is needed.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 8, 2018

I have completed a first full draft of the catalog documentation. There is neutral, high-level documentation (not particular to XML or JSON), and also specific documentation for XML and JSON. I have XML examples. I do not yet have JSON examples, but adding them would only take a few minutes.

@akarmel
Copy link
Contributor Author

akarmel commented Mar 8, 2018

Sprint 8 Acceptance

  • Documentation addresses the scope of this user story
  • User Story complete

@akarmel akarmel closed this as completed Mar 8, 2018
david-waltermire added a commit that referenced this issue Apr 3, 2018
@david-waltermire
# This is a combination of 29 commits.
5b13d9d 
# The first commit's message is:

# This is a combination of 54 commits.
# The first commit's message is:

# This is a combination of 4 commits.
# The first commit's message is:

# This is a combination of 2 commits.
# The first commit's message is:

# This is a combination of 2 commits.
# The first commit's message is:

# This is a combination of 6 commits.
# The first commit's message is:

# This is a combination of 3 commits.
# The first commit's message is:

# This is a combination of 111 commits.
# The first commit's message is:

Initial commit of docs branch.

# This is the commit message #2:

Create CONTRIBUTING.md
# This is the commit message #3:

Create ROADMAP.md
# This is the commit message #4:

Update README.md
# This is the commit message #5:

Create README.md
# This is the commit message #6:

Update README.md
# This is the commit message #7:

Update README.md
# This is the commit message #8:

Create OSCAL-PRODUCERS.md
# This is the commit message #9:

Create OSCAL-CONSUMERS.md
# This is the commit message #10:

Update and rename OSCAL-CONSUMERS.md to USERS.md
# This is the commit message #11:

Update and rename OSCAL-PRODUCERS.md to IMPLEMENTERS.md
# This is the commit message #12:

Rename CONTRIBUTING.md to CONTRIBUTORS.md
# This is the commit message #13:

Update README.md
# This is the commit message #14:

Update README.md
# This is the commit message #15:

Update USERS.md
# This is the commit message #16:

Update README.md
# This is the commit message #17:

Update IMPLEMENTERS.md
# This is the commit message #18:

Update README.md
# This is the commit message #19:

Update ROADMAP.md
# This is the commit message #20:

Update USERS.md
# This is the commit message #21:

Update CONTRIBUTORS.md
# This is the commit message #22:

Update README.md
# This is the commit message #23:

Update README.md
# This is the commit message #24:

Update IMPLEMENTERS.md
# This is the commit message #25:

Update IMPLEMENTERS.md
# This is the commit message #26:

Rename CONTRIBUTORS.md to CONTRIBUTING.md
# This is the commit message #27:

Create control.md
# This is the commit message #28:

Update control.md
# This is the commit message #29:

Update control.md
# This is the commit message #30:

Update control.md
# This is the commit message #31:

Update control.md
# This is the commit message #32:

Add files via upload
# This is the commit message #33:

Update control.md
# This is the commit message #34:

Create temp.md
# This is the commit message #35:

Delete NIST-SP-800-53-Rev4-AC1.png
# This is the commit message #36:

Add files via upload
# This is the commit message #37:

Delete temp.md
# This is the commit message #38:

Add files via upload
# This is the commit message #39:

Update control.md
# This is the commit message #40:

Add files via upload
# This is the commit message #41:

Add files via upload
# This is the commit message #42:

Update control.md
# This is the commit message #43:

Update CONTRIBUTING.md
# This is the commit message #44:

Update CONTRIBUTING.md
# This is the commit message #45:

Update USERS.md
# This is the commit message #46:

Update CONTRIBUTING.md
# This is the commit message #47:

Delete CONTRIBUTING.md
# This is the commit message #48:

Delete USERS.md
# This is the commit message #49:

Add files via upload
# This is the commit message #50:

Delete CSA-CCM-IAM02.png
# This is the commit message #51:

Update control.md
# This is the commit message #52:

Update control.md
# This is the commit message #53:

Update control.md
# This is the commit message #54:

Update control.md
# This is the commit message #55:

Update control.md
# This is the commit message #56:

Update control.md
# This is the commit message #57:

Update control.md
# This is the commit message #58:

Update control.md
# This is the commit message #59:

Update control.md
# This is the commit message #60:

Update control.md
# This is the commit message #61:

Delete NIST-SP-800-53-AC1-in-OSCAL-XML.png
# This is the commit message #62:

Update README.md
# This is the commit message #63:

Update control.md
# This is the commit message #64:

Update control.md
# This is the commit message #65:

Add files via upload
# This is the commit message #66:

Delete ISO-27001-Control-A9.png
# This is the commit message #67:

Update control.md
# This is the commit message #68:

Add files via upload
# This is the commit message #69:

Add files via upload
# This is the commit message #70:

Delete ISO-27002-Control-9.1.1-part1.png
# This is the commit message #71:

Delete ISO-27002-Control-9.1.1-part2.png
# This is the commit message #72:

Update control.md
# This is the commit message #73:

Update control.md
# This is the commit message #74:

Update control.md
# This is the commit message #75:

Update control.md
# This is the commit message #76:

Update control.md
# This is the commit message #77:

Update README.md
# This is the commit message #78:

Update IMPLEMENTERS.md
# This is the commit message #79:

Add files via upload
# This is the commit message #80:

Delete oscal-layers.png
# This is the commit message #81:

Add files via upload
# This is the commit message #82:

Delete oscal-layers.png
# This is the commit message #83:

Add files via upload
# This is the commit message #84:

Update IMPLEMENTERS.md
# This is the commit message #85:

Update control.md
# This is the commit message #86:

Update IMPLEMENTERS.md
# This is the commit message #87:

Update control.md
# This is the commit message #88:

Rename IMPLEMENTERS.md to docs/prose/IMPLEMENTERS.md
# This is the commit message #89:

Rename IMPLEMENTERS.md to implementers.md
# This is the commit message #90:

Rearranged and outlined catalog documentation based on the conversation with karen and Wendell.

# This is the commit message #91:

Create catalog-xml.md
# This is the commit message #92:

Rename control.md to catalog.md
# This is the commit message #93:

Update catalog.md
# This is the commit message #94:

Update catalog.md
# This is the commit message #95:

Update catalog.md
# This is the commit message #96:

Update catalog-xml.md
# This is the commit message #97:

Update catalog-xml.md
# This is the commit message #98:

Update catalog-xml.md
# This is the commit message #99:

Update catalog-xml.md
# This is the commit message #100:

Update catalog-xml.md
# This is the commit message #101:

Update catalog-xml.md
# This is the commit message #102:

Update catalog-xml.md
# This is the commit message #103:

Update catalog-xml.md
# This is the commit message #104:

Update catalog-xml.md
# This is the commit message #105:

Update catalog-xml.md
# This is the commit message #106:

Docset migration to Slate

# This is the commit message #107:

Removing unused file.

# This is the commit message #108:

Update README.md

Corrected a typo
# This is the commit message #109:

Add files via upload

Graphical representation of OSCAL schemas aligned with Risk Management Framework steps and tasks.
# This is the commit message #110:

Create CONTRIBUTING.md
# This is the commit message #111:

Create ROADMAP.md
# This is the commit message #2:

Create README.md
# This is the commit message #3:

Update README.md
# This is the commit message #2:

Create OSCAL-PRODUCERS.md
# This is the commit message #3:

Create OSCAL-CONSUMERS.md
# This is the commit message #4:

Update and rename OSCAL-CONSUMERS.md to USERS.md
# This is the commit message #5:

Update and rename OSCAL-PRODUCERS.md to IMPLEMENTERS.md
# This is the commit message #6:

Rename CONTRIBUTING.md to CONTRIBUTORS.md
# This is the commit message #2:

Update USERS.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #2:

Update ROADMAP.md
# This is the commit message #3:

Update USERS.md
# This is the commit message #4:

Update CONTRIBUTORS.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #3:

Update IMPLEMENTERS.md
# This is the commit message #4:

Rename CONTRIBUTORS.md to CONTRIBUTING.md
# This is the commit message #5:

Create control.md
# This is the commit message #6:

Update control.md
# This is the commit message #7:

Update control.md
# This is the commit message #8:

Update control.md
# This is the commit message #9:

Update control.md
# This is the commit message #10:

Add files via upload
# This is the commit message #11:

Update control.md
# This is the commit message #12:

Create temp.md
# This is the commit message #13:

Delete NIST-SP-800-53-Rev4-AC1.png
# This is the commit message #14:

Add files via upload
# This is the commit message #15:

Delete temp.md
# This is the commit message #16:

Add files via upload
# This is the commit message #17:

Update control.md
# This is the commit message #18:

Add files via upload
# This is the commit message #19:

Add files via upload
# This is the commit message #20:

Update control.md
# This is the commit message #21:

Update CONTRIBUTING.md
# This is the commit message #22:

Update CONTRIBUTING.md
# This is the commit message #23:

Update USERS.md
# This is the commit message #24:

Update CONTRIBUTING.md
# This is the commit message #25:

Delete CONTRIBUTING.md
# This is the commit message #26:

Delete USERS.md
# This is the commit message #27:

Add files via upload
# This is the commit message #28:

Delete CSA-CCM-IAM02.png
# This is the commit message #29:

Update control.md
# This is the commit message #30:

Update control.md
# This is the commit message #31:

Update control.md
# This is the commit message #32:

Update control.md
# This is the commit message #33:

Update control.md
# This is the commit message #34:

Update control.md
# This is the commit message #35:

Update control.md
# This is the commit message #36:

Update control.md
# This is the commit message #37:

Update control.md
# This is the commit message #38:

Update control.md
# This is the commit message #39:

Delete NIST-SP-800-53-AC1-in-OSCAL-XML.png
# This is the commit message #40:

Update README.md
# This is the commit message #41:

Update control.md
# This is the commit message #42:

Update control.md
# This is the commit message #43:

Add files via upload
# This is the commit message #44:

Delete ISO-27001-Control-A9.png
# This is the commit message #45:

Update control.md
# This is the commit message #46:

Add files via upload
# This is the commit message #47:

Add files via upload
# This is the commit message #48:

Delete ISO-27002-Control-9.1.1-part1.png
# This is the commit message #49:

Delete ISO-27002-Control-9.1.1-part2.png
# This is the commit message #50:

Update control.md
# This is the commit message #51:

Update control.md
# This is the commit message #52:

Update control.md
# This is the commit message #53:

Update control.md
# This is the commit message #54:

Update control.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #3:

Add files via upload
# This is the commit message #4:

Delete oscal-layers.png
# This is the commit message #5:

Add files via upload
# This is the commit message #6:

Delete oscal-layers.png
# This is the commit message #7:

Add files via upload
# This is the commit message #8:

Update IMPLEMENTERS.md
# This is the commit message #9:

Update control.md
# This is the commit message #10:

Update IMPLEMENTERS.md
# This is the commit message #11:

Update control.md
# This is the commit message #12:

Rename IMPLEMENTERS.md to docs/prose/IMPLEMENTERS.md
# This is the commit message #13:

Rename IMPLEMENTERS.md to implementers.md
# This is the commit message #14:

Rearranged and outlined catalog documentation based on the conversation with karen and Wendell.

# This is the commit message #15:

Create catalog-xml.md
# This is the commit message #16:

Rename control.md to catalog.md
# This is the commit message #17:

Update catalog.md
# This is the commit message #18:

Update catalog.md
# This is the commit message #19:

Update catalog.md
# This is the commit message #20:

Update catalog-xml.md
# This is the commit message #21:

Update catalog-xml.md
# This is the commit message #22:

Update catalog-xml.md
# This is the commit message #23:

Update catalog-xml.md
# This is the commit message #24:

Update catalog-xml.md
# This is the commit message #25:

Update catalog-xml.md
# This is the commit message #26:

Update catalog-xml.md
# This is the commit message #27:

Update catalog-xml.md
# This is the commit message #28:

Update catalog-xml.md
# This is the commit message #29:

Fixed typos, updated repo documentation, and migrated documentation for use in Slate.

Corrected a typo (+4 squashed commit)

Squashed commit:

[6ada57f] Removing unused file.

[503ad71] Docset migration to Slate

[351257e] Update catalog-xml.md

[aae1e8b] Add files via upload

Graphical representation of OSCAL schemas aligned with Risk Management Framework steps and tasks.
@david-waltermire david-waltermire added this to the OSCAL 1.0 M1 milestone Apr 6, 2018
@aj-stein-nist aj-stein-nist mentioned this issue Jun 8, 2022
Closed
7 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@wendellpiez wendellpiez

@david-waltermire david-waltermire

@kscarf1 kscarf1

Labels
LoE: Medium User Story
Projects
None yet
Milestone
OSCAL 1.0 Milestone 1
Development

No branches or pull requests
5 participants
@wendellpiez @david-waltermire @kscarfone @akarmel @kscarf1