Trestle Validation and Troubleshooting

Validation Commands

Validate All Models

trestle validate -a

Validates every OSCAL model in the workspace.

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 malformed or missing UUIDs with fresh 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 the YAML header hasn't been corrupted
2. •Verify no structural markdown elements were deleted (headers, dividers)
3. •Try regenerating and re-applying changes:
   bash

   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 badly corrupted:

1. •Check if dist/ has a previously assembled good copy
2. •Re-import 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/ regularly as validated snapshots
5. •Version control: Use git to track all changes to OSCAL models
6. •One format per directory: Don't 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 reporting issues:

• •Include the full error message
• •Note which command triggered the error
• •Provide the trestle version (trestle version)
• •Include the Python version (python --version)

What Each Validator Checks

Trestle includes several specialized validators that 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 using trestle split, individual fragment files are not standalone valid OSCAL documents. Validation must follow the correct workflow:

1. •

   Never validate mid-split — a split model's root file references child files via the trestle split convention. The individual pieces won't pass schema validation on their own.

2. •

   Always merge before validating:

   bash

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

3. •

   Partial sanity check — while you shouldn't schema-validate split files, you can verify they are valid JSON:

   bash

   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. Never skip the merge step before validation.

CI/CD Validation Patterns

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 JSON-based workflows (split/merge rather than generate/assemble). Validation is critical after every merge because these models have dense UUID cross-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 where validation catches structural errors before they propagate
• •trestle-assessment: JSON-based assessment-results workflow where refs validation is essential
• •trestle-poam: JSON-based POA&M workflow with dense UUID cross-references requiring refs and duplicates validation
• •trestle-governance: Combining OSCAL schema validation with document structure validation for complete coverage