1---
  2layout: page
  3title: Gemara Schemas
  4nav-title: Schema
  5---
  6
  7Schemas (CUE format) standardize the expression of elements in the model and enable automated interoperability between GRC tools. These schemas provide validation across all layers.
  8
  9Click on an artifact to view its schema:
 10
 11<div class="layer-grid">
 12  <a href="guidancecatalog.html" class="layer-card">
 13    <span class="layer-badge">Layer 1</span>
 14    <h3>Guidance Catalog</h3>
 15    <p>High-level guidance on cybersecurity measures from industry groups and standards bodies.</p>
 16  </a>
 17
 18  <a href="vectorcatalog.html" class="layer-card">
 19    <span class="layer-badge">Layer 1</span>
 20    <h3>Vector Catalog</h3>
 21    <p>Attack vectors and techniques used to compromise information systems.</p>
 22  </a>
 23
 24  <a href="principlecatalog.html" class="layer-card">
 25    <span class="layer-badge">Layer 1</span>
 26    <h3>Principle Catalog</h3>
 27    <p>Foundational values that guide governance, design, and operational decisions.</p>
 28  </a>
 29
 30  <a href="controlcatalog.html" class="layer-card">
 31    <span class="layer-badge">Layer 2</span>
 32    <h3>Control Catalog</h3>
 33    <p>Technology-specific, threat-informed security controls for protecting information systems.</p>
 34  </a>
 35
 36  <a href="capabilitycatalog.html" class="layer-card">
 37    <span class="layer-badge">Layer 2</span>
 38    <h3>Capability Catalog</h3>
 39    <p>Technology capabilities that can be leveraged to implement security controls.</p>
 40  </a>
 41
 42  <a href="threatcatalog.html" class="layer-card">
 43    <span class="layer-badge">Layer 2</span>
 44    <h3>Threat Catalog</h3>
 45    <p>Threats mapped to technology capabilities and security controls.</p>
 46  </a>
 47
 48  <a href="riskcatalog.html" class="layer-card">
 49    <span class="layer-badge">Layer 3</span>
 50    <h3>Risk Catalog</h3>
 51    <p>Organizational risk categories, severity levels, and risk appetite definitions.</p>
 52  </a>
 53
 54  <a href="policy.html" class="layer-card">
 55    <span class="layer-badge">Layer 3</span>
 56    <h3>Policy</h3>
 57    <p>Risk-informed guidance tailored to your organization's specific needs and risk appetite.</p>
 58  </a>
 59
 60  <a href="evaluationlog.html" class="layer-card">
 61    <span class="layer-badge">Layer 5</span>
 62    <h3>Evaluation Log</h3>
 63    <p>Inspection of code, configurations, and deployments against policies and controls.</p>
 64  </a>
 65
 66  <a href="enforcementlog.html" class="layer-card">
 67    <span class="layer-badge">Layer 6</span>
 68    <h3>Enforcement Log</h3>
 69    <p>Prevention or remediation based on assessment findings.</p>
 70  </a>
 71
 72  <a href="auditlog.html" class="layer-card">
 73    <span class="layer-badge">Layer 7</span>
 74    <h3>Audit Log</h3>
 75    <p>Review of organizational policy and conformance.</p>
 76  </a>
 77</div>
 78
 79**[Browse all schemas in the CUE Central Registry →](https://registry.cue.works/docs/github.com/gemaraproj/gemara@latest)**
 80
 81## Schema Documentation
 82
 83Schema documentation generated from CUE. One page per schema file:
 84
 85<!-- SCHEMA_LIST_START -->
 86
 87- [Aliases & Base Types](base.html)
 88- [Metadata](metadata.html)
 89- [Mapping Primitives](mapping-inline.html)
 90- [Guidance Catalog](guidancecatalog.html)
 91- [Vector Catalog](vectorcatalog.html)
 92- [Principle Catalog](principlecatalog.html)
 93- [Control Catalog](controlcatalog.html)
 94- [Capability Catalog](capabilitycatalog.html)
 95- [Threat Catalog](threatcatalog.html)
 96- [Risk Catalog](riskcatalog.html)
 97- [Policy](policy.html)
 98- [Mapping Document](mappingdocument.html)
 99- [Lexicon](lexicon.html)
100- [Evaluation Log](evaluationlog.html)
101- [Enforcement Log](enforcementlog.html)
102- [Audit Log](auditlog.html)
103
104<!-- SCHEMA_LIST_END -->
105
106### Validation with CUE
107
108```bash
109# Install CUE
110go install cuelang.org/go/cmd/cue@latest
111
112# Validate a control catalog using the ControlCatalog definition
113cue vet -c -d '#ControlCatalog' github.com/gemaraproj/gemara@latest your-controls.yaml
114```
115
116## Architecture Decisions
117
118Significant implementation changes are documented in [Architecture Decision Records (ADRs)](../adrs/index.html).
119
120## Schema Standards
121
122Schemas follow these naming standards:
123
124| Layer | Category    | Atomic Unit (Interactive) | Atomic Unit (Defensive) | Collection (Interactive) | Collection (Defensive) |
125|:------|:------------|:--------------------------|:------------------------|:-------------------------|:-----------------------|
126| 1     | Definition  | Vector                    | Guidance                | Vector Catalog           | Guidance Catalog       |
127| 2     | Definition  | Threat                    | Control                 | Threat Catalog           | Control Catalog        |
128| 3     | Definition  | Risk                      | Policy                  | Risk Catalog             | —                      |
129| 4     | —           | —                         | —                       | —                        | —                      |
130| 5     | Measurement | Control Evaluation        | Control Evaluation      | Evaluation Log           | Evaluation Log         |
131| 6     | Measurement | Action Result             | Action Result           | Enforcement Log          | Enforcement Log        |
132| 7     | Measurement | —                         | Audit Result            | —                        | Audit Log              |
133
134**Note:** "—" indicates no planned schema implementation.
135
136**Naming conventions**:
137- **Definition layers (1-3)**: Collections of atomic units are called **Catalogs**
138- **Measurement layers (5-7)**: Collections of atomic units are called **Logs**
139
140## Versioning and Maintenance
141
142Project release deliverables are divided into the **Core Specification** and language-specific **SDKs**.
143
144* **Core Specification Release:** The CUE schemas are versioned and released as the core specification. These schemas implement the Model, which is published separately.
145* **SDK Releases:** Language-specific implementations that provide tooling, types, and helpers to work with Gemara documents. SDK types are generated from the CUE schemas.
146
147Each **maintains its own** independent [SemVer](https://semver.org/) lifecycle.
148
149### Specification Release Versioning
150
151The core specification release versions the CUE schemas as a single unit.
152
153| Change Type | Version Bump | Examples                                                     |
154|:------------|:-------------|:-------------------------------------------------------------|
155| Major       | v2.0.0       | Breaking changes to Stable schemas.                         |
156| Minor       | v1.(x+1).0   | Additive changes, schema promotions, or new optional fields. |
157| Patch       | v1.x.(y+1)   | Bug fixes in schema logic or documentation.                  |
158
159### Schema Lifecycle and Major Version Example
160
161Possible schema states include: **Experimental** → **Stable** → **Deprecated**. These are denoted on each schema file with a `@status(experimental|stable|deprecated)` attribute.
162
163The following table illustrates how schemas progress through their lifecycle and how major version changes are handled:
164
165| Version | Status              | Change Type | Example Scenario                        |
166|:--------|:--------------------|:------------|:----------------------------------------|
167| v1.0.0  | Experimental        | Initial     | Schema first published                  |
168| v1.1.0  | Experimental        | Minor       | Optional fields added                   |
169| v1.2.0  | Stable              | Minor       | Promoted to Stable                      |
170| v1.3.0  | Stable              | Minor       | Additive changes                        |
171| v1.3.1  | Stable              | Patch       | Bug fix                                 |
172| v1.4.0  | Stable              | Minor       | Field deprecated, replacement added     |
173| v1.5.0  | Stable → Deprecated | Minor       | Original deprecated, replacement Stable |
174| v2.0.0  | Stable              | Major       | Deprecated schema removed               |
175| v2.1.0  | Stable              | Minor       | Additive changes                        |
176
177### Experimental Status
178* All new schemas start as Experimental.
179* Adding Experimental schemas or making breaking changes triggers minor version increments.
180* Breaking changes and performance issues may occur during this phase.
181* These schemas may not be feature-complete.
182
183### Stable Status
184
185* Schemas promote independently and at different times (e.g., ControlCatalog can be Stable while Policy remains Experimental).
186* When a schema is promoted to Stable, all types it references must also be Stable (e.g., promoting `#ControlCatalog` requires `#Catalog`, `#Metadata`, `#Group`, and any other referenced types to already be Stable).
187* Stable schemas may only reference other Stable types.
188* Stable schemas maintain backward and forward compatibility within major versions, allowing **additive optional changes** only.
189* Breaking changes require major version increments and should be avoided in all normal circumstances.
190
191### Deprecated Status
192
193* Schemas or fields within schemas may be deprecated when replaced.
194* Replacement schema or field must be added in Experimental status and promoted to Stable before deprecation.
195* Deprecated schemas and fields maintain the same support guarantees as Stable schemas and remain functional.
196* Deprecated schemas are removed in the next major version release.
197
198## Contributing
199
200The Schemas evolve based on community needs. If you find an error or have suggestions for a schema improvement, open a [GitHub Issue](https://github.com/gemaraproj/gemara/issues) or raise your suggestion on a [community](/community) meeting.
201
202See the [Contributing Guide](https://github.com/gemaraproj/gemara/blob/main/CONTRIBUTING.md) for details.
203
204## Relationship to Other Components
205
206### [The Model](../model)
207The Model is published separately and provides the conceptual foundation. These CUE schemas are an implementation of the model, with each schema corresponding to a layer in the model.
208
209### [The SDKs](../sdk/)
210SDKs support programmatic access to Gemara documents. SDK types are generated from these schemas, ensuring consistency between validation and programmatic access.
211
212## Questions or Feedback
213
214For questions about versioning strategy or to propose changes:
215
216* Open an issue on [GitHub](https://github.com/gemaraproj/gemara/issues)
217* Discuss in the [OpenSSF Slack #gemara channel](https://openssf.slack.com/archives/C09A9PP765Q)
218* Attend the [biweekly Gemara meeting](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ)