welldotdocs
Guides

Serializing and sharing

Write a Well back to .well text with serializeWell, keep unknown members, check whether a well holds data, and redact sections before sharing a file.

serializeWell

import { serializeWell } from '@welldot/core';

const text = serializeWell(well); // a JSON string, ready to save as .well

serializeWell(well: Well): string writes the current format:

  • "version": "2.4" (the value of WELL_FORMAT_VERSION), whatever version the file was read from;
  • location as an object, never the v1 flat lat / lng / elevation;
  • no null and no undefined optional fields, as the spec requires (absent values), except inside x- members and @context, which are written as they are;
  • every root member the spec does not define (x- fields and blocks, foreign members) unchanged, after the spec blocks (extensibility).

The output is compact JSON. To store it indented, re-indent it:

const pretty = JSON.stringify(JSON.parse(serializeWell(well)), null, 2);

Round trips keep what you did not touch

parseWell keeps unknown members at every level, and serializeWell writes them back. A tool that reads a file, edits a field and saves it therefore preserves extensions it has never heard of:

import { parseWell, serializeWell } from '@welldot/core';

const well = parseWell(
  '{"version":2,"x-acme":{"asset":"A-7"},"bore_hole":[{"from":0,"to":60,"diameter":254,"x-acme-bit":"PDC"}],' +
    '"well_case":[],"reduction":[],"well_screen":[],"surface_case":[],"hole_fill":[],' +
    '"lithology":[],"fractures":[],"caves":[]}',
);
well.name = 'PT-07';
serializeWell(well);
// {"version":"2.4","name":"PT-07","bore_hole":[{"from":0,"to":60,"diameter":254,"x-acme-bit":"PDC"}],
//  …,"x-acme":{"asset":"A-7"}}
Spreading a well into a new object of only the fields you know ({ name, bore_hole, … }) drops unknown members. Edit the parsed object in place, or copy it whole with structuredClone.

Empty or not

Two helpers answer different questions:

Helpertrue when
isWellEmpty(well)There is nothing to draw: every construction and geology array is empty.
hasWellData(well)The well holds any data at all: a profile, identification, location, events, samples, permits or x- members. Blank strings and zeros do not count.

A registry record with a location and a permit but no construction has data (hasWellData is true) and nothing to draw (isWellEmpty is true). Both accept null and undefined.

calculatedWellDepth(well) returns the deepest to across the construction arrays, ignoring geology, or 0. Use it when well_depth is absent and you need the drilled depth (Depths and intervals).

Redacting before sharing

To publish a well without some of its data, such as a private owner's location or permits, use redactWell. It returns a copy with the hidden parts removed (arrays emptied, optional fields deleted), so the result is still a valid .well file.

import { redactWell, serializeWell } from '@welldot/core';

// Hide a whole section
const publicWell = redactWell(well, { operation: false });

// Or individual fields
const anonymous = redactWell(well, {
  location: false,
  permits: false,
  meters: false,
});

serializeWell(publicWell);

Keys are the seven sections or the fields within them; false hides, a missing key stays visible, and hiding a section hides all its fields:

SectionFields
generalidentification, location, obs, attachments
constructivebore_hole, surface_case, well_case, reduction, well_screen, hole_fill, centralizers, cement_pad
geologylithology, fractures, caves
hydrodynamichydrodynamic_events, aquifer_analysis
history(the whole section)
operationpump_installations, meters, operating_regime, production, permits
water_quality(the whole section)

The same structure is exported as SECTION_KEYS, VISIBILITY_TREE and VISIBILITY_LEAF_KEYS, for building a visibility form.

References from visible records to hidden ones are left as they are; they become dangling references, which readers report as warnings (dangling references). Unknown root members (x- blocks) are kept only when nothing is hidden, since redactWell cannot know whether they are private.

Related

Parsing and validating

Unit conversion