Skip to main content

Cross-artifact Patterns

Real BDL systems are usually composed from multiple related artifacts rather than isolated definitions.

This page describes safe composition patterns without inventing undocumented reference shapes or runtime bindings.

Composition principle​

Each artifact should have a clear responsibility and stable identity.

Relationships between artifacts should use structures documented by the active BDL baseline.

Do not connect artifacts by guessing native identifiers, internal object IDs, field IDs, workflow activity IDs, or runtime values.

Common composition patterns​

Entity and form​

An entity defines data structure and domain identity.

A form provides an interaction surface for that entity.

The form should reference the intended entity through the supported BDL reference structure rather than by fabricated native metadata.

Entity and report​

A report may read data associated with one or more entities.

Resolve the source entity and required fields from authoritative metadata before defining report columns, filters, grouping, or parameters.

Entity, form, and workflow​

A workflow may use forms to collect or review data associated with an entity.

Do not assume that a form can be attached to a workflow activity merely because both artifact kinds exist.

Check the runtime and authoring capability for the exact linkage.

Workflow, rule, and command​

Rules may govern workflow decisions.

Commands may expose explicit operations used by users or workflow surfaces.

Keep each responsibility separate unless the active baseline explicitly defines a combined structure.

Permission and navigation​

Permissions and menu or navigation artifacts may control who can access a page, form, report, or command.

Do not assume that authoring availability for one artifact automatically implies authoring availability for all related access-control artifacts.

Page and group​

Pages and groups are first-class artifact kinds in the active knowledge baseline.

Their presence in the language model does not automatically imply that every create, update, rename, move, or delete operation is available in the current authoring surface.

Dependency ordering​

When several artifacts depend on each other, create and validate them in dependency order.

A typical safe sequence is:

  1. Resolve existing native metadata.
  2. Define foundational entities or references.
  3. Validate foundational artifacts.
  4. Define dependent forms, reports, pages, or workflows.
  5. Add rules, commands, permissions, and navigation.
  6. Validate again before execution.
  7. Post-verify the resulting native state.

Reference discipline​

Use stable BDL codes for authored objects when supported.

Use authoritative native identifiers only when they have been resolved from live metadata or trusted deployment context.

Never convert captions into assumed internal identifiers.

Avoid hidden coupling​

Do not rely on undocumented side effects such as:

  • A form being auto-linked to an entity
  • A report automatically inheriting permissions
  • A workflow automatically discovering a start form
  • A command automatically appearing in navigation
  • A page automatically resolving a group

If a relationship matters, it should be explicitly represented using supported BDL structures or explicitly resolved by runtime metadata.

Validation pattern​

For multi-artifact definitions, validate both individual artifacts and cross-artifact references.

The validation pipeline should detect unresolved references, unsupported authoring operations, and capability mismatches before mutation.

Compose the smallest coherent group of artifacts that represents one feature.

Validate it, inspect diagnostics, then extend the feature incrementally.

This is safer than generating an entire subsystem with many unverified cross-references in one step.

Next​

The next page defines AI-safe authoring patterns for generating BDL definitions.