markitect-main/markitect/schemas/changelog-schema-v1.0.md

schema, version, domain, description, created, author

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

Changelog Schema v1.0

Overview

This schema validates CHANGELOG.md files following the Keep a Changelog 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

{
  "$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

# 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

# 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 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, 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