Validate inspects a contracts/steampipe/<asset_type>.yaml mapping and
reports whether it can produce a schema-valid observation for the
declared asset type, plus how much of the catalog's read surface it
covers.
Three checks:
1. Structural — required fields, recognised operation kinds, each
kind's mandatory subfields.
2. Schema fit — every operation path resolves to a property declared
in schemas/observation/v1/asset-types/<asset_type>.schema.json
(paths the schema does not declare are warned, not failed —
additionalProperties is true).
3. Catalog coverage — how many of the property paths the control +
chain catalog reads for this asset type are populated, with the
highest-control-count gaps surfaced.
Inputs:
--file FILE Mapping YAML to validate (required)
--controls DIR Control catalog (default: controls)
--chains DIR Chain catalog (default: chains)
--format F text (default) | json
--strict Treat coverage gaps and unknown-to-schema paths
as failures (exit 3) instead of warnings.
Exit codes:
0 Mapping is valid (warnings may apply unless --strict)
2 Invalid input (missing flag, unreadable file, bad format)
3 Mapping is invalid (structural or, with --strict, coverage gap)
4 Internal error
Usage:
stave validate-mapping [flags]
Examples:
stave validate-mapping --file contracts/steampipe/aws_s3_bucket.yaml
stave validate-mapping --file contracts/steampipe/aws_iam_role.yaml --strict
stave validate-mapping --file contracts/steampipe/aws_kms_key.yaml --format json
Flags:
--chains string chain catalog directory (default "chains")
-i, --controls string control catalog directory (default "controls")
--file string mapping YAML file to validate (required)
-f, --format string output format: text | json (default "text")
-h, --help help for validate-mapping
--strict treat coverage gaps and unknown-to-schema paths as failures
Global Flags:
--allow-symlink-output Allow writing output through symlinks (default: refuse)
--force Allow overwriting existing output files
--log-file string Write logs to file (default: stderr)
--log-format string Log format: text|json (default "text")
--log-level string Log level: debug|info|warn|error (overrides -v)
--log-timestamps Include timestamps in logs (breaks determinism)
--log-timings Include timing information (breaks determinism)
--no-color Disable ANSI colors in output
--path-mode string Path rendering in errors/logs: base (basename only) or full (absolute paths) Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
--quiet Suppress output (exit code only) Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
--require-offline Assert offline operation: fail if proxy env vars (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) are set
--sanitize Sanitize infrastructure identifiers (bucket names, ARNs, policies) from output Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
-v, --verbose count Increase verbosity (-v=INFO, -vv=DEBUG)
-y, --yes Auto-confirm all interactive prompts (distinct from --force which controls file overwriting)