House rules
Energistics standards leave questions open: a producer may omit a field, two readings of a sentence are possible, a unit string means different things in two releases. Where the specification is silent, ambiguous or only interpreted, this library makes a decision. A house rule is such a decision, when it changes what a user sees, reads or is refused and no specification dictates it word for word.
Those decisions are not left scattered in code comments. They are in a registry,
the energyml-rules crate, so that:
- a user can ask the tool what it decided, and why;
- code cites a rule by an identifier, and a misspelt identifier does not compile;
- an interface can show “this is a house rule” next to the answer it affects.
What a rule says
Each rule is a record in a TOML file, one file per theme:
| Field | Meaning |
|---|---|
id | house/<theme>/<name> |
status | active (decided and coded), designed (decided, not coded yet - says so on the button that shows it), superseded (kept for history) |
| stance | what the specification does: silent, ambiguous, interpreted, extends (the result is no longer strict standard) or restates (a cited text made executable) |
| level, text, reason | what is decided, at which level, and why |
| references | quoted strings: a specification document, a page or paragraph, or a path in this repository. They are never read at run time |
| anchors | where the rule shows (a view, an object, a command) |
English is the source and is always present. A translation is optional per rule; a rule without one answers in English and says so.
A rule that changes meaning gets a new id that supersedes the old one, which
becomes superseded: history is information. A new rule enters the registry in
the same change as the decision or the code that makes it.
The crate is a leaf with no runtime dependency (WebAssembly included): the TOML is compiled by a build script into statics, and nothing is parsed when a program runs. The loader refuses a malformed rule with a named error (file, rule, field).
Reading them
energyml rules --house # all of them
energyml rules --house --theme colour # one theme
energyml rules --house --id <rule-id>
energyml rules --house --anchor <anchor> # the rules that apply where something shows
energyml rules --house --json
Themes today include attachments, colour, inheritance of properties, series,
statistics, tables, the well, directional surveys, properties and provenance (energyml rules --house lists the ten themes of this release).
Statistics, scales and gaps
Along the measured depth, a gap wider than 3 median steps is never bridged, and a jump of the value wider than 10 median steps of its variation is signalled as a seam. A logarithmic scale is proposed when the values span 3 decades, and automatic bounds are the 1st and 99th percentiles. Read them with energyml rules --house --theme stats; the decisions are in ADR 0027.
Around the well
Where a trajectory is evaluated, the direction at a knot of a linear line is that of the interval that ends there, and a hole under 1 degree of inclination has no high side, so its frame is refused at that node by name. A true vertical depth along a well is counted below the MD datum, and a convention the file does not state (the sense of angles, the axes of a per-node matrix) is declared by the caller, never guessed. Read them with energyml rules --house --theme well; the decisions are in ADR 0031, ADR 0032, ADR 0033 and ADR 0041.
Tables and links
A column links to another table by one qualifier facet that holds the complete uri of the target (convention B, ADR 0029); the target table has one key column, by which a value names a row, or none, and then a value names a row by its rank from 0. A link that leads nowhere is an error, a key held by two rows, a declaration made in a description or a title, and a uri that names no object of the package are warnings, and a link that cannot be checked is said to be uncheckable, never passed. Read them with energyml rules --house --theme table; the decisions are in ADR 0030 and the way to use them in Tables, keys and links.
Directional surveys
A survey that states no north is placed only with a north the caller declares, which is carried in the result and never written into the package, and a declaration never overrules a north the file states. A survey in true or magnetic north is turned to grid north by the convergence and the declination the file states, and a station left out as rejected is left out only when the caller declares so. A RESQML 2.0.1 deviation survey is read from the north of its projected CRS. Read them with energyml rules --house --theme survey; the decisions are in ADR 0034.
Properties
Two properties of one quantity on one support, told apart only by a vertical and a lateral direction facet, are expected to keep the order a layered medium gives them: for a resistivity, the vertical value is not below the lateral one. When more than 5 % of their pairs have a vertical value under 0.95 times the lateral one, the check report carries a warning, never an error: the specification names the directions and says nothing of the order of their values, so the expectation is ours and a package that breaks it is kept. A direction written as an extension value (nwdf:vertical) is not guessed: the check is then unverifiable, unless the caller declares which property is vertical. Read it with energyml rules --house --theme property; the decision is in ADR 0036.
Provenance
An activity is held to the template its ActivityDescriptor names: each parameter has an equivalent of the same title, of an allowed kind and in the allowed numbers, and a departure is a warning in the check report, never a refusal, because the activity is read and drawn all the same. The role of a parameter (input, output, sub-activity) comes from its template or from a named rule, and is undeclared otherwise: it is never guessed from a title. What this library writes, it declares in its own templates, the files a step read included. Read them with energyml rules --house --theme provenance; the decisions are in ADR 0035.
The full list
The complete, current list is generated from the registry: run
energyml rules --house (add --json for a machine-readable form). It is
deliberately not copied by hand here, because a hand-copied list is out of date
the day a rule changes.
Why this matters
A data format that says nothing about a case still gets a producer’s answer, and a tool that quietly picks another one yields results nobody can explain. Registering the choice, with its reason and its status, lets you disagree with it explicitly. See also ADR 0005.