Skip to main content

AI-safe Authoring Patterns

BDL is designed to work well with AI-assisted authoring, but AI-generated definitions must remain evidence-driven, capability-aware, and validation-first.

This page defines safe patterns for AI systems that generate, modify, or reason about BDL.

Core rule​

Never invent native Barsa state.

An AI system must not fabricate identifiers, existing entities, fields, forms, workflows, pages, groups, runtime capabilities, or deployment metadata.

Unknown state should remain unresolved until authoritative metadata is available.

Pattern 1: Resolve before referencing​

Before generating a reference to an existing object:

  1. Identify what metadata is required.
  2. Resolve the object from authoritative live metadata.
  3. Confirm identity and scope.
  4. Only then emit the BDL reference.

Do not derive internal identity from captions or human-readable names alone.

Pattern 2: Check all four capability layers​

For every important feature, distinguish:

  1. Native Barsa - Does Barsa support it?
  2. Runtime Support - Can the runtime execute it?
  3. BDL Expressibility - Can BDL describe it?
  4. BDL Authoring Availability - May the current authoring surface generate it?

Do not collapse these questions into a single supported assumption.

Pattern 3: Generate the smallest valid definition​

Prefer the smallest BDL document that expresses the requested intent.

Add complexity incrementally.

This makes validation failures easier to diagnose and reduces the risk of fabricated cross-artifact references.

Pattern 4: Preserve unresolved values​

When deployment-specific values are unknown, keep them explicit and unresolved.

Example:

{
  "systemId": "${RESOLVE_SYSTEM_ID}"
}

An unresolved placeholder is safer than a guessed identifier.

Pattern 5: Diagnostics over fabrication​

If required information is missing, emit a diagnostic requirement instead of inventing a value.

Examples include:

  • Missing native identifier
  • Unknown field metadata
  • Unsupported authoring operation
  • Runtime capability not confirmed
  • Ambiguous target object
  • Known gap affecting lossless authoring

Pattern 6: Validate before mutation​

AI-generated BDL should pass the validation pipeline before any native mutation is performed.

The expected flow is:

  1. Parse
  2. Resolve live metadata
  3. Preflight
  4. Validate or compile
  5. Build execution plan
  6. Review blocking diagnostics
  7. Approve
  8. Execute
  9. Post-verify
  10. Reconcile

Pattern 7: Treat system code as governed code​

systemCode is not a fallback for unsupported or unknown BDL structures.

Use it only when explicitly justified, supported, reviewed, and validated.

Prefer first-class BDL artifacts whenever they can represent the intended behavior.

Pattern 8: Preserve version context​

AI systems should keep independent version dimensions explicit.

Do not treat the BDL language version, knowledge baseline, Native Contract version, runtime pack version, and documentation site version as one shared version.

Pattern 9: Respect known gaps​

Known gaps are part of the authoritative contract.

An AI system must not silently work around a known gap by inventing unsupported syntax or assuming lossless behavior.

If a known gap affects the request, surface it explicitly.

Pattern 10: Post-verify native state​

Successful execution is not the end of the workflow.

After mutation, compare the resulting native state with the intended BDL definition.

Detect drift, partial application, unexpected defaults, or runtime-side transformations.

Unsafe patterns​

Avoid these behaviors:

  • Guessing IDs
  • Inferring internal names from captions
  • Assuming model presence means authoring availability
  • Treating runtime support as guaranteed by BDL syntax
  • Generating large subsystems before validating foundations
  • Using system code to bypass unsupported structures
  • Ignoring known gaps
  • Silently mixing version baselines

Understand intent, resolve metadata, check capabilities, generate the smallest definition, validate, inspect diagnostics, then expand incrementally.

This pattern keeps AI-generated BDL auditable, explainable, and safer to execute.