Concepts

Extensibility

How to carry data the spec does not define, with x- fields, x- blocks and x- vocabulary values, and why every reader must keep them.

No format can foresee every field a project needs. .well reserves the x- prefix for data the spec does not define, and requires every reader to keep that data untouched. A tool can add its own information without breaking any other tool, and the information survives a round trip through software that does not understand it.

The rules are in Extensibility.

Three kinds of extension

Fields. Any object can carry fields whose names start with x-. Their content needs no prefix (custom fields).

{
  "id": "evt-07",
  "type": "constant_rate",
  "datetime": "2006-03-14T08:00:00-03:00",
  "x-siagas": { "registro": "SP-0042819" }
}

Top-level blocks. Whole blocks the spec does not define must start with x-, for example a block of gas readings or geophysical logs (custom top-level blocks).

{
  "version": "2.4",
  "x-acme-gas_monitoring": [
    { "datetime": "2025-02-01T09:00:00-03:00", "ch4_pct": 0.2 }
  ]
}

Vocabulary values. In an open vocabulary, a value outside the recommended list should start with x-, such as "type": "x-slug_test" for a hydrodynamic event (custom vocabulary values).

Name your extensions after yourself

Since 2.4 the spec recommends x-<vendor>-<name>, for example x-welldot-example or x-acme-gas_monitoring. Two tools that both invent x-custom would collide; two that use their own name do not.

Readers keep what they do not understand

A reader must preserve x- fields and blocks it does not recognize and write them back unchanged. The same applies to any other member it does not know, such as a field added by a newer revision of the spec (design principles, "Preserve unknown members"). Dropping them on save is a bug.

Read the file, change what you need, and write every other member back as it was. parseWell and serializeWell in @welldot/core do this.

const well = parseWell(text);
well.name = 'PT-01 (renamed)';
const out = serializeWell(well); // x- members are still there

Don't

Rebuild the object from the fields your program knows. Every x- member and every newer field is lost.

const { version, name, bore_hole } = JSON.parse(text);
const out = JSON.stringify({ version, name, bore_hole });

Fields without the prefix

A field that is neither in the spec nor prefixed is "technically non-conformant": readers must not reject the file, but should warn. Use the prefix for anything you add.

Extensions are a path into the spec

An extension that many people need can become part of the format. A revision adopts the field or value, and for vocabularies the x- form stays equivalent until the next major version (vocabulary value promotion). Extending the format explains when to extend locally and when to propose a change.

Attachments are referenced by URL. For archives and regulators, a .well file can travel with its documents in a ZIP package with the .wellz extension. The .well file inside is an ordinary file (offline packaging).

Versions and deprecation