Application metadata

Documentation status: reference — see Maturity and evidence.

logiCells metadata describes structures the Runtime can interpret and execute. It is not decorative annotation: classId, rolePath, published, action parameters, facets, and views are part of the execution contract.

Two notations, one contract

Projects may use XML or YAML. New YAML examples must follow the current canonical declarative grammar:

YAML -> Yaml2XML -> DOM XML -> DataStructure -> Runtime
XML  -------------------------> DataStructure -> Runtime

Historical XML remains an important compatibility format. New YAML documentation must not reproduce permissive legacy XML shortcuts.

Main families

• Class — conceptual identity and model container.
• Entities — instantiable business concepts.
• Relations — conceptual links and reified facts.
• Actions — executable capabilities and intentions.
• Events — observable changes.
• States and Transitions — explicit lifecycle.
• Collections — set navigation and projections.
• Views — functional projections of concepts.
• Rules — constraints and executable interpretation.
• Processes — multi-step, multi-participant coordination.
• Lifecycle — cross-cutting lifecycle view.
• Execution flow — from model to execution.
• Roles — role paths and conceptual projections.

Authoring conventions

For new content:

1. use *.model.yaml or *.model.xml for models;
2. use ClassItems.manifest.yaml or ClassItems.manifest.xml for the manifest;
3. use a stable project-owned classId, for example crm#contact;
4. keep a field name as the YAML key when the grammar allows it;
5. use explicit item types in polymorphic lists, especially action: and actionGroup:;
6. cite public names and capability aliases, never private implementation names;
7. never add a T prefix to example classes.

Minimal example

class:
  name: Contact
  classId: crm#contact
  type: Entity
  concepts:
    - name: Entity
      facets:
        - name: main
          type: hypergraph
          fields:
            - Name: String
            - Email: String
  actions:
    - action:
        name: Validate
        type: ObjectItem
        published: true
        params:
          - Result:
              dataType: Boolean
              paramType: ptReturn

The exact permitted structure is always defined by the declarative grammar and the targeted Runtime version.