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 +546 -212
- package/codelist.json +58 -58
- package/package.json +1 -1
- package/xoev-xwasser-utils.d.ts +114 -114
- package/xoev_xwasser.d.ts +471 -444
- package/xoev_xwasser.js +42 -11
- package/xoev_xwasser_bg.wasm +0 -0
- package/xoev_xwasser_bg.wasm.d.ts +14 -12
package/README.md
CHANGED
|
@@ -1,265 +1,546 @@
|
|
|
1
1
|
# xoev-xwasser
|
|
2
2
|
|
|
3
|
+
[](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
|
-
|
|
28
|
+
```bash
|
|
29
|
+
npm install xoev-xwasser
|
|
30
|
+
```
|
|
9
31
|
|
|
10
|
-
|
|
32
|
+
For browser usage, see [Web (Browser) Usage](#web-browser-usage).
|
|
11
33
|
|
|
12
|
-
##
|
|
34
|
+
## Quick Start
|
|
13
35
|
|
|
14
|
-
|
|
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
|
-
|
|
45
|
+
import qualityReport from "./quality_report.json";
|
|
17
46
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
52
|
+
// Parse XML back to JSON
|
|
53
|
+
const obj = parse_vorgang_transportieren_2010(xml);
|
|
54
|
+
```
|
|
29
55
|
|
|
30
|
-
|
|
56
|
+
## Creating XML Messages
|
|
31
57
|
|
|
32
|
-
|
|
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
|
-
|
|
60
|
+
Serializes a `VorgangTransportieren2010` object to an XML string suitable for the XWasser transport protocol:
|
|
40
61
|
|
|
41
|
-
|
|
62
|
+
```typescript
|
|
63
|
+
import { create_vorgang_transportieren_2010, schema, local_schema } from "xoev-xwasser";
|
|
42
64
|
|
|
43
|
-
|
|
44
|
-
|
|
65
|
+
const xml = create_vorgang_transportieren_2010(data)
|
|
66
|
+
.replace(schema(), local_schema());
|
|
45
67
|
```
|
|
46
68
|
|
|
47
|
-
|
|
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
|
-
|
|
71
|
+
### create_administration_quittung_0020
|
|
50
72
|
|
|
51
|
-
|
|
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
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
|
|
94
|
+
## Parsing XML
|
|
95
|
+
|
|
96
|
+
### parse_vorgang_transportieren_2010
|
|
95
97
|
|
|
96
|
-
|
|
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
|
-
|
|
99
|
-
use raxb::{ser::to_string, de::from_str};
|
|
100
|
-
use serde_json;
|
|
115
|
+
### parse_administration_quittung_0020
|
|
101
116
|
|
|
102
|
-
|
|
103
|
-
let xml = to_string(&message)?;
|
|
117
|
+
Parses an administration receipt XML:
|
|
104
118
|
|
|
105
|
-
|
|
106
|
-
|
|
119
|
+
```typescript
|
|
120
|
+
import { parse_administration_quittung_0020 } from "xoev-xwasser";
|
|
107
121
|
|
|
108
|
-
|
|
109
|
-
let parsed: VorgangTransportieren2010 = from_str(&xml)?;
|
|
122
|
+
const receipt = parse_administration_quittung_0020(xmlSource);
|
|
110
123
|
```
|
|
111
124
|
|
|
112
|
-
|
|
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
|
-
|
|
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
|
-
|
|
117
|
-
|
|
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
|
-
|
|
120
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
-
|
|
159
|
-
|
|
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
|
-
###
|
|
210
|
+
### Addresses
|
|
179
211
|
|
|
180
|
-
```
|
|
181
|
-
|
|
212
|
+
```typescript
|
|
213
|
+
import { anschrift_type } from "xoev-xwasser";
|
|
182
214
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
194
|
-
|
|
240
|
+
const name = allgemeiner_name_type("Max Mustermann");
|
|
241
|
+
// Returns: { name: "Max Mustermann" }
|
|
195
242
|
|
|
196
|
-
|
|
197
|
-
|
|
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
|
-
|
|
247
|
+
### Authorities and Institutions
|
|
203
248
|
|
|
204
|
-
|
|
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
|
-
|
|
207
|
-
|
|
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
|
-
###
|
|
284
|
+
### Pruefbericht (Test Report)
|
|
211
285
|
|
|
212
286
|
```typescript
|
|
213
|
-
import {
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
-
|
|
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
|
|
225
|
-
const
|
|
226
|
-
|
|
227
|
-
|
|
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
|
-
###
|
|
340
|
+
### Monitoring Plans, Objects, and More
|
|
231
341
|
|
|
232
342
|
```typescript
|
|
233
|
-
import {
|
|
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
|
|
236
|
-
|
|
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
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
-
|
|
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));
|
|
523
|
+
console.log(vorname(person)); // "Sepp"
|
|
253
524
|
console.log(familienname(person)); // "Meier"
|
|
254
525
|
```
|
|
255
526
|
|
|
256
|
-
|
|
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
|
|
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
|
-
|
|
560
|
+
### Browser
|
|
280
561
|
|
|
281
|
-
|
|
562
|
+
```typescript
|
|
563
|
+
import xmlvalidate, { XmlValidatorError } from "@raxb/validate-wasm";
|
|
282
564
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
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
|
-
|
|
288
|
-
|
|
569
|
+
const { XmlValidator } = await xmlvalidate();
|
|
570
|
+
const validator = new XmlValidator(new Uint8Array(xsdBundle));
|
|
571
|
+
validator.init((err: string) => console.error(err));
|
|
289
572
|
|
|
290
|
-
|
|
291
|
-
|
|
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
|
-
|
|
581
|
+
## Version Detection
|
|
295
582
|
|
|
296
|
-
|
|
297
|
-
./build.sh
|
|
298
|
-
```
|
|
583
|
+
Automatically detect the XWasser schema version from an XML document:
|
|
299
584
|
|
|
300
|
-
|
|
585
|
+
```typescript
|
|
586
|
+
import { detect_version } from "xoev-xwasser";
|
|
301
587
|
|
|
302
|
-
|
|
588
|
+
const version = detect_version(xmlString.slice(0, 1024));
|
|
589
|
+
console.log(version); // e.g. "100"
|
|
590
|
+
```
|
|
303
591
|
|
|
304
|
-
|
|
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
|
-
|
|
309
|
-
cargo test --features schema,trace
|
|
594
|
+
## Web (Browser) Usage
|
|
310
595
|
|
|
311
|
-
|
|
312
|
-
cargo test --features builder
|
|
596
|
+
For browser environments, use the `xoev-xwasser-web` package which compiles with the Web target:
|
|
313
597
|
|
|
314
|
-
|
|
315
|
-
|
|
598
|
+
```bash
|
|
599
|
+
npm install xoev-xwasser-web
|
|
316
600
|
```
|
|
317
601
|
|
|
318
|
-
|
|
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
|
-
```
|
|
321
|
-
|
|
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
|
-
|
|
329
|
-
# Watch mode with auto-rebuild
|
|
330
|
-
cargo watch --watch src -s "./build.sh"
|
|
331
|
-
```
|
|
613
|
+
## TypeScript Types
|
|
332
614
|
|
|
333
|
-
|
|
615
|
+
The package includes full TypeScript type definitions. All model types are exported from the main entry point:
|
|
334
616
|
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
|
|
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.
|