@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 three:

1. CPT (Cone Penetration Test)
2. BHR-GT (Geotechnical Borehole)
3. BHR-G (Geological Borehole)

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

Live demo: bro.bedrock.engineer (source)

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.

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 number | 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.number(".//cptcommon:finalDepth"),
    location: p.gmlLocation("./dscpt:deliveredLocation/cptcommon:location"),
  },
  "CPT",
);
// { id: "CPT000000099543", depth: 25.5, 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), structural combinators (object, array, oneOf, custom), the domain helpers (gmlLocation, columns), and the shared field-maps (COMMON_REGISTRATION_PRODUCERS, REGISTRATION_HISTORY) you can spread into a schema.

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