USM

Appearance

usm/cli-validate ​

The usm validate command checks .usm files against the v1 JSON Schema and reports errors.

Usage ​

bash
# Validate all .usm files in the .usm/ directory
usm validate .usm

# Validate a single file
usm validate .usm/system.usm

# Validate from current directory (scans all .usm dirs)
usm validate .

Why this exists ​

Users need to verify that their .usm files conform to the schema before generating docs. Validate catches missing required fields, wrong types, and invalid enum values.

How it works ​

Run usm validate (run-validate) ​

User runs usm validate on one or more .usm files

  1. Parse — each .usm file path
  2. Observe — v1 JSON Schema via Ajv
    • expects: valid: true
  3. Submit — validation result per file
  4. Observe — exit code 0 if all pass, 1 if any fail

Guarantees ​

validate-against-v1-schema ​

Validate must use the v1.json schema with Ajv and report all errors

Acceptance criteria:

  • [ ] Uses Ajv with allErrors: true
  • [ ] Reports path and message for each error
  • [ ] Exit code 1 if any file fails

Test specifications ​

validate-valid-file ​

Given:

  • valid_usm_file: true

Then:

  • assertion: output shows ✓ for the file
  • assertion: exit code 0

validate-invalid-file ​

Given:

  • usm_missing_required_fields: true

Then:

  • assertion: output shows ✗ with error details
  • assertion: exit code 1