Skip to main content

Minimal BDL Document

This example shows the smallest practical BDL document structure.

It establishes the language schema, project identity, reference container, and artifact collection without inventing environment-specific state.

Example​

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

What each section means​

schema​

Identifies the BDL language family used by the document.

Current documentation uses:

barsa.definition.v1

project​

Contains project-level identity and version information.

The project block should identify the intended system without fabricating deployment-specific identifiers.

systemId​

systemId is environment-specific.

In reusable examples it should remain unresolved until authoritative metadata is available.

Do not replace ${RESOLVE_SYSTEM_ID} with a guessed value.

references​

Provides a place for references to existing or externally resolved objects.

An empty object is valid when the document does not yet need external references.

artifacts​

Contains the BDL artifacts that define the system.

An empty array represents a valid structural starting point before entities, forms, reports, workflows, or other artifacts are added.

Starting from the smallest valid document makes validation and diagnostics easier.

It also prevents authors and AI systems from introducing unsupported assumptions before live metadata and capability checks are available.

Safe authoring rules​

  • Resolve environment-specific identifiers from authoritative metadata.
  • Do not invent existing Barsa objects.
  • Add artifacts incrementally.
  • Validate after meaningful changes.
  • Keep language structure separate from runtime assumptions.
  • Check all four capability layers before relying on a feature.

Next​

The next example adds an entity artifact to this minimal document.