feat: add JSON Schema definitions for programmatic access

[edonadei]

Summary

This PR establishes the foundational data structure contract for SAFE-MCP by adding comprehensive JSON Schema (Draft 7) definitions for techniques, mitigations, and tactics. These schemas enable programmatic access, validation, and automated tooling integration.

This is Part 1 of a multi-PR initiative to address issue #48.

Type of Contribution

• Documentation improvement
• Infrastructure/Tooling

What's Included

Schema Definitions (~1k lines total)

1. schemas/technique-schema.json (~500 lines)

   • Comprehensive schema for attack techniques
   • Includes: metadata, attack vectors, impact assessment, detection methods, mitigations, MITRE ATT&CK mappings, version history
   • ID pattern: ^SAFE-T[0-9]{4}(\.[0-9]{3})?$

2. schemas/mitigation-schema.json (~400 lines)

   • Complete schema for security controls
   • Includes: metadata, implementation details, benefits/limitations, deployment considerations, testing requirements
   • ID pattern: ^SAFE-M-[0-9]+$

3. schemas/tactic-schema.json (~50 lines)

   • Schema for MITRE ATT&CK-aligned tactics
   • ID pattern: ^ATK-TA[0-9]{4}$

Key Features

• Required fields enforce core metadata presence
• Enum values provide controlled vocabularies for consistency
• Pattern matching validates ID formats
• Extensible design allows future additions without breaking changes
• JSON Schema Draft 7 standard compliance

Benefits

This establishes a contract that enables:

• Automated tooling integration (dashboards, SIEM systems)
• Programmatic data access via scripts and APIs
• Data validation and consistency checking
• Type-safe development for integrations

Multi-PR Roadmap

• feat: add JSON Schema definitions for programmatic access #100 (this): Schema definitions
• feat: Add Markdown parser and CI validation workflow #101: Markdown parser + CI automation (GitHub Actions)
• Not yet: TOON token-efficient format generator for LLM optimization
• Not yet: Documentation and README updates

Checklist

• DCO sign-off included in commits (git commit -s)
• Schemas follow JSON Schema Draft 7 specification
• ID patterns match existing SAFE-MCP naming conventions
• All required fields identified from markdown templates
• Extensibility considered for future enhancements

Related Issues

Related: #48 - Create JSON/YAML index of SAFE-MCP techniques

Testing

The schemas can be validated against tools like:

# Using online validators
https://www.jsonschemavalidator.net/

# Or CLI tools (will be automated in PR #2)
pip install jsonschema
python -c "import jsonschema; print('Schemas are valid JSON Schema Draft 7')"

[edonadei]

@fkautz @bochristopher PTAL, as discussed during the last safe-mcp community meeting, I decided to give it a try. The big idea would be:

Markdown as source of truth --> JSON schema --> "compiled" in TOON format for efficient LLM retrieval

I've gone that direction because it seems like contributors enjoy the ability to work with Markdown and being opened to contributing in this format. It's a suggestion though, and I'm open to other ideas, we could actually do the opposite, where the contributors would contribute in JSON (or YAML).

JSON as source of Truth --> JSON schema --> Markdown compiled
YAML as source of Truth --> JSON schema --> Markdown compiled