Skip to content
EN FR

Models, concepts, facets and relations

Documentation status: guide — see Maturity and evidence.

Build the conceptual model before optimizing storage, routes or screens. The model is executable meaning; tables, generated classes and views are projections of that meaning.

Concepts and instances

A concept declares stable meaning. An instance is a runtime occurrence of that concept. For identified entities, identity is conceptual and should not be simulated by an arbitrary application field when the runtime already provides entity identity semantics.

Model declaration with modernized implementation names

Some current metadata forms include implementation bindings. The public documentation keeps those examples but removes the historical T prefix:

class:
  classId: lgc#activity
  name: Activity
  className: CustomClassItem
  currentGeneratorName: Common.CustomActivity
  type: Entity
  object:
    className: ObjectItemActivity
    objectName: Activity

The same normalization applies to relation-like models:

class:
  classId: lgc#belongs_to
  name: BelongsTo
  className: CustomClassItem
  currentGeneratorName: Common.BelongsTo
  type: Entity
  object:
    className: CustomObjectItem
    objectName: BelongsTo

These names select runtime implementations where the metadata grammar requires a binding. They do not replace the conceptual identifiers lgc#activity or lgc#belongs_to.

Facets

Use facets to project one concept into several operational spaces. Typical facets include conceptual/hypergraph structure and persistence. A persistence field should point back to conceptual meaning through its role path rather than becoming a second unrelated model.

Relations and roles

Roles are part of the model contract. For a relation, declare participant roles with meaningful names and stable order. Use a polyadic relation when the business fact naturally has more than two participants instead of decomposing it into unrelated binary edges only for storage convenience.

Reify a relation when the relation itself needs identity, persistence, attributes, lifecycle, actions or references from other structures.

Design rule

A model should answer, in order:

What concepts exist?
What gives each concept identity?
Which roles and relations express its meaning?
Which facets project that meaning?
Which constraints make invalid states explicit?
Which actions/events expose behavior?
Which views/services publish selected capabilities?

For detailed hypergraph semantics see Conceptual hypergraph and Special dimensions.