Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Schemas and supported versions

Supported versions

The library reads and writes these Energistics data schemas. Every version is a separate generated crate under generated/, and energyml-schemas registers them in one Registry (energyml_schemas::all(), or energyml::schemas::all() through the energyml crate) - those whose Cargo feature is on.

all() registers every generated type on each call, which is a cost to pay once, not per request. A program that answers many requests takes energyml_schemas::shared() instead: the same registry, built on the first call and handed out as an Arc afterwards (the compiled-in crates cannot change during a run, so it is never stale). Keep all() when you need an owned registry to add to.

StandardVersions
RESQML2.0.1, 2.2 (and the development drop 2.2_dev3, see below)
EML (Energistics common)2.0, 2.1, 2.2, 2.3
WITSML2.0, 2.1
PRODML2.0, 2.2, 2.3

Choosing the versions you compile

Each version is a Cargo feature, spelled as Energistics spells a qualified type:

StandardVersionsFeatures
EML2.0, 2.1, 2.2, 2.3eml20, eml21, eml22, eml23
RESQML2.0.1, 2.2, 2.2_dev3resqml20 (the 2.0.1 release), resqml22, resqml22dev3
WITSML2.0, 2.1witsml20, witsml21
PRODML2.0, 2.2, 2.3prodml20, prodml22, prodml23

The families eml, resqml, witsml, prodml and all switch several on. A version brings the EML version it is built on (resqml22 brings eml23, resqml20 brings eml20). The energyml crate turns no version on by itself, so a dependency says what it reads:

energyml = { version = "0.1", features = ["resqml22"] }   # or ["all"]

energyml-schemas itself defaults to all (for the tools that want everything); the energyml command and the Python wheel ship every version. A version that is not compiled is a named refusal (“RESQML 2.2 is not compiled in: enable the resqml22 feature”), never a half read. The façade’s build feature (and providers, which implies it) turns on the four versions it writes: RESQML 2.2, EML 2.3, WITSML 2.1 and PRODML 2.3.

Everything above the generated layer - units, coordinate systems, value arrays, geometry, exports - is written once for all versions. A concept keeps its version-independent name, so a reader for a concept serves every release that keeps it; a release that respells the inside of a type is handled by a reader that accepts both spellings.

The development drop resqml 2.2_dev3 is registered so that files written against it before the 2.2 publication still open. It is read, never offered: no new object is created in it, because most of its types carry the very qualified type of a released one, and the rest exist only in the drop and no released 2.2 reader knows them. energyml relabel can correct a package that declares the release while holding drop content.

Adding an Energistics release costs a generated crate, one dependency, one feature, one row of KNOWN_VERSIONS and one register line in energyml-schemas; the storage, domain and geometry layers name no version. A test checks that the registry and the list of versions the code is generated from agree.

Where the generated code comes from

The Rust under generated/ is produced mechanically from the official Energistics XSD files by an internal tool that is not part of this repository. Generated files are committed and are never edited by hand; a robot proposes changes to them as pull requests. generated/schemas.lock records the SHA-256 of each input schema so a reviewer can tell which input a file was generated from. It contains no Energistics schema content.

The generated code is public because it is a derived work, produced under the Energistics Product License Agreement; the XSD files themselves are obtained from the official publisher (The Open Group) and are not redistributed here.

Each generated crate carries a NOTICE. TODO(verify): final wording and any condition The Open Group or Energistics attaches to naming crates after their standards.

Notice

This product includes software developed by Geosiris. The following Energistics(R) products were used in the creation of this work: RESQML(TM) Data Schema v2.0.1 and v2.2, WITSML(TM) Data Schema v2.0 and v2.1, PRODML(TM) Data Schema v2.0, v2.2 and v2.3, Energistics common v2.0-v2.3, Energistics Transfer Protocol (ETP) v1.2. Energistics(R), WITSML(TM), PRODML(TM) and RESQML(TM) are trademarks or registered trademarks of Energistics Consortium, Inc. All rights in the Energistics standards, or any portion thereof, which remain in this work remain with Energistics and are subject to the Energistics Product License Agreement (https://www.energistics.org/product-license-agreement).

TODO(verify): this text follows the licence’s requirement for derived works; confirm it against the NOTICE file of the repository, which is authoritative.

Disclaimer

This project is not affiliated with or endorsed by Energistics or The Open Group. RESQML, WITSML, PRODML and Energistics are trademarks of their owners. “EnergyML” is used here as the common name of the family of standards.

The ETP (Energistics Transfer Protocol) implementation lives in a separate repository, retp. ADR 0001 explains why generated code is committed.