The specification
The specification is the standard that defines the .well format. It is written as plain Markdown in the spec/ folder of the repository and rendered on this site as it is, with heading anchors and links adapted for the web. Everything else on this site explains it; when a guide and the spec seem to disagree, the spec is right.
The current revision is 2.4.
The documents
| Document | What it covers |
|---|---|
| Overview | The changes in each revision, the purpose of the format, its design principles and its known limitations. |
| Format reference | Top-level fields, versioning and deprecation, datetimes, recommended vocabularies, well_id, location, units, profiles, extensibility, cross-references and precision. |
| Object schemas | Every object: construction, geology, hydrodynamic events, aquifer analysis, history logs, pumps, permits, meters, production, operating regime, and a complete example. |
| Water quality | Water samples and results, their units, the parameter vocabulary and regulatory profiles. |
| Interoperability | The reserved JSON-LD context, the mapping to GroundWater ML 2 and JSON Schema validation. |
| FGDC textures | The 282 lithology pattern codes. |
| v1 (archived) | The first version, kept for reference. v2 readers upgrade v1 files on read. |
How to read it
The spec uses the keywords MUST, SHOULD and MAY in their usual standards sense: MUST is a requirement, SHOULD a strong recommendation, MAY an option. Sections marked (since v2.x) were added in that revision.
If you are new to the format, start with What is .well? and the concepts, then come back to the spec for the exact rules.
How it relates to the code
@welldot/coreimplements the spec. Its tests compare the vocabulary tables in the spec with the published constants and parse the spec's complete example, so the two cannot drift apart silently.- The JSON Schema is generated from
@welldot/coreand published athttps://welldot.org/schema/v2/well.schema.json. - The object reference is generated from the schema and links back to the spec sections.
How it changes
Changes to the format start as an issue on GitHub. The spec text is edited first, then the implementation and these docs, in the same change (update rules). Each revision adds a "Changes in v2.x" section to the overview; the changelog links to them.
The spec files are licensed under Apache 2.0, like the rest of the project.