Schemas (CUE format) standardize the expression of elements in the model and enable automated interoperability between GRC tools. These schemas provide validation across all layers.

Click on a layer to view its schema:

Layer 1: Guidance

High-level guidance on cybersecurity measures from industry groups and standards bodies.

Layer 2: Controls

Technology-specific, threat-informed security controls for protecting information systems.

Layer 3: Policy

Risk-informed guidance tailored to your organization's specific needs and risk appetite.

Layer 5: Evaluation

Inspection of code, configurations, and deployments against policies and controls.

Layer 6: Enforcement

Prevention or remediation based on assessment findings. (Coming Soon)

Layer 7: Audit

Review of organizational policy and conformance. (Coming Soon)

Browse all schemas in the CUE Central Registry →

Schema Documentation

Schema documentation generated from CUE. One page per schema file:

Validation with CUE

# Install CUE
go install cuelang.org/go/cmd/cue@latest

# Validate a control catalog using the Layer 2 ControlCatalog definition
cue vet -c -d '#ControlCatalog' github.com/gemaraproj/gemara@latest your-controls.yaml

Architecture Decisions

Significant implementation changes are documented in Architecture Decision Records (ADRs).

Schema Standards

Schemas follow these naming standards:

Layer Category Atomic Unit (Interactive) Atomic Unit (Defensive) Collection (Interactive) Collection (Defensive)
1 Definition Vector Guidance Vector Catalog Guidance Catalog
2 Definition Threat Control Threat Catalog Control Catalog
3 Definition Risk Policy Risk Catalog —
4 — — — — —
5 Measurement Evaluation Result Evaluation Result Evaluation Log Evaluation Log
6 Measurement Enforcement Result Enforcement Result Enforcement Log Enforcement Log
7 Measurement — Audit Result — Audit Log

Note: “—” indicates no planned schema implementation.

Naming conventions:

  • Definition layers (1-3): Collections of atomic units are called Catalogs
  • Measurement layers (5-7): Collections of atomic units are called Logs

Versioning and Maintenance

Project release deliverables are divided into the Core Specification and language-specific SDKs.

  • Core Specification Release: The CUE schemas are versioned and released as the core specification. These schemas implement the Model, which is published separately.
  • SDK Releases: Language-specific implementations that provide tooling, types, and helpers to work with Gemara documents. SDK types are generated from the CUE schemas.

Each maintains its own independent SemVer lifecycle.

Specification Release Versioning

The core specification release versions the CUE schemas as a single unit.

Change Type Version Bump Examples
Major v2.0.0 Breaking changes to Stable schemas.
Minor v1.(x+1).0 Additive changes, schema promotions, or new optional fields.
Patch v1.x.(y+1) Bug fixes in schema logic or documentation.

Schema Lifecycle and Major Version Example

Possible schema states include: Experimental → Stable → Deprecated. These are denoted on each layer schema with a @status(experimental|stable|deprecated) attribute.

The following table illustrates how schemas progress through their lifecycle and how major version changes are handled:

Version Status Change Type Example Scenario
v1.0.0 Experimental Initial Schema first published
v1.1.0 Experimental Minor Optional fields added
v1.2.0 Stable Minor Promoted to Stable
v1.3.0 Stable Minor Additive changes
v1.3.1 Stable Patch Bug fix
v1.4.0 Stable Minor Field deprecated, replacement added
v1.5.0 Stable → Deprecated Minor Original deprecated, replacement Stable
v2.0.0 Stable Major Deprecated schema removed
v2.1.0 Stable Minor Additive changes

Experimental Status

  • All new schemas start as Experimental.
  • Adding Experimental schemas or making breaking changes triggers minor version increments.
  • Breaking changes and performance issues may occur during this phase.
  • These schemas may not be feature-complete.

Stable Status

  • Layers promote independently. Each layer only requires its direct dependencies to be Stable (e.g., Layer 2 requires Layer 1, but not Layer 6).
  • Layers can be promoted to Stable at different times. Layer 2 can be Stable while Layer 6 remains Experimental.
  • Stable schemas may only reference other Stable schemas.
  • Stable schemas maintain backward and forward compatibility within major versions, allowing additive optional changes only.
  • Breaking changes require major version increments and should be avoided in all normal circumstances.

Deprecated Status

  • Schemas or fields within schemas may be deprecated when replaced.
  • Replacement schema or field must be added in Experimental status and promoted to Stable before deprecation.
  • Deprecated schemas and fields maintain the same support guarantees as Stable schemas and remain functional.
  • Deprecated schemas are removed in the next major version release.

Contributing

The Schemas evolve based on community needs. If you find an error or have suggestions for a schema improvement, open a GitHub Issue or raise your suggestion on a community meeting.

See the Contributing Guide for details.

Relationship to Other Components

The Model

The 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.

The SDKs

SDKs support programmatic access to Gemara documents. SDK types are generated from these schemas, ensuring consistency between validation and programmatic access.

Questions or Feedback

For questions about versioning strategy or to propose changes: