Configuration screen standard

A configuration screen is a screen whose subject is the records of one configuration kind: it lists them, opens one, and reads and changes its sections. The pricing engine configuration and the engine run settings are configuration screens.

These are not configuration screens, and this standard does not govern them:

• a feed, which the Feed screen standard governs;
• a plain record such as a currency, which the record standard governs;
• the report definition and the run, which are state rather than configuration;
• a wizard step that imports or exports a file, though the import step of a configuration follows Import.

One word per idea, in code, on screen and in conversation.

Never print run settings on a configuration screen. It names an internal entity, risk_report_config, and not a configuration.

A report definition binds one configuration per kind, as sibling rows of report_configuration. A configuration is reached through a configuration row, and its kind comes from configuration_type, which carries the ORE root element and, where one exists, the run parameter that names the file.

The family has one exception that the screen must know. The ORE Setup block is a single document split across two kinds: risk_report_config holds the run's paths, currency, market kind and scope, and engine_settings holds the engine choices. Neither names a file of its own, so configuration_type.run_parameter is null for both. The pricing engine configuration is a document of its own, and the Setup block names it through pricingEnginesFile.

The screen name is the kind's subject. Where the subject alone would name the instances rather than the configuration, the name carries the word configuration. Two kinds never differ only by that word, and no kind is named for one thing inside it.

The list title is the plural of the screen name, except for a mass noun such as Engine run settings and Reference data, which take the same title in both numbers.

Three words are fixed by this table and replace the earlier screen words:

• Pricing engines becomes Product pricing. It names the job: how each product type is priced.
• Engine settings becomes Engine run settings. It does not hold the settings of a pricing engine.
• The pricing page has no Settings tab and no Parameters tab. A product's parameters live in its workbench, and the document-level parameters have a Global parameters tab.

A product has parameters, not settings. The words model settings and engine settings never appear in a pricing engine configuration: the model and the engine each take parameters, and the engine run settings are a configuration of their own, named by their own screen. A label that says settings on a product screen is a gap, because it points the reader at the wrong file.

The model names, the configuration type codes and the API routes keep their spelling. Only the screen words change.

A kind is declared once, and every part of its screen reads the declaration.

The list follows the record standard without a variation: breadcrumb, the plural title, one sentence, Refresh, Workflows and Add, the server search, the filters, the paged table and the four states.

A configuration list adds three rules.

1. A row shows what the configuration holds: the count of its sections that are set, or the count of rows in its principal collection. It never shows a count that needs a read for every row unless the server returns the counts in one read.
2. A filter narrows by Used by reports: bound by a report, or bound by none.
3. Where the kind has a lifecycle, a filter narrows by status, and a row marks the configuration that is official for a cycle.

The list never shows the ORE root element, the configuration type code or a UUID. The kind is what the screen is about; a person does not need its schema name.

The page follows the record standard's header, access mark and actions, and adds this tab order, which is fixed:

1. Details.
2. Global parameters, where the kind has document-level parameters.
3. One tab per section, in the order the kind declares them.
4. Used by.
5. History.

Details is always first and History is always last. A tab that does not apply is not drawn. A kind with no sections has no section tabs.

The header carries the name as the title, the version, what the configuration holds, the count of reports that bind it, the access mark, and the actions the person may take.

Details holds the name, the party, the description, the version, the reporting configuration row it is bound through and the last-changed line. It opens with the sentence that says what the configuration decides, and it ends with the related configurations card.

A field set earns its own section when it has its own multiplicity, change reason or reader. A section is one of two shapes, and the shape decides how it is changed.

A group that has no row shows not set, and the engine uses its default for every parameter in it. A collection with no rows says so, and adds a row the way the record standard draws a parts table.

Every section declares whether it changes the numbers a run computes. The declaration drives the label on the section, the warning on a change and the lifecycle.

• Every parameter shows the value in force: the set value, or Default: X. The value the engine uses is never hidden.
• The documentation is collapsed under the parameter. A button opens or closes it for the whole section.
• Simple shows the label, the value and the short help. Advanced adds the schema entry: the ORE path, the format, the release that introduced the parameter and the release that removed it. It is the same switch as the feed screens, and the choice is remembered for every screen that offers it.
• Two filters narrow a long section: Set in this configuration and Changes the numbers.
• A parameter with no documentation entry shows its ORE name and a note. It is never hidden, because a gap in the data must be visible.

