Extending for your own needs

Sooner or later a project needs something the spec does not define: an internal asset code, a field the local regulator asks for, a measurement nobody else takes. This guide shows how to add it without breaking other tools, and how to get it into the format when it is useful to everyone.

Decide where the data belongs

Before adding anything, search the object reference and the recommended vocabularies. Many needs are already covered: free-text notes and obs, attachments for documents, open vocabularies that accept any value.

A local extension

Use the x- prefix, with your organization's name, on a field or a whole block (Extensibility):

{
  "version": "2.4",
  "name": "PT-07",
  "x-acme-asset": { "code": "ACM-PT-07", "cost_center": "4410" },
  "well_case": [
    {
      "from": 0,
      "to": 40,
      "type": "carbon_steel",
      "diameter": 219,
      "x-acme-batch": "B-2291"
    }
  ]
}

• Prefix with your name (x-acme-…) so you do not collide with another tool's x-custom (recommended since 2.4).
• Keep units SI and names self-describing, as the rest of the format does (naming rules).
• Do not use an extension to restate a value the spec already holds; two sources for one fact will drift.

Every conforming reader keeps your extension and writes it back unchanged, so the file can pass through other tools safely. Extensibility explains the rule.

A new value in an open vocabulary

Write it with the prefix: "drilling_method": "x-jetting", "category": "x-site_visit" (custom vocabulary values). Closed vocabularies, such as hole_fill[].type, cannot be extended this way; a new value there needs a spec change.

Requirements for a group: profiles

When an agency or a monitoring network needs every file to carry certain fields or values, publish a profile: a JSON Schema at an HTTPS address that files list in profiles. The profile can require your x- extension, so the extension becomes part of the agreement without changing the core format (profile schema requirements).

Propose a change to the format

If an extension would help most people who record wells, propose it for the spec.

A new optional field ships in a minor revision and never breaks existing files (deprecation policy). An x- vocabulary value that is adopted stays equivalent to the new value until the next major version (vocabulary value promotion).