# BDL - Barsa Definition Language

> Official documentation and machine-readable discovery entry point for BDL.

BDL is a governed JSON-based language for defining Barsa systems for human and AI-assisted authoring.

Canonical site: https://bdl-lang.org

## Primary Documentation

- [Introduction](https://bdl-lang.org/docs/intro): What BDL is and the core documentation model.
- [Language Overview](https://bdl-lang.org/docs/language/overview): Root document, project identity, artifacts and language/runtime distinction.
- [Artifact Reference](https://bdl-lang.org/docs/reference/artifacts): BDL artifact kinds and common artifact rules.
- [Capability Model](https://bdl-lang.org/docs/reference/capabilities): Native Barsa, Runtime Support, BDL Expressibility and BDL Authoring Availability.
- [Validation](https://bdl-lang.org/docs/validation/overview): Governed validation and execution pipeline.
- [Troubleshooting](https://bdl-lang.org/docs/troubleshooting/overview): Incident classification and evidence-driven diagnostics.
- [Known Gaps](https://bdl-lang.org/docs/known-gaps/current): Current documented gaps and limitations.
- [AI Authoring Guidance](https://bdl-lang.org/docs/ai/authoring): Rules for safe AI-generated BDL.
- [Releases](https://bdl-lang.org/docs/releases): Version dimensions, baselines and release policy.

## Current Baseline

- Knowledge baseline: Barsa_BDL_Master_Knowledge_Pack_v5.2.2_ALIGNED_20260828
- Schema family: barsa.definition.v1
- Documentation language: English

## Critical AI Rules

- Never invent Native Barsa IDs.
- Resolve required identifiers from live metadata.
- Do not infer authoring availability from Native Barsa capability alone.
- Evaluate Native Barsa, Runtime Support, BDL Expressibility and BDL Authoring Availability separately.
- Check Known Gaps before generating production BDL.
- Prefer the smallest valid BDL definition.
- Parse success is not production authorization.
- Use validation, diagnostics and approval before governed mutation.
- Do not fabricate state that cannot be recovered losslessly from Native Barsa.
- Treat systemCode as a governed surface, not arbitrary code execution.

## Machine-readable metadata

- https://bdl-lang.org/bdl-release.json

Official domain: bdl-lang.org