BDL - Barsa Definition Language

BDL is a structured, JSON-based language for defining Barsa systems in a governed and machine-readable form.

Instead of describing a system through scattered manual configuration, BDL can represent the major building blocks of a system as structured definitions that can be created, reviewed, validated, versioned, and generated with AI assistance.

What BDL is for

BDL is designed to help teams define and evolve Barsa systems faster while preserving explicit structure and governance.

A BDL project can describe artifacts such as:

• Entities and fields
• Forms and layouts
• Reports
• Workflows
• Business rules and commands
• Permissions and navigation
• Notifications and seed data
• System code
• Other governed artifacts supported by the active BDL version

A minimal BDL project

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

Every BDL definition should be interpreted against the documentation and contracts for its active version.

Capability is layer-aware

BDL documentation does not treat support as one generic boolean.

A capability may differ across four independent layers:

Layer	Question
Native Barsa	Does the Barsa platform support the capability?
Runtime Support	Can the active runtime execute it?
BDL Expressibility	Can BDL describe it?
BDL Authoring Availability	Is governed authoring available for it?

This distinction is important for both human authors and AI systems.

Documentation goals

This documentation is intended to be the authoritative reference for:

• BDL syntax and structure
• Artifact definitions
• Capability availability
• Validation requirements
• Runtime behavior
• Authoring constraints
• Diagnostics and troubleshooting
• Known gaps and limitations
• Version-specific changes
• AI authoring guidance

Next

Continue with the language overview to understand the top-level structure of a BDL definition and how artifacts are organized.