markitect-main/roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md

Schema Naming Convention Specification

Version: 1.0 Status: Implemented Created: 2026-01-04

Overview

This specification defines the filename convention for all MarkiTect schema files to ensure consistency, discoverability, and version tracking across the schema ecosystem.

Filename Format

Standard Format

{domain}-schema-v{major}.{minor}.md

Components

Component	Description	Rules	Examples
domain	Schema domain identifier	- Lowercase only - Start with letter - Letters, numbers, hyphens - No consecutive hyphens - No leading/trailing hyphens	manpage api-documentation arc42
schema	Literal keyword	- Must be exactly schema	schema
version	SemVer major.minor	- Format: v{major}.{minor} - Non-negative integers - Must include both major and minor	v1.0 v2.5 v10.25
extension	File extension	- Must be .md (markdown)	.md

Regular Expression

^[a-z][a-z0-9-]*-schema-v\d+\.\d+\.md$

Breakdown:

• ^[a-z] - Start with lowercase letter
• [a-z0-9-]* - Followed by lowercase letters, numbers, or hyphens
• -schema- - Literal string
• v\d+\.\d+ - Version (v + digits + dot + digits)
• \.md$ - Extension

Valid Examples

Simple Domains

manpage-schema-v1.0.md
terminology-schema-v1.0.md
glossary-schema-v1.0.md

Multi-Word Domains

api-documentation-schema-v1.0.md
architecture-decision-record-schema-v1.0.md
software-requirements-specification-schema-v1.0.md

With Numbers

arc42-schema-v1.0.md
rfc2119-keywords-schema-v1.0.md
iso27001-schema-v1.0.md

Version Variations

manpage-schema-v1.0.md     # Initial version
manpage-schema-v1.1.md     # Minor update
manpage-schema-v2.0.md     # Breaking change
manpage-schema-v10.25.md   # Double-digit versions

Invalid Examples

Wrong Extension

❌ manpage-schema-v1.0.json    # Must be .md
❌ manpage-schema-v1.0.yaml    # Must be .md
❌ manpage-schema-v1.0          # Missing extension

Missing Components

❌ manpage-v1.0.md              # Missing "schema" keyword
❌ manpage-schema.md            # Missing version
❌ manpage.md                   # Missing "schema" and version

Version Format Errors

❌ manpage-schema-1.0.md        # Missing 'v' prefix
❌ manpage-schema-v1.md         # Missing minor version
❌ manpage-schema-v1.0.0.md     # Too many version parts (patch not used)
❌ manpage-schema-v1-0.md       # Hyphen instead of dot

Case Errors

❌ ManPage-schema-v1.0.md       # Uppercase in domain
❌ manpage-Schema-v1.0.md       # Uppercase in keyword
❌ MANPAGE-SCHEMA-V1.0.MD       # All uppercase

Domain Format Errors

❌ 42answers-schema-v1.0.md     # Starts with number
❌ -manpage-schema-v1.0.md      # Starts with hyphen
❌ man_page-schema-v1.0.md      # Underscore (use hyphen)
❌ man page-schema-v1.0.md      # Space (use hyphen)
❌ my--schema-v1.0.md           # Consecutive hyphens

Version Numbering Guidelines

Semantic Versioning

We use simplified SemVer with major.minor only:

Major Version (X.0):

• Breaking changes to schema structure
• Incompatible with previous version
• Documents validated against v1.0 may fail v2.0

Examples:

• manpage-schema-v1.0.md → manpage-schema-v2.0.md (breaking change)
• api-schema-v1.0.md → api-schema-v2.0.md (new required sections)

Minor Version (X.Y):

• Backward-compatible additions
• New optional sections or fields
• Relaxed constraints
• Documents validated against v1.0 still validate against v1.1

Examples:

• manpage-schema-v1.0.md → manpage-schema-v1.1.md (new optional section)
• api-schema-v2.0.md → api-schema-v2.1.md (additional metadata)

Version Incrementing

v1.0 → v1.1 → v1.2 → ... → v1.9 → v1.10 → v1.11
                                   ↓
                                  v2.0 (breaking change)

Initial Version

All new schemas start at v1.0.md:

# New schema
my-new-type-schema-v1.0.md

Domain Naming Guidelines

Good Domain Names

Descriptive and Specific:

✓ manpage-schema-v1.0.md              # Clear: Unix manual pages
✓ api-documentation-schema-v1.0.md    # Clear: API docs
✓ architecture-decision-record-schema-v1.0.md  # Full ADR name

Concise but Meaningful:

✓ adr-schema-v1.0.md                  # Common abbreviation
✓ rfc-schema-v1.0.md                  # Well-known acronym
✓ arc42-schema-v1.0.md                # Standard name

Poor Domain Names

Too Generic:

❌ document-schema-v1.0.md            # Too vague
❌ markdown-schema-v1.0.md            # All schemas are markdown
❌ schema-schema-v1.0.md              # Redundant (use "metaschema")

Too Verbose:

❌ my-custom-documentation-template-for-apis-v1.0.md  # Too long
   → api-documentation-schema-v1.0.md                 # Better

