Codegen input org-file schema reference
Table of Contents
- 1. Summary
- 2. Entity-model schemas
- 3. Flags — PROPERTIES: schema, product, component, has_tenant_id
- 4. Columns
- 5. SQL
- 6. C++
- 7. See also — org-roam links
- 8. Primary key — PROPERTIES: column, type, is_text
- 9. Columns
- 10. Artefact indexes — (optional)
- 11. See also
- 12. Includes — #+begin_src cpp :name includes
- 13. Fields
- 14. Left — PROPERTIES: column, column_short, column_title,
- 15. Right — same shape as * Left
- 16. Columns
- 17. SQL
- 18. Repository — PROPERTIES: name_singular_short, name_short,
- 19. C++
- 20. See also
- 21. Flags — PROPERTIES: central_entity
- 22. Parts — | part | entity | table
- 23. See also
- 24. <service_name> — PROPERTIES: psql_var, env_key, iam_role,
- 25. Entities — | Entity | Brief | table (org-roam links in Entity column)
- 26. See also
- 27. Generator-config schemas
- 28. Facets
- 29. Facet groups
- 30. Components
- 31. ores.modelines module
- 32. See also
This document is the authoritative schema reference for all org-mode files that feed into ores.codegen. It covers three layers:
- Entity-model types — org files that describe a single logical entity and drive code generation across multiple technical spaces (C++, SQL, TypeScript).
- Generator-config types — org files that configure the generator itself (profiles, components, modelines).
For the code that reads these files see ores.codegen architecture.
1. Summary
1.1. Entity-model types
| Type | Compass type | Count | Primary output |
|---|---|---|---|
ores.codegen.entity |
entity_org |
~83 | C++ domain class + SQL table + TypeScript UI |
ores.codegen.lookup_entity |
lookup_entity |
0 | Superseded: the staging table is declared on the owning entity's model and the type is not used by any model |
ores.codegen.field_group |
field_group |
~11 | C++ struct fragment composed into entities |
ores.codegen.table (retired) |
— | 0 | Superseded by ores.codegen.entity; every table model was migrated and the type removed from the generator |
ores.codegen.junction |
junction |
~8 | SQL join table + C++ struct + repository |
ores.codegen.family |
— | few | Composite family protocol (C++ header + TypeScript twin); no scaffolder yet, so the model is authored by hand |
ores.codegen.service_registry |
service_registry |
~2 | SQL GRANT scripts + shell var declarations |
ores.codegen.module |
— | few | Index: groups entity docs for a namespace |
ores.codegen.component |
— | 0 active | Reserved; future component-level config |
1.2. Generator-config types
| Type | File | Description |
|---|---|---|
ores.codegen.facet_catalogue (retired) |
ores physical-space graph | Profile → facet → template/output mapping now lives per-facet on the graph, not in one file |
ores.codegen.component_catalogue |
component_catalogue.org | Component name → discovery roots; read by manifest.py |
ores.codegen.modeline_catalogue |
modeline.org | Editor modeline strings per language; read by generator.py |
2. Entity-model schemas
2.1. ores.codegen.entity
Full-fidelity entity: drives C++ (domain class, mapper, repo, service), SQL (table DDL, triggers, constraints) and TypeScript (protocol and domain interfaces). The largest doc type (~83 files).
2.1.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.entity |
#+component |
yes | Short component name (refdata, trading, …) |
#+entity_singular |
yes | snake_case singular noun (pricing_engine_type) |
#+entity_plural |
yes | snake_case plural noun (pricing_engine_types) |
#+entity_title |
yes | Title-case display name (Pricing Engine Type) |
#+brief |
yes | One-line description; populates C++ namespace comment |
#+filetags |
yes | At minimum :model:entity:{component}: |
2.1.2. Section hierarchy
#+begin_example
3. Flags — PROPERTIES: schema, product, component, has_tenant_id
4. Columns
** <column_name> — PROPERTIES: type, cpp_type, nullable, default (opt), primary_key (opt), natural_key (opt), server_owned (opt)
5. SQL
** Flags — PROPERTIES: tablename
6. C++
* Flags — PROPERTIES: component_include, component_core (opt), service_find_by_uuid (opt), service_find_by_code_column (opt), service_find_by_code_parent_column (opt) * Repository — PROPERTIES: entity_singular_short, entity_plural_short, … * Domain includes — #+begin_src cpp :name includes * Entity includes — #+begin_src cpp :name includes (opt) * Conventions — PROPERTIES: iterator_var * Table display — | column | header | table * Presentation — PROPERTIES: many (key_field, collection_name, …) ** Detail fields — | field | label | widget | type | is_key | view_group (opt) | … | table * Columns — | enum_name | field | header | type | width | table ** Custom repository methods — freeform
7. See also — org-roam links
#+end_example
A column marked :primary_key: true or :natural_key: true leaves the plain
Columns bucket for the key bucket it names; a column carries at most one of
the two, and the order the key columns appear in the Columns section is their
order in the key. Every natural_key column joins one composite unique index,
so a model states its identity once and both the store and the readers take it
from there. A natural key is not required to be non-nullable, but a column that
is half of an identity usually is.
A key column marked :server_owned: true stays in the key and the unique index
but leaves the write record, so a caller never states it and the service stamps
it from the session. A per-party row keyed by a surrogate id uses this for its
party_id: the unique index still scopes the row to its party, and the write
cannot name a party other than the session's. The flag is refused on any column
the specification does not list as server-owned, so a caller-owned field is not
silently dropped from the wire.
7.0.1. service_find_by_code (C++ Flags)
:service_find_by_code_column: names the column, or the whitespace-separated
columns, a find_X_by_code service method and its read_latest_by_code
repository method read. :service_find_by_code_parent_column: names the parent
column they read first, for an identity whose first column is a foreign key.
A composite value generates one finder over the parent and every named code
column, so a hand-written method never has to restate an identity the model
already declares.
7.0.2. view_group (Detail fields)
An optional cell on each Detail fields row naming which
detail-dialog tab that field belongs to. Fields sharing the same
view_group value land in the same tab, in the order they appear in
the table; tabs themselves appear in first-appearance order across the
table. Fields with no view_group all fall into one implicit tab, so
an entity that never sets it generates exactly the single tab codegen
always produced before this existed — adding view_group to one
entity's model has no effect on any other entity's generated dialog.
Named generically (not e.g. tab) since it models "which projection
of the entity a field belongs to" rather than committing to tabs
specifically — the detail dialog is its only consumer today.
7.0.3. ORE Studio MASD stereotypes
These heading tags appear inside * Columns sub-headings on occasion; they are not
yet systematically applied. Future work: review whether :attribute: on each
column heading would clarify the structure.
7.1. ores.codegen.lookup_entity
A batch-loaded reference table with no UI. Typically driven by an external data source (LEI golden copy, reporting definition catalogue, etc.).
No model uses this type. It built the DQ artefact staging tables, and the
DQ artefact migration moved every one of those onto the model of the entity
it stages, which declares it with
:ores.sql.schema.domain_entity_artefact_create.enabled: true; the
sql_schema_artefact_create template it fed is deleted. The generator still
accepts the type and the compass scaffolder still offers it, so the
description below is kept for reading old models; a new artefact does not
use it. See DQ artefacts.
7.1.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.lookup_entity |
#+component |
yes | Short component name |
#+entity_singular |
yes | snake_case singular |
#+entity_plural |
yes | snake_case plural |
#+has_tenant_id |
yes | true / false |
#+has_coding_scheme |
yes | true / false |
#+has_image_id |
yes | true / false |
#+has_artefact_insert_fn |
yes | true — generate artefact insert helper; false — raw DDL only |
7.1.2. Section hierarchy
#+begin_example
8. Primary key — PROPERTIES: column, type, is_text
9. Columns
** <column_name> — PROPERTIES: type, nullable, default (opt)
10. Artefact indexes — (optional)
** <index_name> — PROPERTIES: columns (space-separated list)
11. See also
#+end_example
11.1. ores.codegen.field_group
A C++ struct fragment composed into one or more parent entity structs. Used to keep each struct below the MSVC C1202 complexity threshold.
11.1.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.field_group |
#+component |
yes | Short component name |
#+component_include |
yes | Full include component (e.g. analytics.api) |
#+product |
yes | ores |
#+entity_singular |
yes | snake_case name of the group |
#+namespace |
yes | C++ namespace (ores::{component}::domain) |
#+brief |
yes | One-line description |
11.1.2. Section hierarchy
#+begin_example
12. Includes — #+begin_src cpp :name includes
13. Fields
** <field_name> — PROPERTIES: cpp_type #+end_example
13.1. ores.codegen.table (retired)
Was an SQL-only reference-data table with no C++ or presentation layer. Every
*_table.org model was migrated into its ores.codegen.entity counterpart
(the * Validation function / * Insert trigger sections moved across
unchanged) and the type's dispatch removed from get_model_type()=/
=load_model() — see Retire legacy codegen profile system; add junction support to physical-space codegen.
SQL-only entities (no C++/UI layer, e.g. currency) are expressed as an
ores.codegen.entity with no ** Presentation section rather than a
distinct type.
13.2. ores.codegen.junction
A SQL join table and its C++ counterpart (struct + repository). Has two
mandatory FK sides (* Left, * Right) and optional extra columns.
13.2.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.junction |
#+component |
yes | Short component name |
#+name |
yes | snake_case plural (badge_mappings) |
#+name_singular |
yes | snake_case singular (badge_mapping) |
#+name_title |
yes | Title-case display name |
#+name_singular_words |
yes | Space-separated words |
#+brief |
yes | One-line description |
#+product |
yes | ores |
#+schema |
yes | PostgreSQL schema (public) |
#+has_tenant_id |
yes | true / false |
13.2.2. Section hierarchy
#+begin_example
14. Left — PROPERTIES: column, column_short, column_title,
type, cpp_type, index_comment, list_by (optional, default false — generates a paginated read_latest_by_<column>(value, offset, limit) + get_total_<entity>_count_by_<column> pair through the repository and service layers, mirroring the domain_entity foreign_keys.list_by knob) — Body: domain prose; optional #+begin_src cpp :name generator
15. Right — same shape as * Left
16. Columns
** <column_name> — PROPERTIES: type, cpp_type, nullable
17. SQL
** Flags — PROPERTIES: tablename
18. Repository — PROPERTIES: name_singular_short, name_short,
name_singular_words, name_words, order_column
19. C++
* Domain includes — #+begin_src cpp :name includes * Entity includes — #+begin_src cpp :name includes * Conventions — PROPERTIES: iterator_var * Table display — | column | header | table
20. See also
#+end_example
20.1. ores.codegen.family
The protocol of a composite entity: one central row plus its parts. It
derives the family's records and its four message pairs — get,
get_many, put and put_many — and drives the C++ protocol header and
its TypeScript twin from one derivation. It derives no domain type, SQL
table or service; see Codegen patterns: choosing a model shape,
section "The generic put and the family put".
20.1.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.family |
#+component |
yes | Short component name; the central entity and the parts are found in its modeling/ dir |
#+entity_singular |
yes | snake_case singular of the family |
#+entity_plural |
yes | snake_case plural |
#+entity_title |
yes | Title-case display name |
#+brief |
yes | One-line description |
#+filetags |
yes | At minimum :model:family:{component}: |
20.1.2. Section hierarchy
#+begin_example
21. Flags — PROPERTIES: central_entity
22. Parts — | part | entity | table
23. See also
#+end_example
central_entity names another model in the same component's modeling
directory whose #+type: is ores.codegen.entity; its C++ domain type is
ores::<component>::domain::<central_entity>. Each row of the * Parts
table names a part shim (the C++ member name, first column) and the entity
model that backs it (second column). Each part must be an
ores.codegen.entity in the same component with a foreign key whose
:parent_entity: is the central entity and whose
:bump_parent_version:, :list_by:, :list_by_uuid: and
:list_by_as_of: are all true; a part that does not satisfy that fails
the load.
The family derives <family_singular>_key (copied from the central
entity's own key record), <family_singular>_item (the key, the central
row and one typed array per part) and <family_singular>_write (the
central change and one typed array of part changes per part), then the
four request/response pairs. Subjects use the family plural, so they do
not collide with the central entity's own derived subjects.
23.1. ores.codegen.service_registry
Catalogue of ORE Studio backend services. Each top-level heading is one service. Drives PostgreSQL GRANT scripts and shell variable declarations.
23.1.1. Frontmatter keywords
Minimal — the doc is self-describing via section PROPERTIES.
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.service_registry |
#+filetags |
yes | :codegen:service_registry:literate: |
23.1.2. Section hierarchy
#+begin_example
24. <service_name> — PROPERTIES: psql_var, env_key, iam_role,
description, email
** DML prefixes — unordered list of ores_{service}_ prefix strings
#+end_example
24.1. ores.codegen.module
An index grouping all entity docs in a namespace. Not a code-generation input in the strict sense; the generator does not process it. Provides an org-roam hub for navigation.
24.1.1. Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.module |
#+component |
yes | Short component name |
24.1.2. Section hierarchy
#+begin_example
25. Entities — | Entity | Brief | table (org-roam links in Entity column)
26. See also
#+end_example
27. Generator-config schemas
27.1. ores.codegen.facet_catalogue (retired)
Retired — declared every codegen profile: which templates each facet activated, the model types each template bound to, and how composite facet groups composed leaf facets. Superseded by the ores physical-space graph, where this information now lives directly on each facet's own node (its Archetypes table) instead of in one central file. Kept here for the historical schema shape.
27.1.1. Section hierarchy
#+begin_example
28. Facets
* <facet_name> :facet: — PROPERTIES: description, model_types ** Templates — | template | output | model_types (opt) | table
29. Facet groups
** <group_name> :facet_group: — PROPERTIES: description
| facet | include | table |
#+end_example
29.1. ores.codegen.component_catalogue
Maps each named component to its model-discovery roots. Read at startup by
manifest.py.
29.1.1. Section hierarchy
#+begin_example
30. Components
| name | models_dir | entity_glob | exclude_suffix | modeling_dir | table |
#+end_example
30.0.1. Column semantics
| Column | Description |
|---|---|
name |
Short component id (refdata, trading, …) |
models_dir |
Path to legacy JSON models directory |
entity_glob |
Glob pattern for JSON model files |
exclude_suffix |
Suffix to exclude (e.g. _domain_entity.json) or null |
modeling_dir |
Path to co-located org models; null if none |
30.1. ores.codegen.modeline_catalogue
MASD-style hierarchy of per-language editor modeline strings.
30.1.1. Section hierarchy
Uses MASD stereotypes throughout:
#+begin_example
31. ores.modelines module
* emacs :modeline_group: ** <language> :modeline: ** content :attribute:
:masd.codec.value: <modeline-string>
#+end_example
32. See also
- ores.codegen — the generator component.
- ores.codegen architecture — module list, data files, generation flow.
- Codegen patterns: choosing a model shape — which pattern to pick, and the neighbouring one it is mistaken for. The schema here gives each pattern's flags; that page gives the choice.
- Entity naming — the name every pattern gives the table, the type, the messages and the derived file.
- ores physical-space graph — profile → template/output mapping.
- component_catalogue.org — component discovery roots.
- modeline.org — editor modeline strings.