A collection row is an element with its own identity, and its documentation has two levels.

• The row opens a card or a workbench pane that says what the element is: its label, its code, what it is for, the instrument it maps to, its asset class, and the source of the words. A row that shows a name and a count alone is not enough.
• The card lists the settings of that element as rows, each with the same collapsible documentation and the same Simple and Advanced switch as a group. Advanced adds the schema entry.
• A setting with no documentation entry shows its ORE name and a note.

A group and a collection offer the same documentation: the label, the help, the long description, the default, the format and, under Advanced, the ORE path and the releases. No configuration screen is exempt, and no section is exempt.

The switch is one switch. It appears wherever a parameter is shown, its choice is remembered for every screen that offers it, and a card opened from a row carries it too.

A screen that shows a value without its documentation is a gap, not a variation. The conformance table records it as a gap.

The row a parameter is drawn in, the words it carries and the control it takes are not a configuration's alone: a convention term is drawn the same way on a record page. The ORE element and leaf screen standard states them once, with the exact words, and this page does not restate them.

• Edit turns the section's card into a form in place. There is no dialog, so nothing hides the documentation.
• The first option of every control is the default, which unsets the parameter.
• A parameter that differs from the saved value is marked, and the foot of the card counts the changes.
• The foot states the reach: how many reports the section reaches, and the rule.
• A section that changes the numbers states that it does, and asks for a change reason and a commentary. See The lifecycle for what Save then does.
• Save claims the version the page read. A section that changed since is a conflict, and the page offers to read it again.
• Save writes the section and moves the version of the whole configuration in the same transaction.
• Cancel leaves the card as it was, and a close with changes asks before it discards them.

• A row is added, changed and removed in the record standard's dialog. A collection is not edited in place.
• The dialog shows the documentation of the choice, at the same depth as a group: collapsed under the setting, with Simple and Advanced. Where a choice depends on another (a model on a product type, an engine on a model), it offers only the choices that belong together.
• A change that drops a row or a parameter states what will be dropped before it is dropped. Nothing is dropped silently.
• The save states the difference: added, changed and removed.
• The save claims the configuration's version. A stale save is a conflict, and the dialog offers to read again.
• The save asks for a change reason and a commentary, and follows the lifecycle rule for the section it touches.

One contract serves every ORE leaf, and it is data, not text in a screen.

A documentation entry carries:

• the schema and the XPath that identify the leaf;
• the label and the short help;
• the long description, which says what each value means;
• the default;
• the format;
• the release that introduced the parameter, and the release that removed it, empty while ORE still reads it;
• the kind of value, its closed list where it has one, and its range;
• whether it changes the numbers;
• the source of the words, where they are not ORE's.

Three rules follow.

1. The screen never holds ORE text. A missing entry shows the ORE name and a note.
2. The documentation validates nothing. The type, the range and the check of a value stay with the data model.
3. The contract holds no table of values. A value that names an entity, such as a calendar or a currency, is bound to that entity by the control, and the description gives examples.

A parameter whose meaning depends on an element pair, such as a pricing parameter that belongs to a model and an engine, keys its entry by the schema, the XPath and the pair. The screen looks it up by the same key.

A configuration page says which reports bind it, and never guesses.

• Used by lists each report with a link to its page, and the rule: a change reaches the next run of each report below, and a run already produced keeps what it ran with.
• The read is reporting.v1.report_configurations.list_by_configuration_id.
• A run records the version of each configuration it read. Until it does, the page cannot name the runs a change reached, and it says so.
• When the read fails, the tab says so. It does not show an empty list as if nothing bound the configuration.

History is the shared timeline, as the entity specification draws it: the event chart, the rail under day headings, the collapsed detail, the current-version emblem and the Hide system activity toggle.

• A change to a section is one entry that names the section and its part version.
• The entry moves the version of the whole configuration, because a write to any section makes the next version of the central row.
• A proposal that waits shows at the top, and is not a version in force.
• Revert is offered on every entry that is not current. It writes the values the section had before as a new version. On a numbers-changing section it writes them as a proposal.

The lifecycle attaches to a section, not to a kind, because one configuration may hold both kinds of section.

A kind declares whether it has an official version for a cycle, and which approval parts sign it. A section declares whether it changes the numbers.

The rule:

