Skip to main content

validation-route

OSCAL Document Validation​

Overview​

The validation module provides asynchronous OSCAL document processing with support for validation, conversion, and reference resolution operations. It uses Docker containers to run the OSCAL CLI tools in isolated environments.

Core Validation Workflow​

1. File Upload and Job Creation​

When a user uploads an OSCAL document for validation:

  • A unique job ID (UUID) is generated for tracking
  • The uploaded file is saved to the configured upload folder
  • A job entry is created with PENDING status in the global validation_jobs dictionary
  • The process returns immediately with the job ID (non-blocking)

2. Asynchronous Processing​

The validation runs in a background thread using run_validation_async():

  • Job Status Updates: PENDING → RUNNING → COMPLETED/FAILED
  • Container Execution: Creates and runs an oscalprocessing Docker container
  • Volume Mounting: Mounts host directories for file access:
    • {HOST_VOLUME_PATH}/flask/shared:/shared - Input files
    • {HOST_VOLUME_PATH}/flask/generatedFiles:/generatedFiles - Output files

3. OSCAL CLI Integration​

The OscalDocumentProcessing class handles:

  • Command Generation: Creates appropriate OSCAL CLI commands (e.g., validate /shared/{filename})
  • Container Management: Runs, monitors, and cleans up Docker containers
  • Output Capture: Collects validation results and logs from container execution
  • Error Handling: Manages container failures and non-zero exit codes

4. Result Retrieval​

Users can check job status and retrieve results via the /status/<job_id> endpoint, which returns:

  • Current job status (PENDING, RUNNING, COMPLETED, FAILED)
  • Validation results (when completed)
  • Error messages (when failed)