Skip to main content

Examples and Patterns

This section provides practical BDL examples and reusable authoring patterns.

Examples are intended to show the smallest clear definition that expresses a design intent without inventing native Barsa state, identifiers, runtime behavior, or unsupported authoring capabilities.

How to use these examples​

Each example should be read together with the BDL reference and capability model.

Before using an example in a real system, verify all four capability layers:

  1. Native Barsa - Does Barsa support the capability?
  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?

An example demonstrating a language structure does not automatically prove that every related runtime or authoring operation is available.

Minimal BDL document​

The smallest useful BDL document starts with the language schema, project identity, references, and artifacts.

{
  "schema": "barsa.definition.v1",
  "project": {
    "code": "SAMPLE",
    "caption": "Sample",
    "systemId": "${RESOLVE_SYSTEM_ID}",
    "version": "1.0.0"
  },
  "references": {},
  "artifacts": []
}

systemId is intentionally unresolved in this example.

Authors and AI systems must resolve environment-specific identifiers from live metadata or an authoritative deployment context rather than fabricate them.

Example principles​

  • Start with the smallest valid definition.
  • Never invent native identifiers or existing system state.
  • Keep language structure separate from runtime assumptions.
  • Validate before mutation.
  • Prefer explicit diagnostics over guessed values.
  • Treat systemCode as governed code, not an escape hatch.
  • Preserve version and evidence context.

Planned examples​

This section will include:

  • Minimal project definitions
  • Entities and fields
  • Forms and layouts
  • Reports
  • Workflows
  • Rules and commands
  • Permissions and navigation
  • Notifications and seed data
  • Pages and groups
  • System code governance
  • Cross-artifact composition patterns
  • AI-safe authoring patterns

Pattern versus capability​

A pattern describes a recommended way to compose BDL artifacts.

A capability statement describes what a specific Barsa, runtime, BDL, or authoring layer can actually support.

Do not use an example or pattern as evidence that a capability exists.