Validates OpenAPI specs against a local Itential dev stack — confirms every operation becomes a callable task.
Use a dedicated local dev stack. This tool imports and deletes integration models repeatedly. Running it against a shared or production stack will disrupt other work.
Mac/Linux only.
git clone https://github.com/nathaniel-itential/integration-model-validation.git
cd integration-model-validation
./install.sh
$EDITOR ~/.local/bin/config.json # set your IAP URL, credentials, and assets_dir
validate-integration fetch
validate-integration bulk| File | Purpose |
|---|---|
~/.local/bin/validate-integration |
The CLI |
~/.local/bin/config.json |
Connection config |
~/.claude/skills/validate-integration/SKILL.md |
Claude Code skill (/validate-integration) |
validate-integration fetch # index specs from the configured assets_dir folder
validate-integration bulk # validate all fetched specs
validate-integration bulk --no-cleanup # keep imported models after each specfetch scans the assets_dir folder (configured in config.json) for *.json files one level deep and writes their absolute paths to validate-paths.json in the current directory.
bulk reads from that file and writes results to validate-report.json in the current directory.
Paths can also be written manually into validate-paths.json and executed with validate-integration bulk.
validate-integration <spec.json>
validate-integration <spec.json> --group my_team_group # override default group
validate-integration <spec.json> --cleanup # delete instance + model after
validate-integration <spec.json> --json # machine-readable output/validate-integration fetch
/validate-integration bulk
/validate-integration /path/to/spec.json
~/.local/bin/config.json:
{
"iap_url": "http://localhost:3000",
"username": "admin@itential",
"password": "admin",
"default_group": "admin_group",
"assets_dir": "~/.cache/itential-openapi-specs"
}assets_dir should point to a flat folder of OpenAPI spec JSON files. Re-running install.sh updates the config in place — your values are preserved.
| Stage | What it checks |
|---|---|
login |
Credentials and connectivity |
auth-check |
Security schemes use supported types, are applied to operations, and only one scheme is declared |
import |
Platform accepts the spec |
instance |
A virtual instance can be created from the model |
role-discovery |
Platform auto-created an admin role for the integration |
authz |
Role is granted to the configured group |
methods |
Every operation became a callable task |
- Does not verify the spec matches the real vendor API
- Does not test auth credentials against the real upstream
- Does not execute tasks end-to-end
command not found: validate-integration
Add export PATH="$HOME/.local/bin:$PATH" to your shell rc file.
Login failed (exit 2)
Check that your dev stack is running and that the URL and credentials in config.json are correct.
fetch returns 0 specs
Check that assets_dir in config.json points to a folder containing *.json files.
FAIL at auth-check: auth defined but unapplied
The spec defines security schemes but no operations reference them. Add a top-level security block.
FAIL at import: must NOT have additional properties
Adapter-generated spec with non-standard parse/encode/encrypt fields. Strip them before validating.
FAIL at import: exclusiveMinimum must be number
Spec uses JSON Schema Draft 4 boolean syntax. Convert { "minimum": N, "exclusiveMinimum": true } to { "exclusiveMinimum": N }.
FAIL at authz: group not found
Re-run with --group <name> or set default_group in config.json. The error output lists available groups.
PARTIAL (methods X/Y)
Some operations were dropped during import. Usually caused by duplicate or missing operationId values.
Bulk run aborts with health check failure
The platform accumulates in-memory state across bulk runs. Run make clean on the dev stack to fully reset it before the next bulk run.