@bedrock-engineer/bro-xml-parser

Pre-1.0: This library is under active development. Minor versions may include breaking changes.

TypeScript parser library for Dutch Basisregistratie Ondergrond (BRO) XML data, focussing on geotechnical and geological data.

The BRO contains many registration object types. This library currently only covers five:

1. CPT (Cone Penetration Test)
2. BHR-GT (Geotechnical Borehole)
3. BHR-G (Geological Borehole)
4. GMW (Groundwater Monitoring Well)
5. GLD (Groundwater Level)

Support for more registration object types is desired but not our curent focus. PRs are welcome.

Live demo: bro.bedrock.engineer (source)

Why the web?

Geoscience and hydrology tooling leans heavily on Python. While Python and its scientific and geospatial ecosystem is unmatched for analysis and calculation, it is not the most suitable platform for displaying the contents of BRO/XML and being able to distribute that. Here, the web is unbeatable and the web's language is JavaScript.

Why TypeScript, then? Mostly a quality-of-life choice for developers. The BRO/XML schema is encoded as types so the shape of every parsed object is known while you write it. This gives useful autocompletion and lets the compiler catch mistakes before. It makes the parser pleasant to build on.

Installation

No dependencies in the browser.

npm install @bedrock-engineer/bro-xml-parser

For use in node.js, you need to install two extra dependencies.

npm install @xmldom/xmldom fontoxpath

Usage

Browser (zero dependencies):

import { BROParser, XMLAdapter } from "@bedrock-engineer/bro-xml-parser";

const parser = new BROParser(new XMLAdapter());
const cpt = parser.parseCPT(xmlText);

Node.js (requires peer deps):

import { BROParser, XMLAdapter } from "@bedrock-engineer/bro-xml-parser/node";

const parser = new BROParser(new XMLAdapter());

// Auto-detect file type
const data = parser.parse(xmlText);
console.log(data.meta.dataType); // 'CPT' | 'BHR-GT' | 'BHR-G'

// Or parse specific types
const cpt = parser.parseCPT(xmlText);
const bhr_gt = parser.parseBHRGT(xmlText);
const bhr_g = parser.parseBHRG(xmlText);

Coded values

Fields that carry a BRO code (quality class, soil name, method, …) parse to a Coded object — the code plus the codeSpace domain the XML declares — or null when absent:

cpt.qualityClass;
// { code: "klasse2", codeSpace: "urn:bro:cpt:QualityClass" } | null
cpt.qualityClass?.code === "klasse2";

Keeping the codeSpace from the instance is what lets describe resolve the human-readable text without ever guessing the domain.

Measured values

Fields that carry a physical quantity (depths, layer boundaries, diameters, lengths, …) parse to a Measure object — the numeric value plus its uom, the unit of measure the XML declares as an attribute (uom="m", uom="kPa", uom="g/cm3", …) — or null when absent:

cpt.conePenetrometerSurvey?.trajectory?.finalDepth;
// { value: 25.5, uom: "m" } | null

The unit is provided with the number rather than being silently dropped, so users don't have to assume what a bare number is measured in.

Custom Schemas

Extract only the fields you need:

Build a schema from the producers combinators — a map of field name → producer. The return type is inferred from the map, so result.depth is Measure | null, result.location is Location | null, with no casts:

import { BROParser, XMLAdapter, producers as p } from "@bedrock-engineer/bro-xml-parser/node";

const parser = new BROParser(new XMLAdapter());

const result = parser.parseCustom(
  xmlText,
  {
    id: p.text("brocom:broId"),
    depth: p.measure(".//cptcommon:finalDepth"),
    location: p.gmlLocation("./dscpt:deliveredLocation/cptcommon:location"),
  },
  "CPT",
);
// { id: "CPT000000099543", depth: { value: 25.5, uom: "m" }, location: { x: 155000, y: 463000, epsg: "28992" }, meta: {…} }

The producers namespace carries every building block the library uses internally: leaf combinators (text, number, integer, date, boolean, code, measure), structural combinators (object, array, oneOf, custom), and the domain helpers (gmlLocation, columns / col).

API

| Method | Returns | Description | | --------------------------------- | ----------- | -------------------------- | | parse(xml) | BROData | Auto-detect type and parse | | parseCPT(xml) | CPTData | Parse CPT file | | parseBHRGT(xml) | BHRGTData | Parse BHR-GT file | | parseBHRG(xml) | BHRGData | Parse BHR-G file | | parseCustom(xml, fields, type?) | T | Parse with a producer map |

See src/types/index.ts for full type definitions.

Supported Schemas

| Type | Schema Version | Link | | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CPT | dscpt/1.1 | BRO CPT docs | | BHR-GT | dsbhr-gt/2.1 | BRO BHR-GT docs | | BHR-G | dsbhrg/3.1 | BRO BHR-G docs |

Reference Codes

BRO/XML values use camelCase domain codes like "langwerpig", "mechanischDiscontinu", or "ISO19901d8v2014" some are intuitive, some are cryptic. The BRO publishes official human-readable descriptions for all of these codes.

Coded values parse to { code, codeSpace } (a Coded), carrying the domain the XML declares. Resolve any of them with the single describe function, generated from the BRO reference codes API:

import { describe } from "@bedrock-engineer/bro-xml-parser/reference-codes";

const bore = parser.parseBHRGT(xmlText);

bore.data.forEach((layer) => {
  const description = describe(layer.geotechnicalSoilName); // domain-correct by construction
  console.log(`${layer.upperBoundary}–${layer.lowerBoundary}m: ${description}`);
  // e.g. "0–2m: Grove minerale grond, waarvan de grove fractie uit zand bestaat..."
});

Because a Coded carries its own codeSpace, describe never has to guess which table a code belongs to. The per-domain *_CODES tables and the CODES_BY_DOMAIN index are also exported for advanced use.

Run npm run codegen:reference-codes to regenerate the lookup tables from the latest API.

License

Apache 2.0 — Jules Blom at Bedrock.engineer