Skip to main content

Entity Example

This example shows how an entity artifact fits into a BDL document.

The example focuses on document composition and artifact placement rather than inventing environment-specific identifiers or unsupported native metadata.

Example​

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

What this example demonstrates​

  • An entity is represented as an artifact.
  • The artifact belongs inside the root artifacts array.
  • The artifact kind is explicitly declared as entity.
  • Stable authoring identifiers such as code should be chosen deliberately.
  • Human-readable text such as caption should remain distinct from machine-oriented identity.

What this example does not prove​

This example does not prove that every possible entity operation is available in the current authoring surface.

Before creating or modifying a real entity, verify:

  1. Native Barsa supports the intended entity behavior.
  2. Runtime support exists for the intended operation.
  3. BDL can express the required structure.
  4. The current BDL authoring surface permits that operation.

Extending the entity​

Real entities commonly require additional definition such as fields, relationships, constraints, permissions, forms, or related artifacts.

Those should be added only using structures documented by the active BDL baseline.

Do not infer undocumented field shapes from this minimal entity example.

Safe authoring pattern​

Start with the smallest entity definition that can be validated.

Then add fields and related artifacts incrementally, validating each meaningful change rather than generating a large unverified model in one step.

Existing entities​

If the target entity already exists in Barsa, do not invent its identifier or assume its current structure.

Resolve the live entity from authoritative metadata before attempting an update, rename, relationship, or other mutation.

Next​

The next example shows how a form artifact relates to an entity.