Specification Overview

The CSE specification defines the data formats, schemas, and validation rules for all CSE data types. This ensures consistency and interoperability across implementations.

Specification Documents

The CSE specification is organized into four primary format specifications, each defining a core data type:

Design Principles

The CSE specification is guided by several key principles that inform all design decisions:

1. Stability

Signal IDs are permanent identifiers that never change. Once a signal is published, its ID remains valid indefinitely. This enables long-term citation and reliable cross-system references.

2. Neutrality

CSE is descriptive, not prescriptive. Signals describe observable conditions without asserting compliance status, severity judgments, or remediation requirements. These assessments remain contextual and are left to implementers.

3. Interoperability

All CSE formats use JSON with well-defined schemas. This ensures data can be validated, parsed, and exchanged between any tools or platforms that implement the specification.

4. Extensibility

The specification includes extension mechanisms that allow implementers to add custom fields without breaking compatibility. Core fields are standardized while additional context can be included as needed.

5. Human Readability

Signal IDs and data structures are designed to be meaningful to humans, not just machines. IDs encode domain and category information, and descriptions use clear, non-technical language where possible.

Schema Validation

All CSE data types have corresponding JSON Schema definitions that enable automated validation. These schemas are published in the GitHub repository and can be used with any JSON Schema-compatible validator.

Available Schemas

Validation Example

# Using ajv-cli to validate a signal
npm install -g ajv-cli

# Download the schema
curl -O https://raw.githubusercontent.com/cse-registry/cse-registry/main/schemas/signal.schema.json

# Validate a signal file
ajv validate -s signal.schema.json -d my-signal.json

# Output on success
my-signal.json valid

Versioning

The CSE specification uses semantic versioning (SemVer) to communicate changes:

Compliance Levels

Implementations can achieve different levels of CSE compliance based on which parts of the specification they support:

Extension Mechanism

CSE supports extensions through a standardized mechanism that preserves compatibility:

{
  "id": "CSE-HIPAA-TECH-ENCRYPT-REST-001",
  "domain": "HIPAA",
  "category": "TECH",
  "title": "Data at Rest Encryption Not Enabled",
  // ... standard fields ...

  "extensions": {
    "x-vendor-tool": {
      "internal_id": "ENC-001",
      "priority": "critical",
      "auto_remediate": true
    },
    "x-organization": {
      "owner_team": "platform-security",
      "sla_hours": 24
    }
  }
}

Extension namespaces should be prefixed with x- to indicate non-standard fields. Consumers that don't recognize an extension should ignore it while preserving it during data transformations.

Next Steps

Dive into the specific format specifications to understand each data type in detail: