Trestle Validation

Trestle Validation and Troubleshooting

Validation Commands

Validate All Models

trestle validate -a

This command validates every OSCAL model in the workspace. -a is short for --all. This skill uses -a in all examples.

What a clean run looks like: On a new workspace with no models, trestle validate -a finds no models. The command exits with code 0. Little or no output is normal. No output means pass. It is not a failure. After you add models, a pass lists each validated model. There are no ERROR lines. The exit code is 0.

Validate by Type

trestle validate -t catalog -n my-catalog
trestle validate -t profile -n my-profile
trestle validate -t component-definition -n my-compdef
trestle validate -t system-security-plan -n my-ssp
trestle validate -t assessment-plan -n my-assessment
trestle validate -t assessment-results -n my-results
trestle validate -t plan-of-action-and-milestones -n my-poam

Validate Specific File

trestle validate -f catalogs/my-catalog/catalog.json

Common Validation Errors

Schema Validation Errors

Workspace Structure Errors

Authoring Errors (Generate/Assemble)

Import Errors

Troubleshooting Guide

Step 1: Check Workspace Health

# Verify workspace
ls -la .trestle/

# Check config
cat .trestle/config.ini

# List all models
ls catalogs/ profiles/ component-definitions/ system-security-plans/ 2>/dev/null

Step 2: Run Full Validation

trestle validate -a 2>&1

Step 3: Check Individual Models

For each model that fails validation:

# Validate specific model with verbose output
trestle validate -t <type> -n <name>

# Check the model file directly
python -c "import json; json.load(open('<path>/model.json'))"

Step 4: Common Fixes

Fix Invalid UUIDs

import uuid
print(str(uuid.uuid4()))

Replace any bad or missing UUIDs with new ones.

Fix YAML Header Issues in Markdown

Common YAML problems in control markdown:

• Missing quotes around values with special characters
• Incorrect indentation (YAML requires consistent spaces, not tabs)
• Missing --- delimiters around frontmatter

Fix Broken Import References

Profiles reference catalogs by href. Check:

"imports": [
  { "href": "trestle://catalogs/nist-800-53/catalog.json" }
]

The referenced catalog must exist at that path in the workspace.

Fix Assembly Failures

If assemble fails after markdown edits:

1. Check that the YAML header is not corrupt.
2. Check that no structural markdown elements were deleted. Keep headers and dividers.
3. Generate again. Then apply your changes:

   trestle author ssp-generate --name <ssp> --output <md_dir>-fresh
   

   Then diff the fresh output against your edited version.

Step 5: Reset and Recover

If a model is corrupt:

1. Check if dist/ has a previously assembled good copy.
2. Import again from the original source.
3. Use git history to recover previous versions.

Validation Best Practices

1. Validate after every change: Run trestle validate after imports, edits, and assemblies.
2. Validate before committing: Add validation to your pre-commit workflow.
3. Use CI/CD validation: Run trestle validate -a in pipelines.
4. Keep backups: Assemble to dist/ often. Keep those files as validated snapshots.
5. Version control: Use git to track all changes to OSCAL models.
6. One format per directory: Do not mix JSON and YAML in the same model directory.

Error Message Reference

Trestle validation errors follow this pattern:

ERROR: [model_type] [model_name]: [error_description]

When you report an issue:

• Include the full error message.
• Note which command caused the error.
• Give the trestle version (trestle version).
• Give the Python version (python --version).

What Each Validator Checks

Trestle includes several specialized validators. These go beyond basic schema validation:

Run specific validators with:

trestle validate -t <model-type> -n <model-name>

All validators run automatically as part of trestle validate -a.

Validating Split Files

After you use trestle split, individual fragment files are not valid OSCAL documents by themselves. Follow this workflow:

1. Do not validate during a split. A split model's root file references child files with the trestle split convention. The individual pieces do not pass schema validation on their own.

2. Always merge before you validate:

   trestle merge -e catalog.*        # merge all split parts back
   trestle validate -t catalog -n my-catalog
   

3. Partial check. Do not run schema validation on split files. You can check that they are valid JSON:

   python -c "import json, pathlib; [json.loads(p.read_text()) for p in pathlib.Path('.').rglob('*.json')]"
   

4. Pattern: The correct workflow is always split → edit → merge → validate. Do not skip the merge step before validation.

CI/CD Validation Patterns

CI/CD validation is optional for first tests. Run trestle validate -a on your machine during exploration. Add the pipeline patterns below after models are in version control and change often.

GitHub Actions Workflow

name: OSCAL Validation

on:
  pull_request:
    paths:
      - 'catalogs/**'
      - 'profiles/**'
      - 'component-definitions/**'
      - 'system-security-plans/**'
      - 'assessment-results/**'
      - 'plan-of-action-and-milestones/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install trestle
        run: pip install compliance-trestle

      - name: Initialize trestle workspace
        run: |
          cd ${{ github.workspace }}
          trestle init --govdocs

      - name: Validate all OSCAL models
        run: |
          trestle validate -a 2>&1 | tee validation-report.txt
          if grep -q "ERROR" validation-report.txt; then
            echo "::error::OSCAL validation failed"
            exit 1
          fi

      - name: Validate governed docs
        run: trestle author docs validate -tn policies -hv

      - name: Upload validation report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: validation-report
          path: validation-report.txt

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: trestle-validate
        name: Validate OSCAL models
        entry: bash -c 'trestle validate -a'
        language: system
        pass_filenames: false
        files: '\.(json|yaml|yml)$'

Tip: For faster feedback during development, validate only the model you changed:

trestle validate -t system-security-plan -n my-ssp

Reserve trestle validate -a for CI/CD pipelines.

Validation After Assessment and POA&M Edits

Assessment results and POA&M documents use a JSON workflow. Use split and merge. Do not use generate and assemble. Validate after every merge. These models have many UUID references.

Common Assessment Validation Issues

Common POA&M Validation Issues

Tip: Always validate with the specific type for faster feedback:

trestle validate -t assessment-results -n my-results
trestle validate -t plan-of-action-and-milestones -n my-poam

Cross-References

• trestle-authoring-workflow: The generate-assemble cycle. Validation finds structure errors before they spread.
• trestle-assessment: JSON assessment-results workflow. The refs validator is required.
• trestle-poam: JSON POA&M workflow with many UUID references. Use refs and duplicates validation.
• trestle-governance: Combine OSCAL schema validation with document structure validation.