Skip to content

v0.2.0 Release Notes

Release Date: 2026-03-02

This release introduces the ThreatModel canonical format for multi-diagram threat models with shared metadata and framework mappings, along with JSON Schema generation for validation support.

Highlights

  • ThreatModel canonical format for multi-diagram threat models with shared metadata and framework mappings
  • JSON Schema generation and embedding for validation support

What's New

ThreatModel Format

The new ThreatModel type serves as the canonical format for threat models containing multiple diagram views:

{
  "id": "tm-example",
  "title": "My Threat Model",
  "description": "Description of the threat model",
  "version": "1.0.0",
  "authors": [{"name": "Author", "email": "author@example.com"}],
  "mappings": {
    "mitre_attack": [{"tactic": "Initial Access", "technique": "T1189"}]
  },
  "diagrams": [
    {"type": "dfd", "title": "Data Flow Diagram", ...},
    {"type": "attack-chain", "title": "Attack Chain", ...},
    {"type": "sequence", "title": "Sequence Diagram", ...}
  ]
}

Key benefits:

  • Shared Metadata — Title, description, version, and authors apply to all diagrams
  • Shared Mappings — Framework mappings (MITRE ATT&CK, OWASP, etc.) are defined once and inherited by all diagrams
  • Single File — One JSON file contains all diagram views for a threat model

JSON Schema

JSON Schemas are now generated from Go types and embedded in the schema package:

Schema Description
threat-model.schema.json ThreatModel format (multi-diagram)
diagram.schema.json DiagramIR format (single diagram)

Access schemas programmatically:

import "github.com/grokify/threat-model-spec/schema"

threatModelSchema := schema.ThreatModelSchema
diagramSchema := schema.DiagramSchema

Validate with external tools:

ajv validate -s schema/threat-model.schema.json -d model.json

CLI Improvements

The CLI now auto-detects ThreatModel vs DiagramIR format:

# Process ThreatModel (generates separate D2 files per diagram)
tms generate threatmodel.json -o output

# Produces: output_dfd.d2, output_attack-chain.d2, output_sequence.d2

# Validate reports format and diagram count
tms validate threatmodel.json
# Output: threatmodel.json: valid (ThreatModel with 3 diagrams)

Schema Generator

A new cmd/genschema tool generates JSON schemas from Go types:

go build -o genschema ./cmd/genschema
./genschema schema/

Migration Guide

From v0.1.0

If you have separate diagram files (e.g., dfd.json, attack_chain.json), you can:

  1. Keep using DiagramIR — The CLI still supports single-diagram files
  2. Migrate to ThreatModel — Combine diagrams into a unified file with shared metadata

To migrate:

# Old approach (multiple files)
tms generate dfd.json -o dfd.d2
tms generate attack_chain.json -o attack_chain.d2

# New approach (single ThreatModel file)
tms generate threatmodel.json -o output
# Generates: output_dfd.d2, output_attack-chain.d2

OpenClaw Example

The OpenClaw example has been consolidated:

  • Before: examples/openclaw/dfd.json, attack_chain.json, attack_sequence.json
  • After: examples/openclaw/openclaw.json (unified ThreatModel)

Installation

Go Library

go get github.com/grokify/threat-model-spec@v0.2.0

CLI Tool

go install github.com/grokify/threat-model-spec/cmd/tms@v0.2.0

Requirements

  • Go 1.24+
  • D2 v0.6+ (for SVG rendering)