docs: update manpage and terminology examples to schema-of-schemas standard
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled

Updated example documentation to use the new schema-of-schemas standard
with markdown schema format and multi-schema validation commands.

**Manpage Example Updates:**
- Changed schema reference from markdown-manpage-schema.json to manpage-schema-v1.0.md
- Updated all commands to use new multi-schema validation syntax
- Added examples of number-based validation (markitect schema-validate 2)
- Added examples of batch validation (--all, ranges, lists)
- Updated integration examples (CI/CD, pre-commit hooks, Makefile)
- Documented schema registry workflow

**Terminology Example Updates:**
- Changed schema reference from terminology-schema.json to terminology-schema-v1.0.md
- Updated all validation commands to use new CLI syntax
- Added examples of schema-list and numbered selection
- Added batch validation examples
- Updated GitHub Actions and pre-commit hook examples
- Documented schema registry access methods

**Key Changes:**
- All schema filenames now follow {domain}-schema-v{major}.{minor}.md convention
- Commands use schema registry with numbered or filename selection
- Batch validation examples added throughout
- Integration examples updated to new standard
- Documentation reflects markdown-first schema format

All schemas validated successfully against metaschema.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-05 13:13:24 +01:00
parent f19a88f1d5
commit d32dc41315
2 changed files with 100 additions and 73 deletions

View File

@@ -13,9 +13,11 @@ Terminology documents (glossaries, dictionaries, lexicons) benefit from consiste
## Files
- **terminology-example.md** - Example terminology document with proper structure
- **terminology-schema.json** - JSON schema for validating terminology documents
- **Schema**: `terminology-schema-v1.0.md` (in `markitect/schemas/`)
- **README.md** - This file
The terminology schema now follows the schema-of-schemas standard with markdown format and embedded JSON.
## Terminology Document Structure
A well-structured terminology document includes:
@@ -51,39 +53,65 @@ Each term should include:
## Usage
### Using the Registered Schema
### List Available Schemas
The terminology schema is registered in markitect's database and can be used by name:
View all registered schemas (including terminology schema):
```bash
# List all registered schemas (terminology-schema.json should appear)
markitect schema-list
```
# Validate using the registered schema
markitect validate my-glossary.md --schema terminology-schema.json
You should see `terminology-schema-v1.0.md` listed with a number.
# Or use the local file directly
markitect validate my-glossary.md --schema examples/terminology/terminology-schema.json
### Validate Using the Schema
The terminology schema is registered in MarkiTect's database. You can validate using multiple methods:
```bash
# By schema number (if terminology schema is #4 in the list)
markitect schema-validate 4
# By schema filename (from registry)
markitect schema-validate terminology-schema-v1.0.md
# Validate a specific document file
markitect validate my-glossary.md --schema terminology-schema-v1.0.md
# Or use the local file path directly
markitect validate my-glossary.md --schema ./markitect/schemas/terminology-schema-v1.0.md
```
### Validate with Detailed Errors
```bash
markitect validate my-glossary.md --schema terminology-schema.json --detailed-errors
markitect schema-validate terminology-schema-v1.0.md --detailed-errors
```
### Register the Schema (if needed)
### Batch Validation
If the schema isn't already registered, you can add it to markitect's database:
Validate multiple schemas at once:
```bash
markitect schema-ingest markitect/schemas/terminology-schema.json
# Validate all schemas
markitect schema-validate --all
# Validate a range
markitect schema-validate 1-4
# Validate specific schemas
markitect schema-validate 2,4
```
### Generate Schema from Example
### View the Schema
Examine the terminology schema:
```bash
markitect schema-generate terminology-example.md --output my-terminology-schema.json
# Get from registry
markitect schema-get terminology-schema-v1.0.md
# Or view the markdown file directly
cat markitect/schemas/terminology-schema-v1.0.md
```
## Schema Features
@@ -238,7 +266,7 @@ Include specialized validation rules:
```bash
#!/bin/bash
# .git/hooks/pre-commit
markitect validate docs/glossary.md --schema schemas/terminology-schema.json
markitect validate docs/glossary.md --schema terminology-schema-v1.0.md
```
### GitHub Actions
@@ -257,7 +285,7 @@ jobs:
- name: Validate Glossary
run: |
markitect validate docs/glossary.md \
--schema schemas/terminology-schema.json \
--schema terminology-schema-v1.0.md \
--detailed-errors
```