Unclear Abbreviations:

❌ mt-schema-v1.0.md                  # What is "mt"?
❌ doc-schema-v1.0.md                 # Too generic

Normalization Rules

When converting arbitrary strings to valid domain names:

1. Convert to lowercase

   • API Documentation → api documentation

2. Replace separators with hyphens

   • Spaces: api documentation → api-documentation
   • Underscores: my_type → my-type
   • Multiple separators: my type → my--type

3. Remove consecutive hyphens

   • my--type → my-type

4. Remove leading/trailing hyphens

   • -my-type- → my-type

5. Validate result

   • Must start with letter
   • Only lowercase letters, numbers, hyphens

Example Normalizations

"API Documentation"       → "api-documentation-schema-v1.0.md"
"My_Custom_Type"          → "my-custom-type-schema-v1.0.md"
"arc42  Architecture"     → "arc42-architecture-schema-v1.0.md"
"--leading-hyphen"        → "leading-hyphen-schema-v1.0.md"

Implementation

Validation Function

The naming convention is enforced by markitect.schema_naming.validate_schema_filename():

from markitect.schema_naming import validate_schema_filename

is_valid, metadata = validate_schema_filename("manpage-schema-v1.0.md")

if is_valid:
    print(f"Domain: {metadata['domain']}")
    print(f"Version: {metadata['version']}")
    print(f"Major: {metadata['major']}, Minor: {metadata['minor']}")

Suggestion Function

Generate valid filenames from arbitrary input:

from markitect.schema_naming import suggest_schema_filename

# From clean input
filename = suggest_schema_filename("manpage", "1.0")
# → "manpage-schema-v1.0.md"

# From messy input (with normalization)
filename = suggest_schema_filename("API Documentation", "2.1")
# → "api-documentation-schema-v1.0.md"

CLI Integration

The schema-ingest command validates filenames:

# Valid filename - accepted
$ markitect schema-ingest manpage-schema-v1.0.md
✅ Schema stored successfully

# Invalid filename - rejected (unless --force)
$ markitect schema-ingest manpage.json
❌ Invalid schema filename: manpage.json

Expected format: {domain}-schema-v{major}.{minor}.md
Example: manpage-schema-v1.0.md

Suggested filename: manpage-schema-v1.0.md

Use --force to skip validation

Migration from Legacy Naming

Current State Analysis

Existing schemas with inconsistent naming:

terminology-schema.json       # Has .json extension
api-documentation             # No version, no extension
enhanced-manpage              # No version, no extension, unclear name
markdown-manpage              # No version, no extension
markdown-manpage-schema.json  # Has .json extension

Migration Strategy

1. Identify domain and version
2. Apply naming convention
3. Update database registration
4. Remove legacy entries

Migration Mapping

Old Name                      → New Name
────────────────────────────────────────────────────────────────
terminology-schema.json       → terminology-schema-v1.0.md
api-documentation             → api-documentation-schema-v1.0.md
enhanced-manpage              → manpage-schema-v2.0.md
markdown-manpage              → (DELETE - duplicate)
markdown-manpage-schema.json  → (DELETE - duplicate)

Rationale:

• enhanced-manpage → v2.0 (has breaking changes: classification system)
• markdown-manpage variants → DELETE (superseded by v1.0 and v2.0)

Special Cases

Metaschema

The schema-for-schemas follows the same convention:

schema-schema-v1.0.md

Domain is schema, indicating it validates schemas themselves.

Multiple Schemas for Same Domain

Use version numbers to distinguish:

manpage-schema-v1.0.md    # Original
manpage-schema-v2.0.md    # Enhanced with classifications

Or use more specific domain names:

manpage-simple-schema-v1.0.md      # Simplified variant
manpage-extended-schema-v1.0.md    # Extended variant

Validation Testing

All schemas should pass the naming convention validation:

# Test a filename
python -c "
from markitect.schema_naming import is_valid_schema_filename
print(is_valid_schema_filename('manpage-schema-v1.0.md'))
"
# → True

# Get detailed errors
python -c "
from markitect.schema_naming import get_validation_errors
errors = get_validation_errors('invalid.json')
for error in errors:
    print(error)
"

Benefits

Consistency

• All schemas follow same pattern
• Easy to recognize schema files
• Predictable naming

Versioning

• Clear version tracking
• Multiple versions can coexist
• Breaking changes explicit (major version bump)

Discoverability

• Glob patterns work: *-schema-v*.md
• Easy to list all schemas: ls *-schema-*.md
• Domain easily extractable

Tooling

• Programmatic validation
• Automatic suggestion
• Migration support

References

• Implementation: markitect/schema_naming.py
• Tests: tests/test_schema_naming.py
• Workplan: roadmap/schema-of-schemas/WORKPLAN.md
• Examples: examples/schemas/manpage-schema-v1.0.md

Changelog

v1.0 (2026-01-04)

• Initial specification
• Implemented validation and suggestion functions
• 50 unit tests (100% passing)
• CLI integration planned