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.
1. 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.)
2. 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 |
|---|---|
#+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. |
3. 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.
4. 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.