xoev-xwasser 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,265 +1,546 @@
1
1
  # xoev-xwasser
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/xoev-xwasser)](https://www.npmjs.com/package/xoev-xwasser)
4
+
3
5
  The XÖV data exchange standard XWasser is used for the digital exchange of data between operators of water supply systems (operators), who are responsible for regular drinking water testing in accordance with the quality standards of the German Drinking Water Ordinance (TrinkwV), and the responsible public health authorities (GA) as well as other authorities and diagnostic service providers.
4
6
  The standard therefore also covers the direct transmission of test reports from approved testing institutes (laboratories) to the health authorities as well as the annual transmission of drinking water quality data by the health authorities to the competent supreme state authority (OLB), which is subject to reporting requirements.
5
7
  The XWasser standard is part of the project "Nationwide standardized digital data exchange for drinking water hygiene (SHAPTH)" of all 16 federal states within the framework of the Pact for the Public Health Service (ÖGD).
6
8
 
9
+ - [Installation](#installation)
10
+ - [Quick Start](#quick-start)
11
+ - [Creating XML Messages](#creating-xml-messages)
12
+ - [Parsing XML](#parsing-xml)
13
+ - [Transforming XML](#transforming-xml)
14
+ - [Builder Functions](#builder-functions)
15
+ - [Utility Functions](#utility-functions)
16
+ - [Schema Validation (Node.js)](#schema-validation-nodejs)
17
+ - [Version Detection](#version-detection)
18
+ - [Web (Browser) Usage](#web-browser-usage)
19
+ - [TypeScript Types](#typescript-types)
20
+ - [Examples](#examples)
21
+ - [For Rust Development](#for-rust-development)
22
+ - [License](#license)
23
+
24
+ ---
25
+
26
+ ## Installation
7
27
 
8
- ## Legal
28
+ ```bash
29
+ npm install xoev-xwasser
30
+ ```
9
31
 
10
- Licensed under `MIT` license.
32
+ For browser usage, see [Web (Browser) Usage](#web-browser-usage).
11
33
 
12
- ## Versioning
34
+ ## Quick Start
13
35
 
14
- This crate follows the latest minor and patch versions for each maintained major version.
36
+ ```typescript
37
+ import {
38
+ create_vorgang_transportieren_2010,
39
+ parse_vorgang_transportieren_2010,
40
+ schema,
41
+ local_schema,
42
+ VorgangTransportieren2010,
43
+ } from "xoev-xwasser";
15
44
 
16
- The crate versions follow the `X.Y.Z+A.B.C` pattern:
45
+ import qualityReport from "./quality_report.json";
17
46
 
18
- - The major version `X` is the upstream XÖV XWasser API compatibility version:
19
- - `300` for 3.Y.Z
20
- - The patch `Y` version is incremented when making XÖV XWasser update. It is
21
- equal to `B*100 + C`.
22
- - The patch `Z` version is incremented when making internal changes
23
- to the crate.
24
- - `A.B.C` contains the full upstream XÖV XWasser version, like `0.2.1` or `0.5.0`.
25
- Note that this field is actually ignored in comparisons and only there for
26
- documentation.
47
+ // Create XML from a JSON object
48
+ const xml = create_vorgang_transportieren_2010(
49
+ qualityReport as unknown as VorgangTransportieren2010
50
+ ).replace(schema(), local_schema());
27
51
 
28
- ## Features
52
+ // Parse XML back to JSON
53
+ const obj = parse_vorgang_transportieren_2010(xml);
54
+ ```
29
55
 
30
- This crate provides several features that can be enabled:
56
+ ## Creating XML Messages
31
57
 
32
- | Feature | Description |
33
- |---------|-------------|
34
- | `builder` | Enables builder patterns for type construction using `TypedBuilder` |
35
- | `wasm` | Enables WebAssembly bindings using `wasm-bindgen` and `tsify` |
36
- | `schema` | Enables XSD schema validation |
37
- | `trace` | Enables tracing for debugging |
58
+ ### create_vorgang_transportieren_2010
38
59
 
39
- ### Default Features
60
+ Serializes a `VorgangTransportieren2010` object to an XML string suitable for the XWasser transport protocol:
40
61
 
41
- By default, no features are enabled. To use the crate with builders and schema validation:
62
+ ```typescript
63
+ import { create_vorgang_transportieren_2010, schema, local_schema } from "xoev-xwasser";
42
64
 
43
- ```toml
44
- xoev-xwasser = { version = "1.0.0", features = ["builder", "schema"] }
65
+ const xml = create_vorgang_transportieren_2010(data)
66
+ .replace(schema(), local_schema());
45
67
  ```
46
68
 
47
- ### Builder Pattern
69
+ The `schema()` / `local_schema()` replacement is needed because the serialized XML uses the full namespace URI, but the XSD schema reference in the XML should point to the local schema file location.
48
70
 
49
- The builder feature enables a fluent API for constructing XML messages:
71
+ ### create_administration_quittung_0020
50
72
 
51
- ```rust
52
- use xoev_xwasser::{
53
- builder::{
54
- pruefbericht::pruefbericht_type,
55
- transport::{nachrichtenkopf_g2g, NachrichtenTypEnum},
56
- vorgang::identifikation_vorgang,
57
- },
58
- model::{
59
- signature::Signature,
60
- transport::VorgangTransportieren2010,
61
- vorgang::{Vorgang, VorgangType},
62
- },
63
- };
73
+ Serializes an `AdministrationQuittung0020` object (administration receipt/acknowledgement):
64
74
 
65
- // Create a Pruefbericht
66
- let pruefbericht = pruefbericht_type(
67
- "1.0".into(),
68
- None,
69
- "test-context".into(),
70
- Default::default(),
71
- );
75
+ ```typescript
76
+ import { create_administration_quittung_0020 } from "xoev-xwasser";
77
+
78
+ const xml = create_administration_quittung_0020(data);
79
+ ```
80
+
81
+ ### xmlns / version / schema / local_schema
82
+
83
+ Utility functions for namespace and version metadata:
72
84
 
73
- // Build the message with all required fields
74
- let message = VorgangTransportieren2010::builder()
75
- .produkt("MyApp".into())
76
- .produkthersteller("My Company".into())
77
- .produktversion("1.0.0".into())
78
- .nachrichtenkopf_g2g(nachrichtenkopf_g2g(
79
- NachrichtenTypEnum::VorgangTransportieren2010,
80
- ))
81
- .vorgang(
82
- Vorgang::builder()
83
- .identifikation_vorgang(identifikation_vorgang(None))
84
- .vorgang_type(VorgangType::Pruefbericht(pruefbericht))
85
- .bemerkung(None)
86
- .anlage(Default::default())
87
- .build(),
88
- )
89
- .zusatzinformationen(Default::default())
90
- .signature(Some(Signature { exists: true }))
91
- .build();
85
+ ```typescript
86
+ import { xmlns, version, schema, local_schema } from "xoev-xwasser";
87
+
88
+ console.log(xmlns()); // XML namespace URI
89
+ console.log(version()); // Current XWasser schema version
90
+ console.log(schema()); // Full schema namespace URI
91
+ console.log(local_schema()); // Local schema file reference
92
92
  ```
93
93
 
94
- ### Serialization
94
+ ## Parsing XML
95
+
96
+ ### parse_vorgang_transportieren_2010
95
97
 
96
- The crate supports both XML and JSON serialization:
98
+ Parses an XML string back into a typed `VorgangTransportieren2010` object:
99
+
100
+ ```typescript
101
+ import { parse_vorgang_transportieren_2010 } from "xoev-xwasser";
102
+
103
+ const source = `<?xml version="1.0"?>
104
+ <VorgangTransportieren2010 xmlns="...">...</VorgangTransportieren2010>`;
105
+
106
+ const obj = parse_vorgang_transportieren_2010(source);
107
+
108
+ // Tagged union pattern for variant types
109
+ if (obj.vorgang.vorgang_type.t === "Pruefbericht") {
110
+ const pruefbericht = obj.vorgang.vorgang_type.c;
111
+ console.log(pruefbericht.id);
112
+ }
113
+ ```
97
114
 
98
- ```rust
99
- use raxb::{ser::to_string, de::from_str};
100
- use serde_json;
115
+ ### parse_administration_quittung_0020
101
116
 
102
- // Serialize to XML
103
- let xml = to_string(&message)?;
117
+ Parses an administration receipt XML:
104
118
 
105
- // Serialize to JSON
106
- let json = serde_json::to_string(&message)?;
119
+ ```typescript
120
+ import { parse_administration_quittung_0020 } from "xoev-xwasser";
107
121
 
108
- // Deserialize from XML
109
- let parsed: VorgangTransportieren2010 = from_str(&xml)?;
122
+ const receipt = parse_administration_quittung_0020(xmlSource);
110
123
  ```
111
124
 
112
- ### Schema Validation
125
+ ## Transforming XML
126
+
127
+ `transform_vorgang_transportieren_2010` mutates a transport message
128
+ (`vorgang.transportieren.2010`) in-place — `<leser>`, `<autor>`,
129
+ `<zusatzinformationen>`, and/or `<nachrichtenUUID>` — while preserving all
130
+ comments, processing instructions, whitespace text nodes, line endings, and
131
+ attribute order so that XML digital signatures stay valid. A no-op transform
132
+ (all options `undefined`) is byte-identical to the input.
133
+
134
+ The transform is namespace-prefix agnostic (matching uses the resolved
135
+ namespace URI), so it works whether the source uses `xwas:`, `xw:`, or any
136
+ other prefix for the XWasser namespace.
113
137
 
114
- The `schema` feature compiles XSD schemas into a binary format (`.xsdb`) and provides validation:
138
+ ```typescript
139
+ import { transform_vorgang_transportieren_2010 } from "xoev-xwasser";
140
+
141
+ // Mutate leser/autor in-place
142
+ const result = transform_vorgang_transportieren_2010(xml, {
143
+ nachrichtenkopf_g2g: {
144
+ leser: { kennung: "psw:99999999", name: "New Reader" },
145
+ autor: { kennung: "psw:autor123", name: "Updated Autor" },
146
+ },
147
+ });
115
148
 
116
- ```rust
117
- use xoev_xwasser::schemas::XmlValidation;
149
+ // Replace zuständige Behörde IDs (preserves kommentar / wasserversorgungsgebietID)
150
+ const result2 = transform_vorgang_transportieren_2010(xml, {
151
+ zusatzinformationen: { zustaendige_behoerde_id: ["auth-001", "auth-002"] },
152
+ });
118
153
 
119
- let validation = XmlValidation::new()?;
120
- validation.validate(xml_bytes)?;
154
+ // Replace or insert nachrichtenUUID
155
+ const result3 = transform_vorgang_transportieren_2010(xml, {
156
+ nachrichtenkopf_g2g: { nachrichten_uuid: "693c64d6-456f-4d14-abe7-fe9681c74aae" },
157
+ });
121
158
  ```
122
159
 
123
- **How it works:**
124
- 1. During build/test, `raxb_xmlschema_build` compiles `schemas/V1_0_0/xwasser.xsd` to `.xsdb` format
125
- 2. The compiled schemas are embedded via `rust_embed`
126
- 3. At runtime, XML is validated against the compiled schemas using `raxb_validate`
160
+ The second argument is a `TransformOptionsParam` (all fields optional). Its
161
+ shape mirrors the XML document — a header group (`nachrichtenkopf_g2g`) and a
162
+ `zusatzinformationen` group, so each field's destination is explicit and the
163
+ `zusatzinformationen` group can grow later (e.g. a `kommentar` update) without
164
+ reshaping the top-level shape:
127
165
 
128
- **Note:** Schema compilation runs automatically via the `schema` feature test:
129
- ```sh
130
- cargo test --features schema --test generate_schemas
166
+ ```typescript
167
+ export interface TransformOptionsParam {
168
+ nachrichtenkopf_g2g?: {
169
+ leser?: { kennung?: string; name?: string };
170
+ autor?: { kennung?: string; name?: string };
171
+ nachrichten_uuid?: string;
172
+ };
173
+ zusatzinformationen?: {
174
+ zustaendige_behoerde_id?: string[];
175
+ };
176
+ }
131
177
  ```
132
178
 
133
- ## Usage
179
+ | Field | Behavior |
180
+ |-------|----------|
181
+ | `nachrichtenkopf_g2g.leser` | Mutates `<kennung>`/`<name>` inside `<leser>` in-place; inserts a missing `<leser>` as the 2nd child of `nachrichtenkopf.g2g` (after `identifikation.nachricht`) |
182
+ | `nachrichtenkopf_g2g.autor` | Mutates `<kennung>`/`<name>` inside `<autor>` in-place; inserts a missing `<autor>` after `<leser>` |
183
+ | `nachrichtenkopf_g2g.nachrichten_uuid` | `undefined` = no change; `"uuid"` = replace existing `<nachrichtenUUID>` or insert if missing |
184
+ | `zusatzinformationen.zustaendige_behoerde_id` | `undefined` = keep existing block; `["id1", ...]` = replace `<zustaendigeBehoerdeID>` entries (set semantics) while preserving `<kommentar>`, `<wasserversorgungsgebietID>`, comments, and whitespace; `[]` = replace with an empty block |
134
185
 
135
- ### Basic Example
186
+ On malformed input, the original XML is returned unchanged (no partial/truncated output). The Rust crate also exposes `transform_vorgang_transportieren_2010_with_ids(xml, leser, autor, zusatzinfo_ids: Option<&[String]>)` as a convenience wrapper.
136
187
 
137
- ```rust
138
- use xoev_xwasser::{
139
- builder::{
140
- pruefbericht::pruefbericht_type,
141
- transport::{nachrichtenkopf_g2g, NachrichtenTypEnum},
142
- vorgang::identifikation_vorgang,
143
- },
144
- model::{
145
- signature::Signature,
146
- transport::VorgangTransportieren2010,
147
- vorgang::{Vorgang, VorgangType},
148
- },
149
- };
188
+ ## Builder Functions
150
189
 
151
- let pruefbericht = pruefbericht_type(
152
- "1.0".into(),
153
- None,
154
- "context".into(),
155
- Default::default(),
156
- );
190
+ The package provides factory functions to construct typed objects with sensible defaults, auto-generated IDs, and timestamp creation.
191
+
192
+ ### Transport Layer
193
+
194
+ ```typescript
195
+ import {
196
+ identifikation_nachricht,
197
+ nachrichtenkopf_g2g,
198
+ identifikation_vorgang,
199
+ } from "xoev-xwasser";
200
+
201
+ const msgId = identifikation_nachricht("VorgangTransportieren2010");
202
+ // Returns: { nachrichten_uuid: "...", nachrichten_typ: {...}, erstellungszeitpunkt: "..." }
203
+
204
+ const header = nachrichtenkopf_g2g("VorgangTransportieren2010");
157
205
 
158
- let message = VorgangTransportieren2010::builder()
159
- .produkt("MyApp".into())
160
- .produkthersteller("My Company".into())
161
- .produktversion("1.0.0".into())
162
- .nachrichtenkopf_g2g(nachrichtenkopf_g2g(
163
- NachrichtenTypEnum::VorgangTransportieren2010,
164
- ))
165
- .vorgang(
166
- Vorgang::builder()
167
- .identifikation_vorgang(identifikation_vorgang(None))
168
- .vorgang_type(VorgangType::Pruefbericht(pruefbericht))
169
- .bemerkung(None)
170
- .anlage(Default::default())
171
- .build(),
172
- )
173
- .zusatzinformationen(Default::default())
174
- .signature(Some(Signature { exists: true }))
175
- .build();
206
+ const vId = identifikation_vorgang(); // auto-generated vorgangs_id
207
+ const vIdCustom = identifikation_vorgang("my-id-123"); // custom vorgangs_id
176
208
  ```
177
209
 
178
- ### Working with Addresses
210
+ ### Addresses
179
211
 
180
- ```rust
181
- use xoev_xwasser::builder::shared::anschrift::anschrift_type;
212
+ ```typescript
213
+ import { anschrift_type } from "xoev-xwasser";
182
214
 
183
- let addr = anschrift_type(
184
- "Teststr.".into(),
185
- "1".into(),
186
- "12345".into(),
187
- "Testort".into(),
215
+ const addr = anschrift_type(
216
+ "Musterstr.", // strasse
217
+ "42", // hausnummer
218
+ "12345", // postleitzahl
219
+ "Musterstadt", // ort
188
220
  );
221
+ // Returns: { strasse, hausnummer, postleitzahl, ort, id: "anschrift-..." }
189
222
  ```
190
223
 
191
- ### Codelist Codes
224
+ ### Persons and Organizations
225
+
226
+ ```typescript
227
+ import {
228
+ natuerliche_person_type,
229
+ allgemeiner_name_type,
230
+ name_organisation_type,
231
+ } from "xoev-xwasser";
232
+ import { vorname, familienname } from "xoev-xwasser/utils";
233
+
234
+ const person = natuerliche_person_type("Sepp", "Meier");
235
+ // Returns: { name_natuerliche_person: {...}, id: "person-..." }
236
+ // Use utility functions to extract name parts:
237
+ const first = vorname(person); // "Sepp"
238
+ const last = familienname(person); // "Meier"
192
239
 
193
- ```rust
194
- use xoev_xwasser::model::codes::CodeGesamtbewertungType;
240
+ const name = allgemeiner_name_type("Max Mustermann");
241
+ // Returns: { name: "Max Mustermann" }
195
242
 
196
- let bewertung = CodeGesamtbewertungType::builder()
197
- .code("1010".into())
198
- .name(None)
199
- .build();
243
+ const orgName = name_organisation_type("ACME GmbH", "ACME");
244
+ // Returns: { name: { text: "ACME GmbH" }, kurzbezeichnung: "ACME", ... }
200
245
  ```
201
246
 
202
- ## TypeScript / WebAssembly
247
+ ### Authorities and Institutions
203
248
 
204
- The crate compiles to WebAssembly for use in TypeScript/JavaScript applications:
249
+ ```typescript
250
+ import {
251
+ behoerde_type,
252
+ autor,
253
+ leser,
254
+ zustaendige_behoerde_type,
255
+ zugelassene_untersuchungsstelle_type,
256
+ beauftragte_untersuchungsstelle_type,
257
+ betreiber_type,
258
+ UntersuchungsstelleDetails,
259
+ } from "xoev-xwasser";
205
260
 
206
- ```bash
207
- npm install xoev-xwasser
261
+ const authority = behoerde_type();
262
+ const author = autor("Name", "KENNUNG");
263
+ const reader = leser("Name", "KENNUNG");
264
+ const responsible = zustaendige_behoerde_type("NW"); // Bundesland code
265
+
266
+ // Untersuchungsstelle with required accreditation details
267
+ const labDetails: UntersuchungsstelleDetails = {
268
+ id: "lab-1",
269
+ name: "Umweltlabor GmbH",
270
+ zugelassene_untersuchungsstelle_id: "ZUL-12345",
271
+ pruefgebiete_untersuchungen_phys_chem: true,
272
+ pruefgebiete_untersuchungen_mikrobio: true,
273
+ pruefgebiete_untersuchungen_radionuklide: false,
274
+ pruefgebiete_nur_vor_ort_parameter: false,
275
+ akkreditierungsnummer: "AKK-D-PL-12345-01",
276
+ unterorganisation: undefined,
277
+ };
278
+
279
+ const lab = zugelassene_untersuchungsstelle_type(labDetails);
280
+ const commissioner = beauftragte_untersuchungsstelle_type(labDetails);
281
+ const operator = betreiber_type();
208
282
  ```
209
283
 
210
- ### Creating XML Messages
284
+ ### Pruefbericht (Test Report)
211
285
 
212
286
  ```typescript
213
- import {
214
- create_vorgang_transportieren_2010,
215
- parse_vorgang_transportieren_2010,
216
- VorgangTransportieren2010,
217
- PruefberichtType,
218
- schema,
219
- local_schema,
287
+ import {
288
+ pruefbericht_type,
289
+ pruefbericht_signature_template,
290
+ probe_type,
291
+ probennahmestelle_type,
292
+ probennehmer_type,
293
+ parameterangaben_type,
294
+ analyseergebnis_parameter_type,
295
+ kommentar_type,
296
+ zeitraum_type,
297
+ aenderungshistorie_type,
298
+ UntersuchungsstelleDetails,
220
299
  } from "xoev-xwasser";
221
300
 
222
- import quality_report from "./quality_report.json";
301
+ // Untersuchungsstelle details
302
+ const labDetails: UntersuchungsstelleDetails = {
303
+ id: "lab-1",
304
+ name: "Umweltlabor GmbH",
305
+ zugelassene_untersuchungsstelle_id: "ZUL-12345",
306
+ pruefgebiete_untersuchungen_phys_chem: true,
307
+ pruefgebiete_untersuchungen_mikrobio: true,
308
+ pruefgebiete_untersuchungen_radionuklide: false,
309
+ pruefgebiete_nur_vor_ort_parameter: false,
310
+ akkreditierungsnummer: "AKK-D-PL-12345-01",
311
+ unterorganisation: undefined,
312
+ };
223
313
 
224
- // Create XML from JSON object
225
- const xml = create_vorgang_transportieren_2010(
226
- quality_report as unknown as VorgangTransportieren2010
227
- ).replace(schema(), local_schema());
314
+ // Create a test report
315
+ const report = pruefbericht_type(
316
+ "1.0", // sw_version
317
+ null, // id (null = auto-generated)
318
+ "test-context", // context
319
+ labDetails,
320
+ );
321
+
322
+ const sig = pruefbericht_signature_template(); // Signature template
323
+
324
+ // Sampling
325
+ const sample = probe_type();
326
+ const site = probennahmestelle_type("Sampling Point 1");
327
+ // site.name_probennahmestelle === "Sampling Point 1"
328
+
329
+ const sampler = probennehmer_type();
330
+
331
+ // Analysis
332
+ const param = parameterangaben_type();
333
+ const result = analyseergebnis_parameter_type("addr-id", "lab-id");
334
+
335
+ const comment = kommentar_type();
336
+ const period = zeitraum_type();
337
+ const history = aenderungshistorie_type();
228
338
  ```
229
339
 
230
- ### Parsing XML
340
+ ### Monitoring Plans, Objects, and More
231
341
 
232
342
  ```typescript
233
- import { parse_vorgang_transportieren_2010 } from "xoev-xwasser";
343
+ import {
344
+ untersuchungsplan_type,
345
+ terminplan_type,
346
+ wasserversorgungsgebiet_type,
347
+ objekt_type,
348
+ anlage_nach_trinkw_v_type,
349
+ organisation_type,
350
+ identifikation_type,
351
+ quality_and_monitoring_type,
352
+ derogation_type,
353
+ derogation_remedial_action_type,
354
+ exceedance_type,
355
+ exceedance_cause_and_remedial_action_type,
356
+ incident_type,
357
+ incident_cause_and_remedial_action_type,
358
+ } from "xoev-xwasser";
234
359
 
235
- const source = `<?xml version="1.0"?>
236
- <VorgangTransportieren2010>...</VorgangTransportieren2010>`;
360
+ const plan = untersuchungsplan_type();
361
+ const schedule = terminplan_type("sampling-site-id");
362
+ const wvg = wasserversorgungsgebiet_type();
363
+ const obj = objekt_type();
364
+ const system = anlage_nach_trinkw_v_type();
365
+ const org = organisation_type();
366
+ const ident = identifikation_type();
367
+ const qm = quality_and_monitoring_type();
368
+ ```
237
369
 
238
- const obj = parse_vorgang_transportieren_2010(source);
239
- if (obj.vorgang.vorgang_type.t === "Pruefbericht") {
240
- const p = obj.vorgang.vorgang_type.c;
241
- console.log(p.id);
370
+ ### Full List of Builder Functions
371
+
372
+ | Function | Returns | Description |
373
+ |----------|---------|-------------|
374
+ | `identifikation_nachricht(typ)` | `IdentifikationNachricht` | Message ID with auto-generated UUID and timestamp |
375
+ | `nachrichtenkopf_g2g(typ)` | `NachrichtenkopfG2g` | G2G message header |
376
+ | `identifikation_vorgang(id?)` | `IdentifikationVorgang` | Process/transaction ID |
377
+ | `anschrift_type(str, nr, plz, ort)` | `AnschriftType` | Address with auto-generated ID |
378
+ | `natuerliche_person_type(vorname, name)` | `NatuerlichePersonType` | Natural person |
379
+ | `allgemeiner_name_type(name)` | `AllgemeinerNameType` | General name |
380
+ | `name_organisation_type(name?, kurz?)` | `NameOrganisationType` | Organisation name |
381
+ | `behoerde_type()` | `BehoerdeType` | Authority |
382
+ | `autor(name, kennung)` | `BehoerdeG2GType` | Author authority |
383
+ | `leser(name, kennung)` | `BehoerdeG2GType` | Reader authority |
384
+ | `zustaendige_behoerde_type(kuerzel)` | `ZustaendigeBehoerdeType` | Responsible authority (by Bundesland) |
385
+ | `zugelassene_untersuchungsstelle_type(details)` | `ZugelasseneUntersuchungsstelleType` | Approved testing lab |
386
+ | `beauftragte_untersuchungsstelle_type(details)` | `BeauftragteUntersuchungsstelleType` | Commissioned testing lab |
387
+ | `betreiber_type()` | `BetreiberType` | Operator |
388
+ | `pruefbericht_type(ver, id, ctx, details)` | `PruefberichtType` | Test report |
389
+ | `pruefbericht_signature_template()` | `Signature` | Signature template |
390
+ | `probe_type()` | `ProbeType` | Sample |
391
+ | `probennahmestelle_type(name)` | `ProbennahmestelleType` | Sampling point |
392
+ | `probenehmer_type()` | `ProbennehmerType` | Sampler |
393
+ | `parameterangaben_type()` | `ParameterangabenType` | Parameter specification |
394
+ | `analyseergebnis_parameter_type(addr, lab)` | `AnalyseergebnisParameterType` | Analysis result |
395
+ | `kommentar_type()` | `KommentarType` | Comment |
396
+ | `zeitraum_type()` | `ZeitraumType` | Time period |
397
+ | `aenderungshistorie_type()` | `AenderungshistorieType` | Change history |
398
+ | `untersuchungsplan_type()` | `UntersuchungsplanType` | Investigation plan |
399
+ | `terminplan_type(siteId)` | `TerminplanType` | Schedule plan |
400
+ | `wasserversorgungsgebiet_type()` | `WasserversorgungsgebietType` | Water supply area |
401
+ | `objekt_type()` | `ObjektType` | Object |
402
+ | `anlage_nach_trinkw_v_type()` | `AnlageNachTrinkwVType` | System per TrinkwV |
403
+ | `organisation_type()` | `OrganisationType` | Organisation |
404
+ | `identifikation_type()` | `IdentifikationType` | Identification |
405
+ | `quality_and_monitoring_type()` | `QualityAndMonitoringType` | Quality & monitoring |
406
+ | `derogation_type()` | `DerogationType` | Derogation |
407
+ | `derogation_remedial_action_type()` | `DerogationRemedialActionType` | Derogation remedial action |
408
+ | `exceedance_type()` | `ExceedanceType` | Exceedance |
409
+ | `exceedance_cause_and_remedial_action_type()` | `ExceedanceCauseAndRemedialActionType` | Exceedance cause & remediation |
410
+ | `incident_type()` | `IncidentType` | Incident |
411
+ | `incident_cause_and_remedial_action_type()` | `IncidentCauseAndRemedialActionType` | Incident cause & remediation |
412
+
413
+ ## Working with Codelists
414
+
415
+ The XWasser standard defines many codelists (controlled vocabularies) for fields like water type, sampling location category, test result evaluation, parameters, and more. The package provides both typed code interfaces and the raw codelist data.
416
+
417
+ ### Typed Code Interfaces
418
+
419
+ Each codelist has a corresponding TypeScript interface with `code` and `name` fields:
420
+
421
+ ```typescript
422
+ import { CodeGesamtbewertungType } from "xoev-xwasser";
423
+
424
+ // Use in builder pattern
425
+ const bewertung: CodeGesamtbewertungType = {
426
+ code: "1010",
427
+ name: "Einwandfrei",
428
+ };
429
+ ```
430
+
431
+ Common code interfaces include:
432
+
433
+ | Interface | Codelist |
434
+ |-----------|----------|
435
+ | `CodeGesamtbewertungType` | Overall assessment |
436
+ | `CodeMediumType` | Medium (water type) |
437
+ | `CodeProbennahmeverfahrenType` | Sampling procedure |
438
+ | `CodeUntersuchungsanlassType` | Investigation reason |
439
+ | `CodeShapthParameterType` | SHAPTH parameter |
440
+ | `CodeShapthParameterEinheitType` | SHAPTH parameter unit |
441
+ | `CodeArtProbennahmestelleType` | Sampling point type |
442
+ | `CodeKategorieProbennahmestelleType` | Sampling point category |
443
+ | `CodeMassnahmeType` | Measures |
444
+ | `CodeAbhilfemassnahmeType` | Remedial actions |
445
+ | `CodeNamensartType` | Name type |
446
+ | `CodeStaatType` | Country |
447
+ | `CodeStaatsangehoerigkeitType` | Nationality |
448
+ | `CodeAgsType` | Municipality (AGS) |
449
+ | `CodeKreisType` | District |
450
+ | `CodeBundeslandType` | Federal state |
451
+ | `CodeNachrichtentypType` | Message type |
452
+ | `CodePersonenrolleType` | Person role |
453
+ | `CodeKommunikationKanalType` | Communication channel |
454
+
455
+ Refer to the included `xoev_xwasser.d.ts` for the complete list of code interfaces.
456
+
457
+ ### Raw Codelist Data
458
+
459
+ The full codelist dataset is included as `codelist.json` in the package root. It contains all 72 codelists with their metadata, field definitions, and permitted values:
460
+
461
+ ```typescript
462
+ import codelists from "xoev-xwasser/codelist.json" with { type: "json" };
463
+ // or: const codelists = require("xoev-xwasser/codelist.json");
464
+
465
+ // Find a codelist by its short name
466
+ const samplingSites = codelists.find(
467
+ (cl) => cl.header.identification.short_name === "art-probennahmestelle"
468
+ );
469
+
470
+ console.log(samplingSites.header.identification.long_name);
471
+ // "Art der Probennahmestelle"
472
+
473
+ // Iterate permitted values
474
+ for (const value of samplingSites.values) {
475
+ // Each value is an array matching the fields defined in header.fields
476
+ console.log(value[0]); // Key/Code
477
+ console.log(value[1]); // Description
242
478
  }
243
479
  ```
244
480
 
245
- ### Utility Functions
481
+ Example codelist JSON structure:
482
+
483
+ ```json
484
+ {
485
+ "header": {
486
+ "identification": {
487
+ "short_name": "medium",
488
+ "long_name": "Medium",
489
+ "version": "2",
490
+ "canonical_uri": "urn:xoev-de:xwasser:codeliste:medium"
491
+ },
492
+ "description": {
493
+ "codelist_description": "Diese Codeliste dient im Kontext von XWasser der Angabe des Mediums einer Probennahme."
494
+ },
495
+ "fields": [
496
+ { "id": "Key", "field_type": "RecommendedKey", "usage": "Required" },
497
+ { "id": "Medium", "field_type": "Value", "usage": "Required" }
498
+ ],
499
+ "key_index": 0
500
+ },
501
+ "values": [
502
+ ["1010", "Trinkwasser"],
503
+ ["1020", "Rohwasser"],
504
+ ["1030", "Grundwasser"],
505
+ ["1040", "Oberflächenwasser"]
506
+ ]
507
+ }
508
+ ```
509
+
510
+ ### Validating Code Values
511
+
512
+ In Rust, the `validate` feature provides `XWasserValidate` to check code values against the codelists. In TypeScript, you can validate manually by loading `codelist.json` and checking values at runtime.
513
+
514
+ ## Utility Functions
515
+
516
+ Additional helpers are available from the `xoev-xwasser/utils` subpath:
246
517
 
247
518
  ```typescript
248
519
  import { vorname, familienname } from "xoev-xwasser/utils";
249
520
  import { natuerliche_person_type } from "xoev-xwasser";
250
521
 
251
522
  const person = natuerliche_person_type("Sepp", "Meier");
252
- console.log(vorname(person)); // "Sepp"
523
+ console.log(vorname(person)); // "Sepp"
253
524
  console.log(familienname(person)); // "Meier"
254
525
  ```
255
526
 
256
- ### Schema Validation (Node.js)
527
+ ## Schema Validation
528
+
529
+ Schema validation requires the separate `@raxb/validate-wasm` package:
530
+
531
+ ```bash
532
+ npm install @raxb/validate-wasm
533
+ ```
534
+
535
+ The `.xsdb.bin` file is included in the npm package and contains the compiled XWasser XSD schema for version 1.0.0.
536
+
537
+ ### Node.js
257
538
 
258
539
  ```typescript
259
540
  import fs from "fs";
260
541
  import xmlvalidate, { XmlValidatorError } from "@raxb/validate-wasm";
261
542
 
262
- // Load compiled schema
543
+ // Load the compiled XSD bundle from the package
263
544
  const xsdBundle = fs.readFileSync(
264
545
  "node_modules/xoev-xwasser/xwasser-v100.xsdb.bin"
265
546
  ).buffer;
@@ -268,7 +549,7 @@ const { XmlValidator } = await xmlvalidate();
268
549
  const validator = new XmlValidator(new Uint8Array(xsdBundle));
269
550
  validator.init((err: string) => console.error(err));
270
551
 
271
- // Validate XML
552
+ // Validate XML against the schema
272
553
  validator.validateXml(xmlString, (err: XmlValidatorError) => {
273
554
  if (err.level === "fatal") {
274
555
  console.error({ line: err.line, message: err.message });
@@ -276,63 +557,116 @@ validator.validateXml(xmlString, (err: XmlValidatorError) => {
276
557
  });
277
558
  ```
278
559
 
279
- ## Development
560
+ ### Browser
280
561
 
281
- ### Building
562
+ ```typescript
563
+ import xmlvalidate, { XmlValidatorError } from "@raxb/validate-wasm";
282
564
 
283
- ```sh
284
- # Build with all features
285
- cargo build --features builder,wasm,schema
565
+ // Fetch the compiled XSD bundle (served from your public directory)
566
+ const response = await fetch("/xwasser-v100.xsdb.bin");
567
+ const xsdBundle = await response.arrayBuffer();
286
568
 
287
- # Run tests
288
- cargo test --features builder,schema
569
+ const { XmlValidator } = await xmlvalidate();
570
+ const validator = new XmlValidator(new Uint8Array(xsdBundle));
571
+ validator.init((err: string) => console.error(err));
289
572
 
290
- # Run clippy
291
- cargo clippy --features builder
573
+ // Validate XML against the schema
574
+ validator.validateXml(xmlString, (err: XmlValidatorError) => {
575
+ if (err.level === "fatal") {
576
+ console.error({ line: err.line, message: err.message });
577
+ }
578
+ });
292
579
  ```
293
580
 
294
- ### Full Build (includes WASM)
581
+ ## Version Detection
295
582
 
296
- ```sh
297
- ./build.sh
298
- ```
583
+ Automatically detect the XWasser schema version from an XML document:
299
584
 
300
- ### Testing
585
+ ```typescript
586
+ import { detect_version } from "xoev-xwasser";
301
587
 
302
- Tests are run with specific feature combinations:
588
+ const version = detect_version(xmlString.slice(0, 1024));
589
+ console.log(version); // e.g. "100"
590
+ ```
303
591
 
304
- ```sh
305
- # Core tests
306
- cargo test
592
+ The function only needs the first ~1KB of the XML to detect the version from the namespace declaration.
307
593
 
308
- # Schema validation tests
309
- cargo test --features schema,trace
594
+ ## Web (Browser) Usage
310
595
 
311
- # Builder tests
312
- cargo test --features builder
596
+ For browser environments, use the `xoev-xwasser-web` package which compiles with the Web target:
313
597
 
314
- # Full test suite
315
- cargo test --no-default-features --features schema,trace,builder
598
+ ```bash
599
+ npm install xoev-xwasser-web
316
600
  ```
317
601
 
318
- ### Code Linting
602
+ The API is the same as the Node.js version, but the WASM binary is built for web bundlers (ES modules with top-level await).
319
603
 
320
- ```sh
321
- cargo clippy --features builder --fix --allow-dirty
604
+ ```typescript
605
+ import {
606
+ create_vorgang_transportieren_2010,
607
+ parse_vorgang_transportieren_2010,
608
+ } from "xoev-xwasser-web";
322
609
  ```
323
610
 
324
- ### WASM Development
325
611
 
326
- For WASM builds during development:
327
612
 
328
- ```sh
329
- # Watch mode with auto-rebuild
330
- cargo watch --watch src -s "./build.sh"
331
- ```
613
+ ## TypeScript Types
332
614
 
333
- For TypeScript testing:
615
+ The package includes full TypeScript type definitions. All model types are exported from the main entry point:
334
616
 
335
- ```sh
336
- pnpm i
337
- pnpm test
617
+ ```typescript
618
+ import {
619
+ VorgangTransportieren2010,
620
+ AdministrationQuittung0020,
621
+ PruefberichtType,
622
+ AnschriftType,
623
+ NatuerlichePersonType,
624
+ ProbennahmestelleType,
625
+ // ... and many more
626
+ } from "xoev-xwasser";
338
627
  ```
628
+
629
+ Key types include:
630
+
631
+ | Interface | Description |
632
+ |-----------|-------------|
633
+ | `VorgangTransportieren2010` | Root transport message |
634
+ | `AdministrationQuittung0020` | Administration receipt |
635
+ | `PruefberichtType` | Test report (water quality) |
636
+ | `UntersuchungsplanType` | Monitoring/investigation plan |
637
+ | `MassnahmenType` | Measures |
638
+ | `AnschriftType` | Address |
639
+ | `NatuerlichePersonType` | Natural person |
640
+ | `OrganisationType` | Organisation |
641
+ | `BehoerdeType` | Authority |
642
+ | `ProbennahmestelleType` | Sampling point |
643
+ | `ProbeType` | Sample |
644
+ | `ParameterangabenType` | Parameter specification |
645
+ | `Vorgang` | Process/transaction wrapper |
646
+
647
+ Refer to the included `xoev_xwasser.d.ts` file for the complete type reference.
648
+
649
+ ## Examples
650
+
651
+ See the [tests directory](https://github.com/hd-gmbh-dev/xoev-xwasser-rs/tree/main/tests) in the repository for complete examples with JSON payloads and expected XML output:
652
+
653
+ | Test | Description |
654
+ |------|-------------|
655
+ | `quality_report_builder.json` | Quality report with full data |
656
+ | `quality_report_minimal.json` | Minimal quality report |
657
+ | `administration_receipt.json` | Administration receipt |
658
+ | `monitoring_plan_maximal.json` | Full monitoring plan |
659
+ | `monitoring_plan_minimal.json` | Minimal monitoring plan |
660
+ | `olb_report_minimal.json` | OLB (state authority) report |
661
+
662
+ ## For Rust Development
663
+
664
+ This package is built from the [xoev-xwasser-rs](https://github.com/hd-gmbh-dev/xoev-xwasser-rs) repository. If you need:
665
+
666
+ - **Rust crate** — published on [crates.io](https://crates.io/crates/xoev-xwasser) as `xoev-xwasser`
667
+ - **Building from source** — see the repository README for Rust development setup
668
+ - **Contributing** — PRs and issues are welcome on GitHub
669
+
670
+ ## License
671
+
672
+ Licensed under the [MIT](https://github.com/hd-gmbh-dev/xoev-xwasser-rs/blob/main/LICENSE) license.