Validation, schemas, and repair

Validation proves integration configs match JSON schemas and behave correctly before upload. Repair fixes drift between application.yaml and on-disk JSON — the most common cause of “validate passed locally but upload failed” incidents.

Why it matters

Uncertified or invalid configs must not reach AI workloads. Validation is the gate before upload, test, and certification. Skipping repair after manual edits leaves silent drift: missing datasource entries, wrong systemKey, stale deploy JSON, or dimensions out of sync with attributes.

Treat validate → repair (dry-run) → test ladder as the default loop for every integration change. Run validate at the end of each phase (model, govern, publish) — not only once after initial scaffold.

Prerequisites

Integration folder under integration/<systemKey>/
aifabrix auth status green for online cert-sync (optional)

Where it lives

Artifact	Schema	Typical file
Application manifest	`application-schema` ~1.4.x	`application.yaml`
External system	`external-system-schema` ~1.8.x	`<systemKey>-system.json`
External datasource	`external-datasource-schema` ~2.7.x	`<datasourceKey>.json`

Reference summaries: External system schema, External datasource schema, Application schema.

How to set

Validate one file or the whole integration:

aifabrix validate <systemKey>
aifabrix validate <path-to-json>
aifabrix datasource validate <datasourceKey>

Preview repair before mutating lists or auth:

aifabrix repair <systemKey> --dry-run

Apply repair flags as needed:

aifabrix repair <systemKey> --rbac --expose --sync
aifabrix repair <systemKey> --auth apikey
aifabrix json <systemKey>

Re-validate — never upload on stale repair output.
Optional cert sync when online certification state changed:

aifabrix validate <systemKey> --cert-sync

Test ladder after green validate — see Test ladder and protection.

Defaults and examples

Drift symptom	Repair action
Datasource file exists but not in application.yaml	Sync system/datasource lists
Datasource `systemKey` mismatch	Align keys
OpenAPI assumed OAuth on API-key vendor	`--auth apikey` + env.template
metadataSchema stale vs attributes	Refresh from fieldMappings
Missing deploy JSON	Regenerate via `json`

Datasource root fields validated on every pass include key, displayName, systemKey, entityType, resourceType, primaryKey, and indexed externalId for record/document storage.

Example validate command sequence:

{
  "command": "aifabrix validate example-crm",
  "expects": ["schema", "resourceType", "externalId"]
}

aifabrix validate example-crm
aifabrix repair example-crm --dry-run
aifabrix repair example-crm --expose --rbac
aifabrix validate example-crm
aifabrix upload example-crm --probe

Progress from local to live behavior:

aifabrix test <systemKey>
aifabrix test-integration <systemKey>
aifabrix test-e2e <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey> --verbose

verify-operations orchestrates validate → test → integration → E2E as certification pillar 1. Do not run certification pillars on broken validate output.

Validate

aifabrix validate <systemKey>
aifabrix repair <systemKey> --dry-run

If validate reports unknown resourceType, fix catalog first — repair cannot invent catalog keys.

Common mistakes

Mistake	Impact	Fix
Edit JSON without updating application.yaml	Validate fails or upload targets wrong files	`repair --dry-run`
Skip E2E after schema-only validate	Ops pillar fails on live API	Full test ladder
Manual deploy JSON edits	Overwritten on next `json`	Regenerate, don't hand-edit
Validate once at scaffold time	Drift accumulates through govern/publish	Validate every phase

Limits

Schema version numbers drift with Builder releases — confirm against reference schemas when validate errors cite unexpected required fields. Repair is idempotent for lists and auth but does not replace thoughtful field mapping edits. Keep a change log of which datasourceKey files were touched each sprint so repair dry-runs stay reviewable. When validate cites missing externalId, fix metadataSchema before re-running repair — repair will not invent join identity fields for you.

Documentation Index