docs: update schema validation manual with Phase 1 features
Comprehensively document the new classification system and content control features added in Phase 1. ## Documentation Updates ### New Content Added **1. Updated MarkiTect Extensions Section** - Replaced deprecated x-markitect-required/recommended-sections - Documented x-markitect-sections with five classification levels - Documented x-markitect-content-control for content validation **2. Added Section Classification System (150+ lines)** - Detailed explanation of all five classification levels: - required: Missing = ERROR - recommended: Missing = WARNING - optional: No validation impact - discouraged: Present = WARNING - improper: Present = ERROR - Validation behavior for each classification - JSON examples for each level **3. Added Content Control Documentation** - Pattern validation (required/discouraged/forbidden) - Content quality metrics (word count, readability targets) - Content instructions for authors - Complete examples with explanations **4. Updated Schema Design Best Practices** - Replaced old extension examples with new classification system - Added guidance on choosing appropriate classifications - Examples showing required, recommended, optional, discouraged, improper **5. Added Classification System Example** - Complete working schema demonstrating all features - Validation scenarios showing different outcomes - Integration of sections and content-control extensions ## Changes Summary **Lines Added**: ~200 lines of new documentation **Sections Updated**: 4 major sections **Examples Added**: 8 new code examples **Key Topics Covered**: - Five-level classification system (required → improper) - Content pattern validation - Quality metrics and readability targets - Content instructions for document authors - Validation behavior for each classification - Complete working examples ## Validation ✅ Manual validates against improved markdown-manpage-schema.json ✅ All new features documented with examples ✅ Backward compatibility maintained ✅ Self-documenting: manual uses the features it documents The manual now comprehensively documents the Phase 1 enhanced schema system while itself validating against a schema using those features. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -59,13 +59,21 @@ MarkiTect schemas are standard JSON Schema (draft-07) documents with custom exte
|
||||
|
||||
MarkiTect extends JSON Schema with custom properties prefixed with **x-markitect-**:
|
||||
|
||||
**x-markitect-required-sections**
|
||||
: Array of required H2 section names
|
||||
: Example: ["SYNOPSIS", "DESCRIPTION", "EXAMPLES"]
|
||||
**x-markitect-sections**
|
||||
: Section classification and content control system
|
||||
: Defines sections with five classification levels:
|
||||
: - **required**: Must be present (validation fails if missing)
|
||||
: - **recommended**: Should be present (warning if missing)
|
||||
: - **optional**: May be present (no validation impact)
|
||||
: - **discouraged**: Should not be present (warning if present)
|
||||
: - **improper**: Must not be present (validation fails if present)
|
||||
: Each section can specify content instructions, constraints, and custom messages
|
||||
|
||||
**x-markitect-recommended-sections**
|
||||
: Array of recommended but optional section names
|
||||
: Generates warnings when missing
|
||||
**x-markitect-content-control**
|
||||
: Content validation rules for section content
|
||||
: Defines required/discouraged/forbidden patterns
|
||||
: Specifies content quality metrics (word count, readability)
|
||||
: Provides content instructions for authors
|
||||
|
||||
**x-markitect-outline-mode**
|
||||
: Boolean enabling outline-only validation
|
||||
@@ -236,6 +244,139 @@ The **metadata** property validates overall document characteristics:
|
||||
|
||||
Use **const** for exact matches or ranges for flexibility.
|
||||
|
||||
### Section Classification System
|
||||
|
||||
MarkiTect provides a five-level classification system for document sections through **x-markitect-sections**:
|
||||
|
||||
#### Required Sections
|
||||
|
||||
Sections marked as **required** must be present in the document. Validation fails with an error if missing.
|
||||
|
||||
```json
|
||||
"SYNOPSIS": {
|
||||
"classification": "required",
|
||||
"error_message": "SYNOPSIS section is mandatory for all manpages"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Behavior**:
|
||||
- Missing → ERROR → validation fails
|
||||
- Present → Continue validation
|
||||
|
||||
#### Recommended Sections
|
||||
|
||||
Sections marked as **recommended** should be present. A warning is generated if missing, but validation succeeds.
|
||||
|
||||
```json
|
||||
"EXAMPLES": {
|
||||
"classification": "recommended",
|
||||
"warning_if_missing": "Examples improve documentation usability"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Behavior**:
|
||||
- Missing → WARNING → validation succeeds with warnings
|
||||
- Present → Continue validation
|
||||
|
||||
#### Optional Sections
|
||||
|
||||
Sections marked as **optional** may or may not be present with no validation impact.
|
||||
|
||||
```json
|
||||
"BUGS": {
|
||||
"classification": "optional",
|
||||
"content_instruction": "Known issues and bug reporting"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Behavior**:
|
||||
- Missing → No impact
|
||||
- Present → Continue validation
|
||||
|
||||
#### Discouraged Sections
|
||||
|
||||
Sections marked as **discouraged** should not be present. A warning is generated if found, but validation succeeds.
|
||||
|
||||
```json
|
||||
"DEPRECATED": {
|
||||
"classification": "discouraged",
|
||||
"warning_if_missing": "Move deprecated content to HISTORY section"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Behavior**:
|
||||
- Missing → No impact
|
||||
- Present → WARNING → validation succeeds with warnings
|
||||
|
||||
#### Improper Sections
|
||||
|
||||
Sections marked as **improper** must not be present. Validation fails with an error if found.
|
||||
|
||||
```json
|
||||
"TODO": {
|
||||
"classification": "improper",
|
||||
"error_message": "TODO sections must be removed before publication"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Behavior**:
|
||||
- Missing → No impact
|
||||
- Present → ERROR → validation fails
|
||||
|
||||
### Content Control
|
||||
|
||||
The **x-markitect-content-control** extension enables content-level validation:
|
||||
|
||||
#### Pattern Validation
|
||||
|
||||
**required_patterns** - Array of regex patterns that must appear in content:
|
||||
```json
|
||||
"required_patterns": ["\\*\\*command\\*\\*", "\\[.*\\]"]
|
||||
```
|
||||
|
||||
**discouraged_patterns** - Patterns that should not appear (generates warnings):
|
||||
```json
|
||||
"discouraged_patterns": ["TODO", "FIXME", "\\bWIP\\b"]
|
||||
```
|
||||
|
||||
**forbidden_patterns** - Patterns that must not appear (validation fails):
|
||||
```json
|
||||
"forbidden_patterns": ["password\\s*=", "api[_-]?key\\s*="]
|
||||
```
|
||||
|
||||
#### Content Quality Metrics
|
||||
|
||||
Validate content length and readability:
|
||||
|
||||
```json
|
||||
"content_quality": {
|
||||
"min_words": 50,
|
||||
"max_words": 1000,
|
||||
"readability_target": "technical",
|
||||
"min_sentences": 3
|
||||
}
|
||||
```
|
||||
|
||||
**Readability Targets**:
|
||||
- **simple** - Elementary school level
|
||||
- **general** - General audience
|
||||
- **technical** - Technical audience (default for documentation)
|
||||
- **advanced** - Expert/academic level
|
||||
|
||||
#### Content Instructions
|
||||
|
||||
Provide guidance for content authors:
|
||||
|
||||
```json
|
||||
"content_instructions": [
|
||||
"Show command name in bold",
|
||||
"Use brackets [] for optional arguments",
|
||||
"Keep synopsis concise (1-5 lines)"
|
||||
]
|
||||
```
|
||||
|
||||
These instructions appear in validation reports and generated templates.
|
||||
|
||||
## ERROR HANDLING
|
||||
|
||||
### Common Validation Errors
|
||||
@@ -303,11 +444,33 @@ Allow flexibility with minItems/maxItems ranges:
|
||||
|
||||
Avoid exact counts (**const**) unless structure is truly rigid.
|
||||
|
||||
**Required vs Optional Sections**
|
||||
**Section Classification**
|
||||
|
||||
Use **x-markitect-required-sections** for essential sections like SYNOPSIS and DESCRIPTION.
|
||||
Use the five-level classification system to define section requirements:
|
||||
|
||||
Use **x-markitect-recommended-sections** for important but optional sections like EXAMPLES.
|
||||
```json
|
||||
"x-markitect-sections": {
|
||||
"SYNOPSIS": {
|
||||
"classification": "required",
|
||||
"content_instruction": "Brief command syntax",
|
||||
"error_message": "SYNOPSIS is mandatory"
|
||||
},
|
||||
"EXAMPLES": {
|
||||
"classification": "recommended",
|
||||
"warning_if_missing": "Examples improve usability"
|
||||
},
|
||||
"BUGS": {
|
||||
"classification": "optional"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Choose classifications based on importance:
|
||||
- **required** for essential sections (SYNOPSIS, DESCRIPTION)
|
||||
- **recommended** for important sections (EXAMPLES, SEE ALSO)
|
||||
- **optional** for nice-to-have sections (BUGS, AUTHORS)
|
||||
- **discouraged** for sections that should be elsewhere (DEPRECATED)
|
||||
- **improper** for sections that must not appear (TODO, INTERNAL_NOTES)
|
||||
|
||||
**Heading Patterns**
|
||||
|
||||
@@ -463,6 +626,78 @@ markitect schema-generate example.md --max-depth 2 --output v2-schema.json
|
||||
markitect validate test-doc.md v2-schema.json
|
||||
```
|
||||
|
||||
### Schema with Classification System
|
||||
|
||||
Create a schema with section classifications and content control:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "Technical Documentation Schema",
|
||||
"x-markitect-sections": {
|
||||
"OVERVIEW": {
|
||||
"classification": "required",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "High-level description of the system",
|
||||
"min_paragraphs": 2,
|
||||
"error_message": "OVERVIEW section is required"
|
||||
},
|
||||
"EXAMPLES": {
|
||||
"classification": "recommended",
|
||||
"heading_level": 2,
|
||||
"min_code_blocks": 2,
|
||||
"warning_if_missing": "Examples help users understand usage"
|
||||
},
|
||||
"REFERENCES": {
|
||||
"classification": "optional",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "External documentation and resources"
|
||||
},
|
||||
"TODO": {
|
||||
"classification": "improper",
|
||||
"error_message": "Remove TODO sections before publishing"
|
||||
}
|
||||
},
|
||||
"x-markitect-content-control": {
|
||||
"overview": {
|
||||
"discouraged_patterns": ["TODO", "FIXME"],
|
||||
"forbidden_patterns": ["password", "secret"],
|
||||
"content_quality": {
|
||||
"min_words": 100,
|
||||
"max_words": 500,
|
||||
"readability_target": "technical"
|
||||
}
|
||||
}
|
||||
},
|
||||
"properties": {
|
||||
"headings": {
|
||||
"properties": {
|
||||
"level_1": {"minItems": 1, "maxItems": 1},
|
||||
"level_2": {"minItems": 2, "maxItems": 20}
|
||||
}
|
||||
},
|
||||
"paragraphs": {"minItems": 10, "maxItems": 200},
|
||||
"code_blocks": {"minItems": 1}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Validate documents against this schema:
|
||||
|
||||
```bash
|
||||
# Missing required section = ERROR
|
||||
markitect validate doc-without-overview.md tech-schema.json
|
||||
# Result: INVALID - missing required section OVERVIEW
|
||||
|
||||
# Missing recommended section = WARNING
|
||||
markitect validate doc-without-examples.md tech-schema.json
|
||||
# Result: VALID (with warnings) - missing recommended section EXAMPLES
|
||||
|
||||
# Improper section present = ERROR
|
||||
markitect validate doc-with-todo.md tech-schema.json
|
||||
# Result: INVALID - improper section TODO must not be present
|
||||
```
|
||||
|
||||
## FILES
|
||||
|
||||
**\*.json**
|
||||
|
||||
Reference in New Issue
Block a user