Skip to content

docs: establishing lexicon of terms #196

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
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: establishing lexicon of terms #196

wants to merge 2 commits into from
+64 −0

Conversation

@hbraswelrh
Copy link
Contributor

@hbraswelrh hbraswelrh commented Nov 25, 2025 •
edited
Loading

Description

This PR defines a lexicon of terms for gemara. The definitions should be referenced when using the terms to describe the gemara project. The content was adapted from the provided material on issue #189

The "Do Not Use" column is for banned synonyms. Words in the "Do Not Use" column should never be used as synonyms for the associated terms.

Schema Changes

Schema Changes Made

  • No schema changes
  • Layer 1 schema (schemas/layer-1.cue) changes
  • Layer 2 schema (schemas/layer-2.cue) changes
  • Layer 3 schema (schemas/layer-3.cue) changes
  • Layer 4 schema (schemas/layer-4.cue) changes

Schema Change Details

Testing

  • Unit tests added/updated
  • Manual testing performed - gitleaks
  • Test data updated (if applicable)

Related Issues

Reviewer Hints

  • Review the Do Not Use column.
  • Existing terms were suggested on the related issue comment.
  • Term refinement and context is a WIP.

Note: The layout of the lexicon could potentially benefit from grouping terms by category (e.g. regulations, layer-specific terms) for easy access.

@hbraswelrh
docs: initial lexicon outline
da2f50c 
Signed-off-by: Hannah Braswell <[email protected]>
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Nov 25, 2025
@hbraswelrh
Copy link
Contributor Author

hbraswelrh commented Dec 2, 2025

@jpower432 @eddie-knight Any thoughts on including the gemara layers in the lexicon.md? Since the lexicon will be tightly maintained it may be useful to users wanting the project-specific context consolidated as one file. Then, the layers would be defined in the README.md and in the comprehensive lexicon.md.

@jpower432
Copy link
Contributor

jpower432 commented Dec 3, 2025

@jpower432 @eddie-knight Any thoughts on including the gemara layers in the lexicon.md? Since the lexicon will be tightly maintained it may be useful to users wanting the project-specific context consolidated as one file. Then, the layers would be defined in the README.md and in the comprehensive lexicon.md.

@hbraswelrh Do you mean defining terms like Guidance, Control, Policy? If so, I think we need those in the lexicon.

@hbraswelrh
Copy link
Contributor Author

hbraswelrh commented Dec 3, 2025

@jpower432 @eddie-knight Any thoughts on including the gemara layers in the lexicon.md? Since the lexicon will be tightly maintained it may be useful to users wanting the project-specific context consolidated as one file. Then, the layers would be defined in the README.md and in the comprehensive lexicon.md.

@hbraswelrh Do you mean defining terms like Guidance, Control, Policy? If so, I think we need those in the lexicon.

I meant more-so having "Gemara Layer 1, 2, etc.," but I guess having the Guidance, Control, and Policy distinctions are the same thing. I'll just keep it as those. Thanks!

@hbraswelrh hbraswelrh marked this pull request as ready for review December 3, 2025 18:04
@hbraswelrh hbraswelrh requested a review from a team as a code owner December 3, 2025 18:04
@jpower432 jpower432 changed the title docs: establishing lexicon of terms WIP docs: establishing lexicon of terms Dec 3, 2025
@jpower432 jpower432 linked an issue Dec 3, 2025 that may be closed by this pull request
Define a project lexicon of GRC terms #189
Open
11 tasks
@hbraswelrh
Copy link
Contributor Author

hbraswelrh commented Dec 4, 2025

@eddie-knight the last column is the "Do Not Use" column for words that shouldn't be used to interchangeably with the term. It essentially acts as banned synonyms specific to the project to reduce confusion and misuse.

@hbraswelrh hbraswelrh mentioned this pull request Dec 4, 2025
Draft
8 tasks
jpower432
jpower432 reviewed Dec 4, 2025
View reviewed changes
lexicon.md
| **Continuous ATO** | A modern approach to authorization where the Authority To Operate is maintained through continuous monitoring, automated assessments, and real-time risk data, rather than through static, point-in-time audits. | | |
| **Gemara** | Open source logical model to describe the categories of compliance activities, how they interact, and the associated schemas to enable automated interoperability between them. Governed by the Open Source Security Foundation under an Apache 2 license. | Layers 1-6 | |
| **OSCAL** | The Open Security Controls Assessment Language. A set of standardized, machine-readable formats (XML, JSON, YAML) for expressing and exchanging security control and assessment information, developed and governed by the United States' National Institute of Standards and Technology (NIST). | | |
| **OSCAL Compass** | Open source toolkit that enables the creation, validation, and governance of compliance artifacts. It leverages NIST's OSCAL as a standard data format and provides an OSCAL SDK. Governed by the Cloud Native Computing Foundation under an Apache 2 license. | | |
Copy link
Contributor

@jpower432 jpower432 Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| **OSCAL Compass** | Open source toolkit that enables the creation, validation, and governance of compliance artifacts. It leverages NIST's OSCAL as a standard data format and provides an OSCAL SDK. Governed by the Cloud Native Computing Foundation under an Apache 2 license. | | |

Copy link
Contributor

@jpower432 jpower432 Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking the lexicon should focus on compliance, governance, and security terms used throughout the README.md and schemas vs specific frameworks and tools. I would suggest definitions like this be removed. WDYT?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jpower432 jpower432 jpower432 left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Define a project lexicon of GRC terms

2 participants

@hbraswelrh @jpower432