---
schema: changelog-schema-v1.0
version: "1.0"
domain: changelog
description: "JSON schema for Keep a Changelog format with version history validation"
created: "2026-01-06"
author: "MarkiTect Schema System"
---

# Changelog Schema v1.0

## Overview

This schema validates CHANGELOG.md files following the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. It enforces:

- Unreleased section presence (required)
- Version section format: `[X.Y.Z] - YYYY-MM-DD`
- Standard change type subsections
- Semantic versioning adherence
- ISO 8601 date formatting

## Purpose

Ensures changelog files maintain consistent structure and formatting across releases, facilitating:
- Automated release note generation
- Version history tracking
- Release validation workflows
- Documentation consistency

## Schema Definition

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Changelog Schema",
  "description": "Validates Keep a Changelog format for project changelogs",

  "x-markitect-metadata": {
    "schema_name": "changelog-schema-v1.0",
    "version": "1.0",
    "domain": "changelog",
    "created": "2026-01-06",
    "author": "MarkiTect Schema System"
  },

  "x-markitect-sections": {
    "[Unreleased]": {
      "classification": "required",
      "heading_level": 2,
      "error_message": "Unreleased section is mandatory for tracking upcoming changes",
      "content_instruction": "Use ## [Unreleased] heading. Section can be empty if no unreleased changes.",
      "alternatives": ["UNRELEASED", "Unreleased"]
    },
    "Added": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "New features added in this release"
    },
    "Changed": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "Changes to existing functionality"
    },
    "Deprecated": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "Features that will be removed in future versions"
    },
    "Removed": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "Features removed in this release"
    },
    "Fixed": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "Bug fixes in this release"
    },
    "Security": {
      "classification": "optional",
      "heading_level": 3,
      "parent_section_pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "content_instruction": "Security fixes and vulnerabilities addressed"
    }
  },

  "x-markitect-content-control": {
    "title": {
      "required_patterns": [
        "^# Changelog$"
      ],
      "content_quality": {
        "min_words": 1,
        "max_words": 1
      },
      "error_message": "Title must be exactly '# Changelog'"
    },
    "introduction": {
      "recommended_patterns": [
        "Keep a Changelog",
        "Semantic Versioning"
      ],
      "content_instruction": "Introduction should reference Keep a Changelog and Semantic Versioning standards"
    },
    "unreleased_section": {
      "required_patterns": [
        "## \\[Unreleased\\]"
      ],
      "content_quality": {
        "min_words": 0
      },
      "error_message": "Unreleased section must use format: ## [Unreleased]"
    },
    "version_section": {
      "required_patterns": [
        "## \\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2}"
      ],
      "content_instruction": "Version sections must follow format: ## [X.Y.Z] - YYYY-MM-DD",
      "error_message": "Version sections must use semantic versioning (X.Y.Z) with ISO 8601 dates (YYYY-MM-DD)"
    },
    "change_types": {
      "recommended_patterns": [
        "### Added",
        "### Changed",
        "### Deprecated",
        "### Removed",
        "### Fixed",
        "### Security"
      ],
      "content_instruction": "Use standard Keep a Changelog change type subsections",
      "error_message": "Change types should be one of: Added, Changed, Deprecated, Removed, Fixed, Security"
    },
    "link_references": {
      "recommended_patterns": [
        "\\[Keep a Changelog\\]\\(https://keepachangelog\\.com",
        "\\[Semantic Versioning\\]\\(https://semver\\.org"
      ],
      "content_instruction": "Include reference links to Keep a Changelog and Semantic Versioning"
    }
  },

  "x-markitect-validation-rules": {
    "version_format": {
      "pattern": "^\\[\\d+\\.\\d+\\.\\d+\\]",
      "description": "Version must follow semantic versioning: [MAJOR.MINOR.PATCH]"
    },
    "date_format": {
      "pattern": "\\d{4}-\\d{2}-\\d{2}",
      "description": "Date must be in ISO 8601 format: YYYY-MM-DD"
    },
    "version_ordering": {
      "rule": "descending",
      "description": "Versions should be listed in descending order (newest first)"
    },
    "unreleased_position": {
      "rule": "first_section",
      "description": "Unreleased section must come before all version sections"
    }
  },

  "properties": {
    "headings": {
      "type": "object",
      "description": "Document heading structure",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Title heading (should be 'Changelog')",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": "^Changelog$"
              }
            }
          },
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "Version sections ([Unreleased] and [X.Y.Z] - YYYY-MM-DD)",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": "^(\\[Unreleased\\]|\\[\\d+\\.\\d+\\.\\d+\\] - \\d{4}-\\d{2}-\\d{2})$"
              }
            }
          },
          "minItems": 1,
          "maxItems": 100
        },
        "level_3": {
          "type": "array",
          "description": "Change type subsections (Added, Changed, etc.)",
          "minItems": 0,
          "maxItems": 500
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "description": "Introduction and change descriptions",
      "minItems": 1,
      "maxItems": 5000
    },
    "lists": {
      "type": "array",
      "description": "Change item lists",
      "minItems": 0,
      "maxItems": 1000
    }
  },
  "required": ["headings", "paragraphs"]
}
```

## Usage Examples

### Valid Changelog Structure

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2026-01-06

### Added
- New feature A
- New feature B

### Fixed
- Bug fix for issue #123
```

