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