Codegen entity meta-model — file-level conventions
Table of Contents
This page is linked from the Codegen org-entity meta-model hub. Where every
other segment page documents one facet's knobs, this one documents
the conventions that apply to the whole file, before any facet gets
involved at all — this is what a .org file has to look like for
codegen to recognise it as an entity model in the first place. The
concrete document-type scaffold this describes is
ores.doc.modeling.entity_org — the archetype compass add
entity_org renders from.
Naming
Entity files live under projects/ores.<component>/modeling/ with
the filename ores.<component>.<entity>.org. Example:
ores.refdata.party.org under projects/ores.refdata/modeling/.
(Historical note: an earlier convention put these under
projects/ores.codegen/models/<component>/<entity>_entity.org; that
path no longer exists in the tree — codegen discovers models via the
modeling_dir manifest entry, matching #+type: ores.codegen.entity
in the frontmatter, not by directory convention.)
Frontmatter
The first few lines of the file are org-mode frontmatter. They
describe the document (this codegen model), not the modelled
entity. :ID:, #+type:, #+filetags:, and #+component: are
inherited from every metatype's common base — see Codegen
meta-model § "Common frontmatter". Specialized to ores.codegen.entity
on top of that base, and required:
| Keyword | Purpose |
|---|---|
:ores.cpp.qt.enabled: (drawer, optional) |
Set to false to skip Qt-layer generation entirely for this entity. Currently false on ores.marketdata.market_observation (a TimescaleDB hypertable entity) because the standard generated CRUD/detail-dialog Qt layer doesn't fit high-volume timeseries data — a statement about today's generated Qt layer not being the right shape, not a decision that observations never get a UI; a dedicated timeseries-appropriate UI is expected future work (see the capture on timeseries codegen analysis). Defaults to generating Qt when absent. |
#+title: |
Fully-qualified entity name, e.g. ores.refdata.party. |
#+description: |
What this file is, not what the modelled thing is. |
#+entity_singular: |
Identifier form, singular (party). |
#+entity_plural: |
Identifier form, plural (parties). |
#+entity_title: |
Title-cased human form (Party). |
#+brief: |
One-line summary of the modelled entity. |
Prose body (between frontmatter and first heading)
A paragraph or two describing the modelled entity itself. This
text is exposed to templates as the entity description. Keep the
document-level #+description for the file and put the entity
description here.
See also
- Codegen org-entity meta-model — the hub.
- Codegen meta-model — the registry this metatype belongs to, and the common-frontmatter base every metatype specializes.
- ores.doc.modeling.entity_org — the document-type archetype this page describes;
compass add entity_orgrenders a blank scaffold from it.