### Validation Command

```bash
# Ingest schema
markitect schema-ingest markitect/schemas/changelog-schema-v1.0.md

# Validate changelog
markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md --semantic
```

## Validation Checks

### Required Elements
- ✅ Title: Must be "# Changelog"
- ✅ Unreleased section: `## [Unreleased]` must be present
- ✅ Version format: `## [X.Y.Z] - YYYY-MM-DD` for all releases

### Recommended Elements
- ⭐ Introduction paragraph referencing Keep a Changelog
- ⭐ Semantic Versioning reference
- ⭐ At least one change type subsection per version

### Content Patterns
- Version sections use semantic versioning (MAJOR.MINOR.PATCH)
- Dates in ISO 8601 format (YYYY-MM-DD)
- Change types: Added, Changed, Deprecated, Removed, Fixed, Security
- Bullet point lists for change items

## Common Validation Errors

### Missing Unreleased Section
**Error**: "Unreleased section is mandatory for tracking upcoming changes"
**Fix**: Add `## [Unreleased]` section at the top of version history

### Invalid Version Format
**Error**: "Version sections must use semantic versioning (X.Y.Z)"
**Fix**: Use format `## [1.0.0] - 2026-01-06` not `## Version 1.0.0`

### Invalid Date Format
**Error**: "Date must be in ISO 8601 format: YYYY-MM-DD"
**Fix**: Use `2026-01-06` not `Jan 6, 2026` or `01/06/2026`

### Missing Change Type Subsections
**Warning**: "Version should have at least one change type subsection"
**Fix**: Add `### Added`, `### Fixed`, or other change type heading

## Schema Extension Notes

### Future Enhancements

This schema could be extended with:

1. **System Call Validation** (`x-markitect-validation-hooks`):
   - Verify git tags match CHANGELOG versions
   - Check version ordering consistency
   - Validate date chronology

2. **Agent Validation** (`x-markitect-validation-agents`):
   - Semantic consistency checking
   - Duplicate entry detection
   - Version numbering logic validation

3. **Cross-Reference Validation**:
   - Link validation to issue trackers
   - Commit hash verification
   - Release note completeness checking

## Keep a Changelog Standard

This schema enforces the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) principles:

- **Changelogs are for humans**, not machines
- **One entry per version**
- **Group changes by type** (Added, Changed, etc.)
- **Versions and dates** for each release
- **Latest version first**
- **Unreleased section** for upcoming changes

Combined with [Semantic Versioning](https://semver.org/), this enables consistent, readable version history.

## Version History

- **1.0** (2026-01-06): Initial schema release
  - Basic structure validation
  - Version and date format checking
  - Change type subsection validation
  - Keep a Changelog compliance

## Related Schemas

- `schema-schema-v1.0.md` - Metaschema for validating schemas
- `manpage-schema-v1.0.md` - Schema for manual pages
- `api-documentation-schema-v1.0.md` - Schema for API documentation

## License

Part of MarkiTect Schema System