1. On a configuration that at least one report binds, a write to a numbers-changing section is a proposal. The version in force stays in force until the proposal is signed off, and the proposal never rewrites the rows a run reads.
2. On the same configuration, a write to an operational section lands directly, with a change reason and a history entry.
3. A configuration that no report binds is a draft, and every section changes in place. It becomes governed the moment a report binds it.
4. A numbers-changing section never changes in place. On an approved configuration, Edit is Propose a change for that section.
5. A proposal names the version it was written on. The version in force keeps its section versions until the sign-off completes.
6. The person who proposed a change cannot sign it off, even when they hold a part.
7. Making a proposal official changes the section versions in force in one step.
8. An operational change moves the central version and leaves every section version as it was.
9. A revert follows the same rule as the change it reverts.

A kind that has no lifecycle yet is a gap, not an exception: the screen still edits in place, and the history still records the change. The standard names the gap on the kind's conformance line.

The import of a configuration file is the standard Import of the Record screen standard, section Import and Export: one button on the list header, one shared dialog, and the server's ore.v1.ops.preview_<document>_import and import_<document> behind it (decided 2026-10-25). It follows five steps, on the standard steps UI.

1. Choose the file. The screen accepts the kind's root element. A file of another kind is refused, and the refusal names the root element it found.
2. Read what the file holds. The parse happens on the server, so a browser parser cannot drift. The step states the counts before anything is written.
3. Read what the system does not know. Three lists, each only when not empty: a product or element type with no vocabulary row, an element the tables cannot hold, and a duplicate. An element with no column is dropped and named; a duplicate is resolved by the person.
4. Choose the target. A new configuration, or an existing one. A file put into an official configuration is a proposal; a file put into a draft changes the draft in place.
5. Read the difference and review. Added, changed and removed, with the removed rows first and Keep it as the default, because a file that omits a row usually leaves it out by accident. The review states the reach, asks for a change reason and a commentary, and claims the version read.

A file never becomes official directly. Nothing is dropped in silence, and every drop is named in the review.

The export is the standard Export of the record screen standard, on the record header, because a configuration is one document: the server's ore.v1.ops.export_<document> writes the kind's ORE document from the configuration, in the order the rows carry, and the browser saves it.

A kind names its file in ores_reporting_file_types_tbl, the row whose configuration_type_code matches it, and is_default holds when the kind has several. A run may override the name through the parameter that configuration_type.run_parameter records. A kind with no row has no document, and the pair is not drawn for it.

Every configuration page answers two questions before the person asks them.

1. What this configuration decides. One sentence at the top of Details, in the pattern "It decides X. It does not decide Y; that is <the other configuration>." The second half is required only where a person is likely to confuse the kind with another, and it always links to the other.
2. Related configurations. A card that lists the other kinds the same report binds, one row each: the screen name, the configuration this report binds, a one-line statement of what it decides, and a link. A kind with no screen yet says No screen yet, and the row stays, because the relationship is the point.

The link goes both ways. A page that names another configuration links to it.

The list has the record standard's four states: loading, loading again with dimmed rows, none yet, nothing matches with a way to clear, and an error in place with Retry.

A configuration adds these states.

A configuration belongs to a party and is editable only there. From another party the page is read only, says so, and offers a switch to the owning party. The server refuses the write and the page shows the refusal in the server's words.

An action the person may not take is not drawn. It is not drawn disabled.

1. Seed or confirm the configuration_type row: code, name, ORE root element and run parameter.
2. Declare the sections: order, shape, parameters, whether each changes the numbers, and the lifecycle.
3. Seed the documentation entries for every leaf the sections show.
4. Build the list and the page from the shared parts. Do not copy a screen.
5. Add Used by on the reach read and History on the shared timeline.
6. Add the related configurations card and the sentence that says what the kind decides.
7. Add the import where the kind has a document a person brings in.
8. Run the screen review checklist and record each gap on the kind's conformance line.

Measured on 2026-10-24. This is the gap list the tasks close; it is not a licence to differ.

The two configuration prototypes were updated in PR #3720 and draw the words, the sentence, the related card and the section lifecycle. Two changes remain, and they belong to the pricing application task:

• The pricing prototype's product and parameter dialogs must show the documentation, collapsed, with the schema panel under Simple and Advanced.
• The importing prototype must follow Import in the same words, including the server parse. The engine run settings cannot set the example: they have no document of their own, only a section of the run's ore.xml.

The report page prototype is the third place a person meets both configurations. It belongs to the story See and change everything a report runs — the remaining work, and it must use the words in this page.