# 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](/format/spec/v2/format-reference#extensibility).

## Three kinds of extension

**Fields.** Any object can carry fields whose names start with `x-`. Their content needs no prefix ([custom fields](/format/spec/v2/format-reference#custom-fields--x--prefix)).

```json
{
  "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](/format/spec/v2/format-reference#custom-top-level-blocks--x--prefix-required)).

```json
{
  "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](/format/spec/v2/format-reference#custom-vocabulary-values--x--prefix)).

## 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](/format/spec/v2/overview#design-principles), "Preserve unknown members"). Dropping them on save is a bug.

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

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

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

```ts
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](/format/spec/v2/format-reference#vocabulary-value-promotion)). [Extending the format](/format/guides/extending) explains when to extend locally and when to propose a change.

## Related: offline packages

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](/format/spec/v2/format-reference#offline-packaging-since-v24)).