Skip to main content

Validation

BDL validation is a governed process that should detect problems before production execution whenever possible.

Validation is not a single schema check. It combines document parsing, capability checks, metadata resolution, preflight analysis, runtime-aware validation and blocking diagnostics.

Validation pipeline​

A governed BDL operation follows this general validation path:

  1. Parse the BDL document.
  2. Resolve required live metadata and native identifiers.
  3. Run preflight checks.
  4. Compile or run ValidateOnly without mutation.
  5. Build and review the execution plan.
  6. Review blocking diagnostics.
  7. Obtain explicit approval where required.
  8. Execute through governed runtime services.
  9. Reload and post-verify the result.
  10. Export, round-trip and reconcile where applicable.

Parse​

Parsing confirms that the BDL document can be interpreted according to the active language model.

A property being parsable does not automatically mean that it is runtime-supported or production-authorable.

Live metadata resolution​

Native identifiers must come from live metadata when required.

Do not guess:

  • System IDs
  • Entity IDs
  • Field IDs
  • Form IDs
  • Report IDs
  • Workflow IDs
  • Other native identifiers

Failure to resolve required metadata should block authoring rather than trigger guessed values.

Preflight​

Preflight is intended to detect invalid or unsafe operations before mutation.

Typical preflight concerns include:

  • Required values
  • Unsupported properties
  • Capability availability
  • Native identity resolution
  • Placement and host constraints
  • Version compatibility
  • Runtime contract requirements
  • Known gaps
  • Approval requirements

ValidateOnly​

Where supported, validation should use a non-mutating ValidateOnly or equivalent compile path before execution.

Validation must not be treated as permission to mutate production metadata.

Execution plan​

Before governed execution, tooling should produce or expose the intended execution plan.

The plan should make the proposed operation reviewable before mutation occurs.

Blocking diagnostics​

Blocking diagnostics prevent execution when a condition makes the requested operation invalid, unsafe, unsupported or insufficiently evidenced.

A blocking diagnostic should be resolved before execution rather than bypassed through guessed configuration.

Approval​

Some operations require explicit approval.

Destructive or governed mutation must not proceed merely because a document parsed successfully.

Approval requirements are operation- and contract-specific.

Post-verification​

Successful execution is not the end of validation.

After mutation, reload the affected metadata and verify that the persisted and runtime-visible result matches the intended definition.

Round-trip and reconciliation​

Where supported, export the resulting state and compare it with the intended BDL definition.

Round-trip and reconciliation provide evidence that the authored definition and the resulting Barsa state remain aligned.

Failure classification​

Validation and troubleshooting should distinguish at least these failure classes:

  • Authoring defect
  • Pre-execute detection gap
  • Runtime bug
  • Environment or baseline problem
  • Known gap or unsupported behavior
  • Insufficient evidence

An authoring correction does not automatically close a validator gap. If preflight should have detected the same problem before execution, that validation gap should be tracked separately.

Key rule​

Parse success is not production authorization.

Authors and AI systems must verify runtime support, BDL expressibility, authoring availability, diagnostics and approval requirements before execution.

Next​

Continue to Troubleshooting for the diagnostic model and failure investigation workflow.