Language Overview

BDL is a governed JSON contract for describing authorable Barsa metadata, system structure, and supported runtime-governed operations.

BDL expresses intent and structure. It does not replace the native Barsa Runtime, which remains the execution source of truth.

Root document

Every BDL document starts from a canonical root structure:

{
  "schema": "barsa.definition.v1",
  "project": {
    "code": "SampleProject",
    "caption": "Sample Project",
    "systemId": 123,
    "version": "1.0.0"
  },
  "references": {},
  "artifacts": []
}

The root document contains four primary areas:

Property	Purpose
schema	Identifies the BDL document schema.
project	Defines project identity and version metadata.
references	Holds references required by the definition.
artifacts	Contains the system artifacts described by BDL.

Project identity

The project object identifies the BDL project and the target Barsa system.

Native identifiers such as project.systemId must be resolved from live metadata. Guessing native IDs is prohibited.

Artifact model

The base model declares these artifact kinds:

• entity
• form
• report
• workflow
• rule
• command
• permission
• menu
• notification
• seedData
• systemCode

BDL v5.2 additionally promotes page and group to first-class artifact kinds.

The existence of an artifact kind in the language model does not automatically mean that every property is available for production authoring.

Language versus runtime

When evaluating a feature, keep these concerns separate:

1. Native Barsa capability
2. Runtime support
3. BDL expressibility
4. BDL authoring availability

A feature may be supported at one layer and unavailable at another.

Golden path

A governed BDL workflow follows this general sequence:

1. Identify the requirement and host artifact.
2. Check capability documentation and known gaps.
3. Resolve live metadata and identifiers.
4. Author the smallest valid JSON.
5. Parse, preflight, and validate.
6. Review the execution plan and blocking diagnostics.
7. Obtain approval where required.
8. Execute through governed native runtime services.
9. Reload and verify the result.
10. Export, round-trip, reconcile, and record evidence.

Next

Continue to the Artifact Reference for the structure and rules of individual BDL artifact kinds.