Codegen input org-file schema reference
Table of Contents
- Summary
- Entity-model schemas
- Flags — PROPERTIES: schema, product, component, has_tenant_id
- Primary key — PROPERTIES: column, type, cpp_type
- Natural keys — (optional) list of column names used as natural keys
- Columns
- SQL
- C++
- See also — org-roam links
- Primary key — PROPERTIES: column, type, is_text
- Columns
- Artefact indexes — (optional)
- See also
- Includes — #+begin_src cpp :name includes
- Fields
- Left — PROPERTIES: column, column_short, column_title,
- Right — same shape as * Left
- Columns
- SQL
- Repository — PROPERTIES: name_singular_short, name_short,
- C++
- See also
- <service_name> — PROPERTIES: psql_var, env_key, iam_role,
- Entities — | Entity | Brief | table (org-roam links in Entity column)
- See also
- Generator-config schemas
- Facets
- Facet groups
- Components
- ores.modelines module
- 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, Qt).
- Generator-config types — org files that configure the generator itself (profiles, components, modelines).
For the code that reads these files see ores.codegen architecture.
Summary
Entity-model types
| Type | Compass type | Count | Primary output |
|---|---|---|---|
ores.codegen.entity |
entity_org |
~83 | C++ domain class + SQL table + Qt UI |
ores.codegen.lookup_entity |
lookup_entity |
~15 | SQL artefact table (batch-loaded, no UI) |
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.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 |
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 |
Entity-model schemas
ores.codegen.entity
Full-fidelity entity: drives C++ (domain class, mapper, repo, service, Qt widgets) and SQL (table DDL, triggers, constraints). The largest doc type (~83 files).
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}: |
Section hierarchy
#+begin_example
Flags — PROPERTIES: schema, product, component, has_tenant_id
Primary key — PROPERTIES: column, type, cpp_type
Natural keys — (optional) list of column names used as natural keys
Columns
** <column_name> — PROPERTIES: type, cpp_type, nullable, default (opt)
SQL
** Flags — PROPERTIES: tablename
C++
* Flags — PROPERTIES: component_include, component_core (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 * Qt — PROPERTIES: many (domain_class, protocol_include, …) ** Detail fields — | field | label | widget | type | is_key | view_group (opt) | … | table * Columns (Qt model)— | enum_name | field | header | type | width | table ** Custom repository methods — freeform
See also — org-roam links
#+end_example
view_group (Detail fields)
An optional cell on each Detail fields row naming which Qt
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 Qt detail dialog is its only consumer today.
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.
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.).
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 |
Section hierarchy
#+begin_example
Primary key — PROPERTIES: column, type, is_text
Columns
** <column_name> — PROPERTIES: type, nullable, default (opt)
Artefact indexes — (optional)
** <index_name> — PROPERTIES: columns (space-separated list)
See also
#+end_example
ores.codegen.field_group
A C++ struct fragment composed into one or more parent entity structs. Used to
keep each rfl::Literal below the MSVC C1202 complexity threshold.
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 |
Section hierarchy
#+begin_example
Includes — #+begin_src cpp :name includes
Fields
** <field_name> — PROPERTIES: cpp_type #+end_example
ores.codegen.table (retired)
Was an SQL-only reference-data table with no C++ or Qt generation. 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++/Qt layer, e.g. currency) are expressed as an
ores.codegen.entity with no ** Qt section rather than a distinct type.
ores.codegen.junction
A SQL join table and its C++ counterpart (struct + repository). Has two
mandatory FK sides (* Left, * Right) and optional extra columns.
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 |
Section hierarchy
#+begin_example
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
Right — same shape as * Left
Columns
** <column_name> — PROPERTIES: type, cpp_type, nullable
SQL
** Flags — PROPERTIES: tablename
Repository — PROPERTIES: name_singular_short, name_short,
name_singular_words, name_words, order_column
C++
* Domain includes — #+begin_src cpp :name includes * Entity includes — #+begin_src cpp :name includes * Conventions — PROPERTIES: iterator_var * Table display — | column | header | table
See also
#+end_example
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.
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: |
Section hierarchy
#+begin_example
<service_name> — PROPERTIES: psql_var, env_key, iam_role,
description, email
** DML prefixes — unordered list of ores_{service}_ prefix strings
#+end_example
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.
Frontmatter keywords
| Keyword | Required | Notes |
|---|---|---|
#+type |
yes | ores.codegen.module |
#+component |
yes | Short component name |
Section hierarchy
#+begin_example
Entities — | Entity | Brief | table (org-roam links in Entity column)
See also
#+end_example
Generator-config schemas
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.
Section hierarchy
#+begin_example
Facets
* <facet_name> :facet: — PROPERTIES: description, model_types ** Templates — | template | output | model_types (opt) | table
Facet groups
** <group_name> :facet_group: — PROPERTIES: description
| facet | include | table |
#+end_example
ores.codegen.component_catalogue
Maps each named component to its model-discovery roots. Read at startup by
manifest.py.
Section hierarchy
#+begin_example
Components
| name | models_dir | entity_glob | exclude_suffix | modeling_dir | table |
#+end_example
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 |
ores.codegen.modeline_catalogue
MASD-style hierarchy of per-language editor modeline strings.
Section hierarchy
Uses MASD stereotypes throughout:
#+begin_example
ores.modelines module
* emacs :modeline_group: ** <language> :modeline: ** content :attribute:
:masd.codec.value: <modeline-string>
#+end_example
See also
- ores.codegen — the generator component.
- ores.codegen architecture — module list, data files, generation flow.
- ores physical-space graph — profile → template/output mapping.
- component_catalogue.org — component discovery roots.
- modeline.org — editor modeline strings.