Skip to main content

How to choose the correct element role?

Every ElementClass needs a role. The role determines where the ElementClass lives in your project, whether it needs a parent, and whether it can be expanded into code at all. By deciding on the correct role, you prevent unexpected behavior on expansion, and can harness the functionality of the role.

Decision path​

1. Does it need to generate code?​

If the ElementClass represents something that should be expanded into artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project., you need one of the expandable roles: element, program, or module.

If it's purely descriptive (information the model needs), but nothing should be generated from it directly — you're looking at node, data, config, or taxonomy instead.

2. Does it stand alone, or does it belong to something else?​

  • Stands alone, no parent needed → data, program, module
  • Needs a parent to be part of the model at all → element, node, variant

3. Is it the root of an expandable codebase, or something reusable across programs?​

  • It's the architectural root you expand into a project (e.g. an Application) → program
  • It's a reusable model that a program can pull in (e.g. a shared set of script modules) → module

Because Program and Module define the root structure of your metamodel, choosing between them has consequences beyond this page. see Program Models and Module Models for what each one commits you to.

4. Is it configured by application developers rather than shipped in code?​

If applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. developers should be able to define instances themselves, outside of an ExpansionResource, in a settings directory next to their model → config.

5. Can it be referenced without being defined anywhere in the model?​

If an element should be usable even when nothing in the current model actually declares it — because it's expected to be stubbed — → taxonomy.

6. Does it need multiple versions, selected at expansion time?​

If you need several versions of something and only one should be picked during expansion → variant, as a child of a Program via composition.

7. Is its only purpose to be written out, rather than read?​

If the ElementClass isn't really "part of" the model but instead gets exported during expansion or other processes → export.

For the exact requirements and constraints behind each role (identifier rules, where each is defined, reference compatibility) see the ElementRole reference.