0035 - Provenance, written completely and read from four releases
Status: accepted
Context
The library wrote provenance that did not satisfy the rule of the specification it
claims to follow. The EML technical reference guide 2.3 (section 3.1, p. 40) says
the title of an activity parameter must have an equivalent in the activity
descriptor parameters; yet the operations wrote parameters titled input that
no canonical template declared, whole numbers as doubles, and the file a recipe
step had read nowhere. A graph of provenance drawn from such a package had to guess
which parameter was an input.
Reading was the other half. Activities come in four releases (RESQML 2.0.1, EML 2.1, 2.2, 2.3), with a template that may or may not be in the package, and a role that is stated only in the template. Some converters, such as UDAR with its NWDF tables, keep provenance in tables outside any activity, and a drawing that ties a dataset to its objects by a regular expression on the title looks right and is wrong.
Decision
- A
DataObjectParameterthat points to anActivityis read assubActivity. No class of parameter has that kind in the schemas; it is the way the library’s recipes already write a workflow’s steps. - A
TimeIndexParameteris read astimestamp, for the same reason. - The role of a parameter comes from the template, then from a named rule, else it
is
Undeclared. A role is never guessed from a title. The one built-in rule,energyml-build:input-output, readsinputandoutputin an activity written byenergyml-rust; it exists for the packages written before this decision, and its id is shown beside the role it gave. Rules are a registry, the caller’s first (ADR 0006). - Every canonical template declares
inputandinputFile. AninputFileparameter is a string whose value is<slot>: <path>, or<path>when no slot was named. A new package satisfies the rule of section 3.1. - Whole numbers are written as
IntegerQuantityParameter, as the canonical template declares them (Parameter::Integer, a breaking change of the enum). - A verbatim source is a public trait with a registry; the NWDF reader is public.
Its tables are recognised from column titles, one table per role (two are refused
as
SeveralTables, not merged), the objects of a key come from the mapping table and never from a title, and a key nothing resolves is shown as unresolved. When a process’s activity is stated twice and the two differ, both are kept and the disagreement is signalled. - A recipe draft rebuilt from a workflow is lossy, and says so. What it cannot restate is refused by name.
Consequences
- A package written from this version satisfies section 3.1 without an exception in
the template check; the check that excepted
inputis gone. - A package written before it still reads: its
inputparameters get their role from the built-in rule, with the rule’s id shown, andconformancesignals the parameters the template lacks. Nothing is refused for being old. - The rule of the registry (house rules, theme
provenance) reports what departs from a template; it never blocks a read. - A reader of an activity cannot tell a written integer from a written double in a package of another software: a number is read by the field present, and the conformance reports a difference of kind against the template.
- Replaying the Lutetia model changes its templates and activities; its lock file moves in the same release.
- Two tables of one role (two converted boreholes in one package) are refused until there is a way to tell the groups apart, which is a future case, not a guess.