HighwayData XML — Schema 1.1

Draft for review · 2026-08-28 (revision 2) · technical peer audience (Grasshopper reader implementers)

Normative specification. Status: draft for review (2026-08-28, revision 2). Reference producer: iolabs_point_cloud_modelling_export.write_xml.create_xml / prettify_xml (package iolabs-point-cloud-modelling-export; schema 1.0 as of 0.9.0, schema 1.1 targeted at 0.10.0).

Basis: docs/hbw_feature_classes_xml_plan.md (design), owner decisions of 2026-08-28 rounds 1 and 2 (binding; round 2 overrides round 1, and both override the plan — see Appendix A), poster "2D plans overview" (18 columns).

1. Scope & terminology

1.1 Purpose

• R-1.1.1 This document is the contract between the ioLabs detection pipeline (producer side) and HBW's Grasshopper 2D-plan script (consumer side). Both are implemented independently and concurrently; the XML document is the only agreed interface between them.
• R-1.1.2 The primary subject of this specification is therefore document conformance: which elements exist, in what order, with what cardinality, and what their values mean (§§3–5, §6.1). A conforming document is defined without reference to any particular writer.
• R-1.1.3 Writer-side validation (§6.2, §6.3) is a secondary, deliberately partial projection of §6.1. A writer that emits a non-conforming document because it only warned is a producer bug, not a schema ambiguity. Nothing in §6.2/§6.3 narrows §6.1.
• R-1.1.4 §8 additionally specifies the data dict accepted by create_xml, because that dict is the supported way for ioLabs producers to emit a conforming document. Other producers MAY emit conforming documents by other means.
• R-1.1.5 Out of scope: the customer-side Data catalog (SYMB#### block names, rotation modes DRW/OWN/NO/VEC/ORD), CAD layer assignment (Appendix C is informative), hatch generation, tree-group outline detection, DXF export, and any XSD artefact. No SYMB name, rotation mode, or CAD layer name is carried in the XML.
• R-1.1.6 This document specifies behaviour and wire format only. It prescribes no implementation structure.

1.2 Terminology

RFC 2119: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, REQUIRED, OPTIONAL.

• R-1.2.1 Rules are numbered R-<section>.<sub>.<n> and are normative.
• R-1.2.2 Notes numbered N-<section>.<sub>.<n> are informative and impose no requirement.
• R-1.2.3 "Emitted" means present in the serialised document. "Byte-identical" is measured on the UTF-8 bytes produced by prettify_xml(create_xml(data)).

2. Versioning & compatibility

2.1 Version identification

• R-2.1.1 A 1.1 document MUST contain exactly one MetaData/SchemaVersion with text 1.1. A 1.1 writer MUST emit it unconditionally, including for documents built from legacy dicts.
• R-2.1.2 A consumer treats the absence of MetaData/SchemaVersion as schema 1.0.
• R-2.1.3 SchemaVersion MUST match ^[0-9]+\.[0-9]+$. A minor increment is additive under §2.3; a major increment signals a breaking change and is out of scope here.
• R-2.1.4 A producer MAY set metadata.schema_version; the writer MUST reject any value other than the version it implements. Absence defaults to 1.1.

2.2 What 1.1 does not do

• R-2.2.1 No element defined in 1.0 is renamed, removed, retyped, or moved. In particular the four containers and their four NumberOf* siblings are still emitted for every Feature, empty and 0 when the corresponding list is absent.
• R-2.2.2 1.1 MUST NOT change the value semantics of any 1.0 element.
• R-2.2.3 Three feature groups are frozen and MUST NOT carry any NEW element: lane markings (§7.21), road axes (§7.22), and cross-section points (§7.23). Their serialisation is byte-identical to 0.9.0 apart from MetaData/SchemaVersion.
• R-2.2.4 There is no Feature/Layer element in 1.1. The CAD layer name is a drawing artefact, is constant per feature class, and is not derivable from point-cloud data; the consumer derives it from Feature/Type using its own mapping. Appendix C gives that mapping informatively.

2.3 Trailing-placement rule

• R-2.3.1 Every NEW element MUST be placed after all 1.0 children of its parent, so that both name-based and index-based readers of 1.0 content are unaffected.
• R-2.3.2 Single documented exception: Polyline/Type is placed immediately after Polyline/LaneID, the slot Line/Type and Spline/Type have occupied since 0.8.0. This is safe because Polyline/Type is emitted only when a producer supplies it, and no legacy producer does; no legacy document's child indices shift. A consumer MUST NOT assume Polyline child index 2 is RoadPoint.
• R-2.3.3 Within the trailing block, the order of §3 is normative and a consumer MAY rely on it.
• N-2.3.4 Consumers are expected to ignore unknown trailing children rather than fail (confirmed for lane_xml.py; to be confirmed for Grasshopper by a pre-release sample-file acceptance run — §10 O-18).

2.4 Legacy producer output under 1.1

• R-2.4.1 For a data dict containing no 1.1 key, a 1.1 writer's output MUST be byte-identical to the 0.9.0 writer's output except for the single inserted line <SchemaVersion>1.1</SchemaVersion> as the last child of MetaData.
• R-2.4.2 Elements that 1.1 makes optional (Point/RoadPoint, Polyline/RoadPoint, Spline/RoadPoint) MUST still be emitted whenever the corresponding dict key is present, so R-2.4.1 holds.
• R-2.4.3 No writer-side validation may prevent R-2.4.1. Conformance rules that 0.9.0 output could violate are scoped per R-2.6.2.
• R-2.4.4 A 1.1 writer MUST NOT introduce a compatibility/downgrade output mode. If HBW's reader proves strict, that is a separate change.

2.5 Class-key resolution

• R-2.5.1 Feature/Type is the only class key. A consumer MUST filter and dispatch on Feature/Type.
• N-2.5.2 This is consistent with the historic DWG→XML sample files, in which Feature/Type already carried the German CAD layer name (Bordstein, Schutzeinrichtung, Fahrbahnrand -bituminös-, …). A consumer that keys its catalog by Type therefore handles both legacy and 1.1 documents with one lookup table.
• R-2.5.3 A consumer SHOULD ignore any element it does not recognise, at any depth.
• N-2.5.4 For guard-rail labels a 1.1 consumer reads the guardrail_type attribute and Annotation/Text; for 1.0 files it may fall back to the legacy Point/FeatureClass suffix convention Guard Rails_<type>.

2.6 The "1.1-touched" scope

• R-2.6.1 A geometry element is 1.1-touched if its producer supplied any 1.1 key for it: direction, shapes, annotation, attributes, closed, sorting_code (or the sort_class/pair_index/pair_role triple), or type on a polyline. A Feature is 1.1-touched if it supplies attributes or contains a 1.1-touched geometry element.
• R-2.6.2 Conformance rules that 0.9.0 output could violate (R-6.1.6 minimum vertex/control-point counts) apply as writer hard errors only to 1.1-touched elements. For elements that are not 1.1-touched the writer SHOULD warn instead (R-6.3.1). The conformance requirement itself is unchanged for new documents.

3. Document structure

Complete element tree. 1.0 = present in 0.9.0; NEW = introduced by 1.1. Children are listed in the order in which they MUST be emitted.

Cardinality markers: 1 exactly one · ? 0..1 · * 0..n · + 1..n · 2+ 2..n · 1+/2+ 1..n for legacy content, 2..n required by every 1.1 profile (§7).

HighwayData                                   1.0   1
├─ MetaData                                   1.0   1
│  ├─ CreationDate                            1.0   1
│  ├─ Source                                  1.0   1
│  ├─ SoftwareVersion                         1.0   1
│  ├─ PipelineVersions                        1.0   ?
│  │  └─ Step  @name @date?                   1.0   *
│  │     ├─ SegmentRange  @segments @date     1.0   *      (variant A)
│  │     │  └─ Package  @name @version        1.0   *
│  │     └─ Package  @name @version           1.0   *      (variant B)
│  └─ SchemaVersion                           NEW   1
├─ Geoshift                                   1.0   ?
│  ├─ X                                       1.0   1
│  ├─ Y                                       1.0   1
│  └─ Z                                       1.0   1
└─ Features                                   1.0   1
   └─ Feature                                 1.0   *
      ├─ Type                                 1.0   1
      ├─ ID                                   1.0   1
      ├─ LaneID                               1.0   1
      ├─ Lines                                1.0   1
      │  └─ Line                              1.0   *
      │     ├─ ID                             1.0   1
      │     ├─ LaneID                         1.0   1
      │     ├─ Type                           1.0   ?
      │     ├─ StartPoint (X, Y, Z)           1.0   1
      │     ├─ EndPoint   (X, Y, Z)           1.0   1
      │     ├─ RoadPoint  (From, To)          1.0   1
      │     ├─ Width                          1.0   ?
      │     │  ├─ Value                       1.0   ?
      │     │  ├─ Sigma                       1.0   ?
      │     │  ├─ Status                      1.0   ?
      │     │  └─ Flagged                     1.0   ?
      │     ├─ Annotation                     NEW   ?
      │     └─ Attributes                     NEW   ?
      ├─ NumberOfLines                        1.0   1
      ├─ Points                               1.0   1
      │  └─ Point                             1.0   *
      │     ├─ ID                             1.0   1
      │     ├─ LaneID                         1.0   1
      │     ├─ PointerNumber                  1.0   1
      │     ├─ X                              1.0   1
      │     ├─ Y                              1.0   1
      │     ├─ Z                              1.0   1
      │     ├─ Color                          1.0   1
      │     ├─ FeatureClass                   1.0   1
      │     ├─ FeatureID                      1.0   1
      │     ├─ RoadPoint                      1.0   ?   (1 in 1.0; ? for 1.1 producers)
      │     ├─ Direction (X, Y, Z)            NEW   ?
      │     ├─ Shapes                         NEW   ?
      │     │  └─ Shape  @role @type          NEW   +
      │     │     ├─ Base (X, Y, Z)           NEW   1
      │     │     ├─ Top  (X, Y, Z)           NEW   ?   (exactly one of Top | Apex,
      │     │     ├─ Apex (X, Y, Z)           NEW   ?    selected by @type — R-4.20.3)
      │     │     └─ Diameter                 NEW   1
      │     ├─ Annotation                     NEW   ?
      │     └─ Attributes                     NEW   ?
      ├─ NumberOfPoints                       1.0   1
      ├─ Polylines                            1.0   1
      │  └─ Polyline                          1.0   *
      │     ├─ ID                             1.0   1
      │     ├─ LaneID                         1.0   1
      │     ├─ Type                           NEW   ?   (position per R-2.3.2)
      │     ├─ RoadPoint (From, To)           1.0   ?   (1 in 1.0; ? for 1.1 producers)
      │     ├─ Vertices                       1.0   1
      │     │  └─ Vertex                      1.0   1+/2+
      │     │     ├─ ID                       1.0   1
      │     │     ├─ X                        1.0   1
      │     │     ├─ Y                        1.0   1
      │     │     └─ Z                        1.0   1
      │     ├─ SortingCode                    NEW   ?
      │     ├─ Closed                         NEW   ?
      │     ├─ Annotation                     NEW   ?
      │     └─ Attributes                     NEW   ?
      ├─ NumberOfPolylines                    1.0   1
      ├─ Splines                              1.0   1
      │  └─ Spline                            1.0   *
      │     ├─ ID                             1.0   1
      │     ├─ LaneID                         1.0   1
      │     ├─ Type                           1.0   ?
      │     ├─ RoadPoint (From, To)           1.0   ?   (1 in 1.0; ? for 1.1 producers)
      │     ├─ Width  (as Line/Width)         1.0   ?
      │     ├─ Fit_Points                     1.0   1   (MAY be empty)
      │     │  └─ Point (ID, X, Y, Z)         1.0   *
      │     ├─ Control_Points                 1.0   1
      │     │  └─ Point (ID, X, Y, Z)         1.0   1+/2+
      │     ├─ Annotation                     NEW   ?
      │     └─ Attributes                     NEW   ?
      ├─ NumberOfSplines                      1.0   1
      └─ Attributes                           NEW   ?

Shared NEW sub-trees, referenced above:

Annotation                                    NEW
├─ Display                                    NEW   1
├─ Legible                                    NEW   ?   (enumeration — R-5.10.1)
└─ Text                                       NEW   *

Attributes                                    NEW
└─ Attribute  @name @type                     NEW   +

• R-3.1 Children MUST be emitted in exactly the order above. A consumer MAY rely on that order.
• R-3.2 No element outside this tree may be emitted.
• R-3.3 Lines, Points, Polylines, Splines and their NumberOf* siblings MUST always be emitted, interleaved exactly as shown (Lines, NumberOfLines, Points, NumberOfPoints, …).
• R-3.4 NumberOf* MUST equal the count of child geometry elements in the immediately preceding container.
• R-3.5 No element carries mixed content; every element is element-only or text-only.
• R-3.6 Attributes appear only where listed: Step/@name, Step/@date, SegmentRange/@segments, SegmentRange/@date, Package/@name, Package/@version, Attribute/@name, Attribute/@type, Shape/@role, Shape/@type.
• R-3.7 The 1+/2+ marker means: a document containing legacy content MAY carry a one-vertex Polyline or a one-point Control_Points (0.9.0 permitted it); every geometry belonging to a §7 1.1 profile MUST carry at least two. Enforcement scope: R-2.6.2.

4. Element reference

"Position" is relative to siblings. Value rules referencing §5 are normative.

4.1 HighwayData — 1.0

Root, cardinality 1. Children in order: MetaData, Geoshift?, Features.

4.2 MetaData — 1.0

Parent HighwayData, 1, first. Children: CreationDate, Source, SoftwareVersion, PipelineVersions?, SchemaVersion.

4.3 CreationDate, Source, SoftwareVersion — 1.0

Parent MetaData, 1 each, positions 1–3. Text, emitted verbatim from the producer (no str() coercion; producers supply strings). CreationDate SHOULD be ISO-8601.

4.4 PipelineVersions / Step / SegmentRange / Package — 1.0

Unchanged from 1.0. - R-4.4.1 Step/@name REQUIRED. - R-4.4.2 A Step uses either the SegmentRange variant or the flat variant, never both. In the flat variant Step/@date is always set — to the empty string when the producer supplies no date — and Package children follow. In the SegmentRange variant Step carries no @date. - R-4.4.3 SegmentRange/@segments is the segment list joined with ", ", where a range a..b renders a-b and a singleton (a == b) renders a. SegmentRange/@date REQUIRED.

4.5 SchemaVersion — NEW

Parent MetaData, 1, last child. Text 1.1 (R-2.1.1). Example: <SchemaVersion>1.1</SchemaVersion>.

4.6 Geoshift (X,Y,Z) — 1.0

Parent HighwayData, 0..1, after MetaData. Emitted iff the producer supplies it. Numeric text per §5.1. Adding Geoshift to an export-frame coordinate yields the absolute coordinate.

4.7 Features — 1.0

Parent HighwayData, 1, last. Contains 0..n Feature. Always emitted, even when empty.

4.8 Feature — 1.0

Parent Features, 0..n, document order = producer order. Children per §3.

4.9 Feature/Type — 1.0

1, first child. Text, non-empty. The stable semantic class id and the sole class key (R-2.5.1). Values in use: Cross Section, Center Lines, Axis of the Edge, Central Axis, Both-Sides Central Axis, Single-Side Central Axis, guardrail, guardrail_support, guardrail_top_rail, noise_wall, plus the 1.1 classes of §7. Existing lower-case strings are preserved as-is; NEW classes use English singular Title Case. - R-4.9.1 The writer MUST NOT validate Type against a closed vocabulary; producers may add classes without a writer release.

4.10 Feature/ID — 1.0

1, second. Text, non-empty, document-unique (R-6.1.2; producer obligation, writer warns).

4.11 Feature/LaneID — 1.0

1, third. Text. "0" when the feature is not lane-bound. Always emitted. - R-4.11.1 Every geometry element carries its own LaneID, always emitted. A legacy dict MUST supply the geometry-level lane_id (the 0.9.0 writer raises without it, and R-2.4.1 depends on it). A 1.1-touched geometry MAY omit it, in which case the writer defaults it to the owning Feature/LaneID.

4.12 Feature/Attributes — NEW

0..1, last child of Feature (after NumberOfSplines). Feature-level metadata; see §4.28. Rare — per-geometry Attributes is preferred.

4.13 (reserved — Feature/Layer was removed by R-2.2.4)

No element occupies this slot. Documents produced from pre-release drafts may contain a <Layer> child of Feature; consumers ignore it (R-2.5.3).

4.14 Line and children — 1.0

ID, LaneID text; Type 0..1 immediately after LaneID; StartPoint/EndPoint with X,Y,Z; RoadPoint with From,To; Width 0..1. 1.1 appends Annotation? then Attributes? after Width. - R-4.14.1 Line/Type is an open string; the writer emits whatever the producer supplies and MUST NOT restrict it. - N-4.14.2 The vocabulary in use today is solid | dashed (lane markings). This is informative.

4.15 Width (Value,Sigma,Status,Flagged) — 1.0

Parent Line or Spline, 0..1. Each child is emitted only when its source value is not None. Flagged is str(bool(v)).lower(). Unchanged in 1.1.

4.16 Point — 1.0 (extended)

Parent Points, 0..n. In 1.0 a Point was only a cross-section sample; in 1.1 it is either that (frozen, §7.23) or a point symbol (§7 point classes).

4.17 Point legacy children — 1.0

ID (text, non-empty), LaneID (text), PointerNumber (integer text), X,Y,Z (numeric text, export frame), Color, FeatureClass, FeatureID (text; str()-coerced — hence the literal None seen in legacy cross-section output), RoadPoint (scalar numeric text — not a From/To pair, unlike Line/Polyline/Spline). - R-4.17.1 PointerNumber, Color, FeatureClass, FeatureID MUST always be emitted. When a 1.1 producer omits the source key the writer MUST default: PointerNumber = 1-based index of the point within its Points container; Color = empty text; FeatureClass = the owning Feature/Type; FeatureID = the owning Feature/ID. - R-4.17.2 These defaults apply only when the key is absent. A key present with value None is str()-coerced to the text None, preserving 1.0 behaviour (R-2.4.1). - R-4.17.3 RoadPoint MUST be emitted iff the producer supplies it. Point symbols with no chainage omit it.

4.18 Point/Direction — NEW

0..1, immediately after RoadPoint (or after FeatureID when RoadPoint is omitted). Children X,Y,Z in that order, numeric text. Value rules: §5.5. Example:

<Direction><X>0.963767</X><Y>-0.221946</Y><Z>0.147964</Z></Direction>

4.19 Point/Shapes — NEW

0..1, after Direction. Contains 1..n Shape. Emitted iff the producer supplies a non-empty shape list. Producer order is preserved.

4.20 Point/Shapes/Shape — NEW

1..n. Attributes: role (REQUIRED, free text; known: trunk, crown, post) and type (REQUIRED, cylinder | cone). - R-4.20.1 type="cylinder" — children in order: Base (X,Y,Z), Top (X,Y,Z), Diameter. - R-4.20.2 type="cone" — children in order: Base (X,Y,Z), Apex (X,Y,Z), Diameter. - R-4.20.3 Exactly one of Top / Apex MUST be present, selected by @type. Emitting both, neither, or the one that does not match @type is non-conforming. Geometry semantics: §5.8. Example:

<Shapes>
  <Shape role="trunk" type="cylinder">
    <Base><X>-109.06</X><Y>-383.29</Y><Z>0.02</Z></Base>
    <Top><X>-109.04</X><Y>-383.27</Y><Z>2.52</Z></Top>
    <Diameter>0.3</Diameter>
  </Shape>
  <Shape role="crown" type="cone">
    <Base><X>-109.04</X><Y>-383.27</Y><Z>2.52</Z></Base>
    <Apex><X>-109.01</X><Y>-383.22</Y><Z>8.52</Z></Apex>
    <Diameter>7.0</Diameter>
  </Shape>
</Shapes>

4.21 Annotation — NEW

Parent: Point, Polyline, Spline, Line. 0..1. Position: after all 1.0 children and after Direction/Shapes/SortingCode/Closed where those exist; immediately before Attributes. Children in order: Display (1), Legible (0..1), Text (0..n). Emitted iff the producer supplies it — legacy producers are unaffected. - R-4.21.1 A producer MUST supply Annotation for every geometry whose §7.1 "Annot." column reads true or false, including when the value is false, so the poster's boolean is explicit in the document. Classes whose "Annot." column reads — (noise_wall, guardrail_support, guardrail_top_rail, and all frozen profiles) MUST NOT carry Annotation.

4.22 Annotation/Display — NEW

1, first. Boolean text, lower-case (§5.2). Corresponds to the poster's "has annotation display" / "has a description". - R-4.22.1 Display=true means the consumer renders a label at this geometry. Whether the label text travels in the document is profile-dependent (§4.24, §7).

4.23 Annotation/Legible — NEW

0..1, second child of Annotation. Enumeration, not a boolean: full | partial | none (R-5.10.1). It reports how much of the text carried by the physical object was recoverable from the point cloud.

• R-4.23.1 Legible MUST be emitted for feature classes whose annotation text is transcribed from a physical object — today KM Sign only; Traffic Sign plates later.
• R-4.23.2 For any other class a producer SHOULD NOT emit Legible; the writer SHOULD warn (R-6.3.6). It carries no meaning for labels computed by us (elevation labels, tree Ø= labels, guard-rail type labels).
• R-4.23.3 When Legible is none, Text MUST be omitted while Display stays true, so the consumer still places the symbol without a label.
• R-4.23.4 When Legible is full, no Text value may contain a substitution mark (R-4.24.5); the writer SHOULD warn if one does (R-6.3.16).
• N-4.23.5 The object was detected in every case; Legible describes only the legibility of its inscription, never the confidence of the detection.

4.24 Annotation/Text — NEW

0..n, after Display/Legible. Text, UTF-8. One element per rendered line, in draw order. - R-4.24.1 Text absent while Display=true is conforming and profile-dependent. It means either the consumer derives the label itself (elevation labels — §7.13, §7.23, N-5.7.2) or the label was unrecoverable (Legible=none — R-4.23.3). - R-4.24.2 Text MUST NOT be emitted when Display=false (R-6.2.4). - R-4.24.3 A producer MUST NOT put \n or \r inside a Text value; multi-line labels use multiple Text elements. The writer does not split such a value; it SHOULD warn (R-6.3.4). - R-4.24.4 Text is a display string produced upstream. The writer MUST NOT format, localise, round, or reorder it. - R-4.24.5 (substitution marks) Under Legible=partial, an unreadable character inside an emitted line MUST be written as a single ? — one ? per unreadable character. When the number of unreadable characters is unknown, the run MUST be written as ?… (U+003F followed by U+2026). These two forms are the only substitution marks; a line that was entirely unreadable is omitted rather than filled with marks. - N-4.24.6 A consumer SHOULD render partial text verbatim, ? and ?… included: the marks tell the plan reader that a sign exists and how much of it was recovered. Stripping them would silently fabricate a complete label. Example (KM sign, 3 lines):

<Annotation><Display>true</Display><Legible>full</Legible>
  <Text>KM 46.5</Text><Text>Abs. 90</Text><Text>Station 0,25</Text></Annotation>

4.25 Polyline/Type — NEW

0..1, immediately after LaneID (R-2.3.2). Open string. Known values: top, bottom (trench/slope outlines) and guard-rail sub-kinds. Redundant with SortingCode on purpose (human readability); the code is the contract.

4.26 Polyline/SortingCode — NEW

0..1, immediately after Vertices. Text matching R-5.6.1. Absent = the poster's null.

4.27 Polyline/Closed — NEW

0..1, after SortingCode. Boolean text, lower-case. true = the vertex list describes a closed ring; the consumer closes it. - R-4.27.1 When Closed is true the producer MUST NOT repeat the first vertex as the last, and the polyline MUST have at least 3 vertices. The writer SHOULD warn on either (R-6.3.8, R-6.3.9).

4.28 Attributes / Attribute — NEW

Parent: Feature, Point, Polyline, Spline, Line. 0..1, always the last child of its parent. Contains 1..n Attribute; Attributes MUST NOT be emitted empty (R-6.2.9). Attribute/@name REQUIRED, snake_case, unique within its Attributes; units belong in the name (length_m). Attribute/@type REQUIRED, one of string | integer | float | boolean (§5.9). Text = the serialised value. - R-4.28.1 Attribute children MUST be emitted sorted ascending by @name (deterministic output). - R-4.28.2 An attribute whose value is None MUST be skipped entirely. Example:

<Attributes>
  <Attribute name="guardrail_type" type="string">EDSP</Attribute>
  <Attribute name="post_count" type="integer">37</Attribute>
</Attributes>

4.29 Polyline legacy children — 1.0

ID (text), LaneID (text), RoadPoint (From,To), Vertices. - R-4.29.1 RoadPoint MUST be emitted iff the producer supplies it (optional for 1.1 producers, always present for legacy ones). - R-4.29.2 Vertices MUST always be emitted; vertex count per R-3.7. - R-4.29.3 The writer MUST generate Vertex/ID as f"{polyline_id}-{index+1}" (1-based). Producers MUST NOT supply vertex ids.

4.30 Spline legacy children — 1.0

ID, LaneID, Type?, RoadPoint?, Width?, Fit_Points, Control_Points. - R-4.30.1 Fit_Points MUST always be emitted; it MAY be empty (<Fit_Points/>), so the Spline child layout never varies. - R-4.30.2 Control_Points MUST always be emitted; point count per R-3.7. - R-4.30.3 The writer MUST generate ids f"{spline_id}_{n+1}", where n is the 0-based running index across Fit_Points followed by Control_Points — control-point numbering continues after the fit points. - R-4.30.4 RoadPoint MUST be emitted iff the producer supplies it. - R-4.30.5 Spline/Type is an open string (as R-4.14.1).

5. Value types & formatting

5.1 Numbers

• R-5.1.1 Numeric values are serialised as Python str(value); the writer MUST NOT round, pad, localise, or apply a format spec. 0.1 → 0.1; 1.0 → 1.0; 12 → 12.
• R-5.1.2 Precision is the producer's concern: supply an already-rounded float, or a pre-formatted str.
• R-5.1.3 Producers MUST NOT supply NaN or ±Inf in any coordinate or length. The writer hard-rejects this only inside NEW elements (R-6.2.5, R-6.2.7); elsewhere it SHOULD warn (R-6.3.3).
• R-5.1.4 The decimal separator in numeric element text MUST be .. A decimal comma is permitted only inside Annotation/Text (display strings, e.g. Ø= 0,30/7,0m).
• R-5.1.5 All coordinates and lengths are metres in the export frame unless stated otherwise.

5.2 Booleans

• R-5.2.1 Boolean element text MUST be exactly true or false (lower-case), i.e. str(bool(v)).lower(). Applies to Width/Flagged (1.0), Annotation/Display, Polyline/Closed, and Attribute values of @type="boolean".
• N-5.2.2 True, 1, yes are not valid boolean text. Consumers are not expected to accept them.

5.3 Text & encoding

• R-5.3.1 The document is UTF-8. prettify_xml returns a str beginning with <?xml version="1.0" encoding="UTF-8"?>; whoever writes it to a file or stream MUST encode it as UTF-8 bytes, so that the declaration is truthful.
• R-5.3.2 Non-ASCII characters (ä ö ü ß Ø ⌀) MUST be emitted as literal UTF-8, not character references.
• R-5.3.3 &, <, > MUST be XML-escaped by the serialiser; producers MUST NOT pre-escape.
• R-5.3.4 The writer MUST NOT trim or normalise element text. Consumers SHOULD strip leading and trailing whitespace when reading element text, as a defensive measure.
• R-5.3.5 A NEW element's text value MUST NOT be empty or whitespace-only where §4 requires content (SchemaVersion, Annotation/Text when emitted, Attribute text of @type="string" where the profile requires a value, SortingCode, Polyline/Type, Shape numeric children). The writer MUST reject such a value (R-6.2.10). This rule does not apply to 1.0 elements, which may legitimately be empty (Color).
• N-5.3.6 Ø (U+00D8) and ⌀ (U+2300) are distinct; the poster shows ⌀ in its template and Ø in its example. Producers pick one per deployment; the writer never substitutes (§10 O-15).

5.4 Identifiers

• R-5.4.1 Feature/ID, Point/ID, Line/ID, Polyline/ID, Spline/ID are producer-supplied, non-empty, and MUST be unique within the document. This is a producer obligation; the writer SHOULD warn (R-6.3.2) and MUST NOT reject, so R-2.4.1 holds for legacy input.
• R-5.4.2 Ids SHOULD match ^[A-Za-z0-9_.:-]+$ so derived vertex ids stay parseable.
• R-5.4.3 Vertex and spline-point ids are writer-generated (R-4.29.3, R-4.30.3) and MUST NOT be supplied.
• R-5.4.4 LaneID is text, not numeric; "0" denotes "no lane".

5.5 Direction vectors

• R-5.5.1 Direction is a full 3D unit vector in the export frame: |v| = 1 ± 1e-6. Any orientation is representable; Z MAY be non-zero (a tilted or inclined sign plate).
• R-5.5.2 Components MUST be finite and the vector MUST NOT be zero-length. The writer MUST reject a violation (R-6.2.5).
• R-5.5.3 Producers normalise. The writer MUST NOT normalise and MUST NOT silently repair a non-unit vector; it SHOULD warn (R-6.3.5).
• N-5.5.4 A consumer that needs a plan (2D) rotation projects the vector onto the XY plane and normalises there. Catalog rotation mode VEC is the main consumer (traffic signs, KM signs, shafts, gullys).
• R-5.5.5 Semantics by class: for sign-like classes (Traffic Sign, KM Sign) the vector is the plate normal pointing towards oncoming traffic; for Gully, Shaft, and the remaining point classes it is the road-axis tangent at the point.
• R-5.5.6 Direction MUST be emitted for every 1.1 point class of §7, including classes whose catalog rotation mode ignores it (NO, ORD, DRW).
• R-5.5.7 When the true orientation could not be measured, the producer SHOULD emit the substitute vector and an attribute direction_source with value fallback in the same Point's Attributes; value measured otherwise (§10 O-14).

5.6 Sorting-code grammar

• R-5.6.1 A SortingCode MUST match exactly: ^[A-Z]+(0|[1-9][0-9]*)\$[AB]$ This regex is the single normative definition. Capture semantics: [A-Z]+ = family (G = Graben/Grabensohle, B = Böschung); the digits = pair index, an unbounded non-negative integer with no leading zeros; $ = separator; trailing A = top outline, B = bottom outline.
• R-5.6.2 The pair index is unique per family per XML document. G10$A is well-formed.
• R-5.6.3 Every (family, index) pair occurring in a document MUST occur exactly twice — once with A and once with B. Because the two halves may be produced by different detectors or segments, an incomplete pair MUST NOT abort the document; the writer SHOULD warn (R-6.3.7).
• R-5.6.4 Two SortingCode values MUST NOT be equal within one document. The writer MUST reject a duplicate (R-6.2.3).
• R-5.6.5 The writer accepts either a ready sorting_code string, or the triple sort_class (family), pair_index (int), pair_role ∈ top|bottom, and composes f"{sort_class}{pair_index}${role_letter}" with top→A, bottom→B. Supplying both forms, or the triple incompletely, is an error (R-6.2.6).

5.7 Annotation text conventions

• R-5.7.1 One Text per rendered line; no embedded newlines (R-4.24.3).
• N-5.7.2 (informative — consumer rendering guidance for elevation labels) For Terrain Point and Cross Section, no Text travels in the document; the consumer renders the label from the point's Z. The agreed rendering is the absolute height — export-frame Z plus Geoshift/Z — with exactly three decimals, a dot separator, no unit suffix and no thousands separator, e.g. 47.333. This is guidance, not a writer rule; the document carries only the numbers.
• N-5.7.3 (informative — tree label) The reference rendering is Ø= 0,30/7,0m: trunk diameter then crown diameter, decimal comma, two decimals for the trunk and one for the crown. It is produced upstream and travels as Text; the writer MUST NOT derive it from Shapes (R-6.4.3). See §10 O-15.
• R-5.7.4 (KM sign) Up to three Text lines, in order: KM <km>, Abs. <section>, Station <station>. A line whose source field is unknown is omitted, keeping the remaining lines in order.
• R-5.7.5 (guard rail) The Text is the guard-rail type label as drawn (EDSP, ESP 2,0), matching the machine value of the guardrail_type attribute.

5.8 Shape geometry semantics

• R-5.8.1 A Shape locks its position in 3D explicitly. Its axis is the segment Base → Top (cylinder) or Base → Apex (cone). Any orientation is representable, including leaning trunks; nothing is implied by the owning Point's coordinates.
• R-5.8.2 All of Base, Top, Apex are absolute points in the export frame, in metres, with the same X,Y,Z conventions as Point/X|Y|Z.
• R-5.8.3 Base is the centre of the bottom circle. Top is the centre of the top circle of a cylinder; Apex is the tip of a cone.
• R-5.8.4 Diameter is the diameter of the Base circle, in metres, and MUST be finite and > 0. For a cylinder the diameter is constant along the axis.
• R-5.8.5 The axis MUST have non-zero length: Base != Top / Base != Apex.
• R-5.8.6 Shape is generic: any point symbol MAY carry one (e.g. a verge post cylinder). @role is free text scoped by the feature class.
• R-5.8.7 For Tree: a producer MUST emit role="trunk" with @type="cylinder", and role="crown" with @type="cylinder" or "cone"; exactly one shape of each role. The writer SHOULD warn on a violation (R-6.3.10) rather than reject, so unexpected roles are still exported.
• N-5.8.8 For a tree the crown's Base normally coincides with the trunk's Top; nothing requires it.

5.9 Attribute/@type vocabulary

• R-5.9.1 bool MUST map to boolean, never to integer, even though bool subclasses int.
• R-5.9.2 A value that is a Mapping, a sequence, or any other non-scalar MUST be rejected (R-6.2.8); nesting inside Attributes is not representable.
• R-5.9.3 Producers SHOULD encode the unit in @name rather than in the text.
• N-5.9.4 The convention in use: _m metres, _deg degrees, _s seconds — e.g. length_m, top_height_p90_m. This is a naming habit, not a grammar; nothing validates it.

5.10 Enumerations

• R-5.10.1 Annotation/Legible text MUST be exactly one of full, partial, none — lower-case, no surrounding whitespace, no other value. The writer MUST reject anything else (R-6.2.16).
• R-5.10.2 Shape/@type MUST be exactly cylinder or cone (R-4.20.1/2).
• R-5.10.3 Attribute/@type MUST be one of string, integer, float, boolean (§5.9).
• N-5.10.4 Enumerations are closed: a consumer encountering an unknown value SHOULD treat the element as absent rather than guess. Extending an enumeration requires a schema minor version bump.

6. Conformance & validation

§6.1 defines a conforming document — the contract of R-1.1.2, checkable by any consumer or validator. §6.2 and §6.3 state what the reference writer does about each rule; they are a partial projection of §6.1 and never widen or narrow it (R-1.1.3). Every §6.1 rule appears in exactly one of §6.2, §6.3, or §6.4.

6.1 Document conformance

6.2 Writer MUST reject (hard errors, nothing is emitted)

• R-6.2.14 An error message MUST identify the offending Feature/ID and geometry ID where such a context exists; document-level errors (R-6.2.3, R-6.2.11) name the offending values instead.
• R-6.2.15 Document-level checks (R-6.2.3) run after the whole tree is built and MUST prevent the document from being returned.

6.3 Writer SHOULD warn (document is still emitted)

6.4 Explicit non-validations

• R-6.4.1 The writer MUST NOT validate Feature/Type, Line/Type, Spline/Type, or Polyline/Type against a closed vocabulary, and MUST NOT branch its emission logic on Feature/Type. All features are treated uniformly. (§7 profile compliance is a producer obligation; warnings that reference §7.1 are advisory table lookups, not emission logic.)
• R-6.4.2 The writer MUST ignore unknown dict keys silently. <Attributes> is built only from an explicit attributes mapping (R-8.6.1); no other key contributes an attribute.
• R-6.4.3 The writer MUST NOT derive Annotation/Text from Shapes, Z, or guardrail_type, nor infer Direction from geometry.
• R-6.4.4 The writer MUST NOT validate coordinate ranges, geometry self-intersection, polygon orientation, or annotation spelling.
• R-6.4.5 The writer MUST NOT reorder producer-supplied lists (features, geometries, shapes, Text lines). Only Attribute children are sorted (R-4.28.1).

7. Feature-class profiles

• R-7.0.1 A profile is a producer obligation. Every rule in §7 constrains what a producer may emit for that Feature/Type; none of it changes how the writer serialises a document (R-6.4.1).
• R-7.0.2 Producers MUST NOT supply any 1.1 key for a feature belonging to a frozen profile (§7.21–§7.23): no direction, shapes, annotation, attributes, closed, sorting_code (or the sort_class/pair_index/pair_role triple), or polyline type. layer is not a schema concept at all (R-2.2.4); like any unknown key it is silently ignored (R-6.4.2). Frozen-profile output stays byte-identical to 0.9.0 apart from MetaData/SchemaVersion.
• R-7.0.3 Unless a profile says otherwise, 1.1 profiles set LaneID = "0" on the feature and on each of its geometry elements (they are not lane-bound) and omit RoadPoint. Frozen profiles keep their existing LaneID and RoadPoint semantics — lane markings and cross sections carry real lane ids.
• N-7.0.4 The CAD layer name for each class is not in the document. Appendix C lists the expected Type → layer mapping informatively so the consumer can build its catalog lookup.

7.1 Summary table

"Annot." = the required Annotation/Display value, or — when the class MUST NOT carry Annotation (R-4.21.1). "Text" = whether label text travels in the document.

7.2 Tree Line

One Feature per tree line, one Spline with Fit_Points empty and ≥2 Control_Points. Annotation: <Display>false</Display>, no Text. Spline/Type, Width, RoadPoint omitted. Crown symbols are placed by the consumer along the spline from its catalog.

7.3 Tree Group

Decision Q10 (ALT 1): the group outline is exported. One Feature per group; one Polyline with ≥3 vertices and <Closed>true</Closed>. Annotation Display=false. SortingCode omitted. Status: specified, producer TBD — the outline comes from clustering tree detections, a later pipeline step. Consumers may implement against this profile now; documents will not contain Tree Group features until that detector ships.

7.4 Bush

As §7.2.

7.5 Tree

One Point. Direction REQUIRED (road-axis tangent, R-5.5.5). Annotation Display=true, exactly one Text (N-5.7.3). Legible SHOULD NOT be emitted — the label is computed, not read (R-4.23.2). Shapes REQUIRED: exactly one role="trunk" type="cylinder" and exactly one role="crown" type="cylinder"|"cone" (R-5.8.7). Trunk and crown diameters travel as Shape/Diameter; the numeric attributes trunk_diameter_m / crown_diameter_m are not emitted (decision Q2). Attributes MAY carry a future species_class.

7.6 Fence, 7.7 Paving Edge

One Polyline, ≥2 vertices, Annotation Display=false, no SortingCode, no Polyline/Type.

7.8 noise_wall

Decision Q7: the existing lower-case Type string noise_wall is kept (not renamed to Noise Wall), and the geometry stays Polylines — the detector emits polylines; the poster's spline form is not followed. No Annotation is emitted; the object-name label is deferred to post-processing (§10 O-17). Attributes MAY carry height_m, length_m.

7.9 Trench / 7.10 Trench Bottom

Two separate Features per trench couple, tied by the pair index <i>: top = Trench with G<i>$A, bottom = Trench Bottom with G<i>$B. Polyline/Type SHOULD be top / bottom respectively (human readability; the code is the contract). Annotation Display=false. The hatch between the outlines is derived by the consumer and MUST NOT be exported.

7.11 Slope

One Feature containing two Polylines: SortingCode B<i>$A with Type top, and B<i>$B with Type bottom. Annotation Display=false. Decision Q6: A/B plus the two outlines suffice to derive the hatch direction; no explicit downhill vector.

7.12 Pedestrian Road

One Feature per path, using either Polylines or Splines. The same path MUST NOT be emitted in both forms. Annotation Display=false. - R-7.12.1 The consumer selects the CAD layer from the container used (Polylines → pPLC_Gehweg, Splines → sPLC_Gehweg); see Appendix C.

7.13 Terrain Point

One Point per elevation point. Direction REQUIRED and always emitted although catalog mode NO ignores it (R-5.5.6). Annotation Display=true with no Text: the consumer renders the elevation label from Point/Z per N-5.7.2 (decision Q4 revised). Legible SHOULD NOT be emitted.

7.14 Traffic Sign

One Point. Direction REQUIRED = plate normal facing oncoming traffic (R-5.5.5). Annotation Display=false, no Text — plate text is not transcribed today. If plate transcription ships, this class moves to the §7.18 pattern (Display=true + Legible) per R-4.23.1. Shapes OPTIONAL: a producer MAY emit a role="post" type="cylinder" shape for the sign post. Attributes MAY carry height_m, plate_class, direction_source.

7.15 Shaft, 7.16 Emergency Call Box, 7.17 Gully

One Point each. Direction REQUIRED (road-axis tangent). Annotation Display=false, no Text. Gully Attributes MAY carry width_m. - N-7.15.1 The poster's leftover Text km placeholder in column 16 is a copy-paste artefact and is not reproduced.

7.18 KM Sign

One Point. Direction REQUIRED = plate normal facing oncoming traffic. Annotation: Display=true; Legible REQUIRED with one of full | partial | none (§4.23) — sign text is often only partly recoverable from the point cloud; Text 0..3 lines per R-5.7.4, marked per R-4.24.5 under partial. Under none the Text elements are omitted and Display stays true, so the symbol is still placed. Attributes SHOULD carry the machine values km (float), section (string/integer), station (float) when known, so the consumer can re-format without a re-export (§10 O-19).

7.19 Wall

One Polyline, ≥2 vertices, Annotation Display=false, Attributes MAY carry height_m, length_m.

7.20 guardrail — annotation on existing geometry

No new geometry (poster col 18: "part of original XML"). The existing guardrail polyline gains: Attributes with guardrail_type (machine value, e.g. EDSP, ESP 2.0) plus the migrated legacy keys of N-8.6.3; and Annotation with Display=true and one Text = the drawn label (EDSP, ESP 2,0). Decision Q8: the label source is our guardrail_type attribute; the legacy FeatureClass=Guard Rails_<type> convention is a consumer-side fallback for 1.0 files only (N-2.5.4). LaneID stays "0"; RoadPoint is kept as today.

7.21 Lane markings — FROZEN

Axis of the Edge and Center Lines: solid segments as Splines, dashed as Lines, exactly as today, including per-segment Type and Width. Decision Q12: no NEW element of any kind. Output byte-identical to 0.9.0 except MetaData/SchemaVersion (R-2.4.1).

7.22 Road axes — FROZEN

Central Axis, Both-Sides Central Axis, Single-Side Central Axis as Polylines, exactly as today. Polyline/RoadPoint remains present for these features. No NEW element.

7.23 Cross Section — FROZEN

Decision Q4 (revised): cross-section features are fine as they are. Type stays Cross Section; the 1.0 semantics of PointerNumber (cross-section plane index), RoadPoint (distance along road), Color, FeatureClass, FeatureID are unchanged. No Direction, no Annotation, no Attributes. The consumer renders the elevation label from Point/Z per N-5.7.2 and picks the layer from Type via Appendix C.

7.24 guardrail_support, guardrail_top_rail

Unchanged geometry, no Annotation. Their stand-in attribute keys (parent_guardrail_id, post_spacing_m, post_count, post_confidence, halfwidth_m, lateral_offset_m) MUST be emitted through the uniform <Attribute name= type=> form of §4.28 — this is what makes them survive the Nexus exporter.

7.25 Verge Post

Excel-only class (Randpfosten), not on the poster. Standard point-symbol profile: Direction REQUIRED, Annotation Display=false, Attributes height_m, width_m; MAY carry a role="post" type="cylinder" Shape. Class name and layer are provisional (§10 O-16).

8. Producer contract (create_xml(data))

8.1 Top level

data = {
  "metadata": {"creation_date": str,       # REQUIRED
               "source": str,              # REQUIRED
               "software_version": str,    # REQUIRED
               "pipeline_versions": [...], # OPTIONAL, 1.0 shape unchanged
               "schema_version": str},     # OPTIONAL, must be "1.1"
  "geoshift": {"x": float, "y": float, "z": float},   # OPTIONAL
  "features": [ feature, ... ],            # REQUIRED (MAY be empty)
}

pipeline_versions entry: {"step": str, "date": str?, "packages": {name: version}} or {"step": str, "segment_ranges": [{"segments": [[a, b], ...], "date": str, "packages": {...}}]} (§4.4).

8.2 feature

There is no layer key (R-2.2.4). A layer key, if supplied, is ignored (R-6.4.2).

8.3 point

8.4 polyline

8.5 spline, line, width

spline: id (req), control_points (req; ≥2 for 1.1 profiles), fit_points (req in 1.0, default [] for 1.1 producers), type, road_point, width, annotation, attributes. line: 1.0 keys unchanged — id, start_point, end_point, road_point (all required), type (optional, open string), width (optional) — plus OPTIONAL annotation, attributes. lane_id on a spline or line: as R-4.11.1 — required for legacy dicts, defaulted from the feature for 1.1-touched geometry.

width dict → <Width>; each child is emitted only when its source value is not None:

Other keys carried in the same dict (center, blur_left, blur_right, n_points) are ignored (R-8.10.1).

8.6 Attributes are explicit only

• R-8.6.1 The writer MUST build <Attributes> only from an explicit attributes mapping on the feature, point, polyline, spline, or line dict. No other dict key contributes an <Attribute>.
• R-8.6.2 There is no legacy-key adapter. Top-level keys that §8 does not list are ignored silently (R-6.4.2), including the guardrails stand-in's polyline keys. Deriving attributes from them would add an <Attributes> element to output that 0.9.0 produced without one, breaking R-2.4.1.
• N-8.6.3 (informative — guardrails migration) The guardrails producer adopts 1.1 by moving these polyline keys into attributes={...}: side, guardrail_type, faces, length_m, feature_type, width_m, top_height_p90_m, parent_guardrail_id, post_spacing_m, post_count, post_confidence, halfwidth_m — plus any further key it wants to carry (e.g. lateral_offset_m). Until it does, those values simply do not reach the document, exactly as under 0.9.0.
• N-8.6.4 (informative — stand-in tag names) The stand-in exporter derives its tag name as key.replace("_", "").title(), which yields <Guardrailtype>, <Topheightp90m>, and <Postspacingm name="post_spacing_m">. Those tags are not lossy — the canonical key rides in @name for the longer fields — but they are non-uniform, forcing a per-key reader mapping. The uniform <Attribute name= type=> form of §4.28 replaces them; this writer never emits them.

8.7 shape dict

{"role": str, "type": "cylinder"|"cone",
 "base": [x, y, z],
 "top":  [x, y, z],   # cylinder only
 "apex": [x, y, z],   # cone only
 "diameter": float}

• R-8.7.1 Exactly one of top / apex MUST be supplied, matching type (R-4.20.3).
• R-8.7.2 Order within shapes is preserved.

8.8 annotation dict

{"display": bool, "legible": "full" | "partial" | "none" | None, "text": str | list[str] | None}. - R-8.8.1 A str text yields one Text; a list[str] yields one Text per element in order; None or [] yields none. - R-8.8.2 legible is a str from the enumeration of R-5.10.1; absent or None ⇒ Legible not emitted. A bool is not accepted (R-6.2.16). - R-8.8.3 attributes is Mapping[str, str | int | float | bool | None]. - N-8.8.4 (informative — numpy scalars) Wherever §8 declares an int, a float or a bool, the numpy scalar equivalents (bool_, integer, floating) are accepted and mapped to boolean/integer/float — boolean first, so np.bool_ never becomes an integer (R-5.9.1) — and are serialised exactly as the equivalent Python scalar would be (R-5.1.1, R-5.2.1).

8.9 Producer responsibilities (not the writer's)

• R-8.9.1 Coordinates in the geoshifted local frame, metres.
• R-8.9.2 Unit direction vectors.
• R-8.9.3 All display formatting of Annotation/Text (decimal comma, Ø=, line split).
• R-8.9.4 Globally unique, non-empty ids.
• R-8.9.5 Sorting-code pair completeness across the features it contributes.
• R-8.9.6 §7 profile compliance, including R-7.0.2 (no 1.1 key on a frozen profile).

8.10 What the writer ignores

• R-8.10.1 Any dict key not listed in §8 is ignored silently (e.g. the width dict's center, blur_left, blur_right, n_points; a stray layer).
• R-8.10.2 The writer MUST NOT infer any value from Feature/Type (R-6.4.1).
• R-8.10.3 The writer MUST NOT derive Annotation/Text from Shapes, Z, or guardrail_type (R-6.4.3).

9. Complete examples

All examples conform to §§3–8. Whitespace is prettify_xml's (two-space indent).

9.1 Point symbols — Tree with Shapes, KM Sign with Legible

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>hbw_detectors</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Geoshift>
    <X>2600000.0</X>
    <Y>1200000.0</Y>
    <Z>400.0</Z>
  </Geoshift>
  <Features>
    <Feature>
      <Type>Tree</Type>
      <ID>TREE-12</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points>
        <Point>
          <ID>TREE-12-1</ID>
          <LaneID>0</LaneID>
          <PointerNumber>1</PointerNumber>
          <X>-109.06</X>
          <Y>-383.29</Y>
          <Z>0.02</Z>
          <Color/>
          <FeatureClass>Tree</FeatureClass>
          <FeatureID>TREE-12</FeatureID>
          <Direction>
            <X>0.974467</X>
            <Y>-0.224529</Y>
            <Z>0.0</Z>
          </Direction>
          <Shapes>
            <Shape role="trunk" type="cylinder">
              <Base>
                <X>-109.06</X>
                <Y>-383.29</Y>
                <Z>0.02</Z>
              </Base>
              <Top>
                <X>-109.04</X>
                <Y>-383.27</Y>
                <Z>2.52</Z>
              </Top>
              <Diameter>0.3</Diameter>
            </Shape>
            <Shape role="crown" type="cone">
              <Base>
                <X>-109.04</X>
                <Y>-383.27</Y>
                <Z>2.52</Z>
              </Base>
              <Apex>
                <X>-109.01</X>
                <Y>-383.22</Y>
                <Z>8.52</Z>
              </Apex>
              <Diameter>7.0</Diameter>
            </Shape>
          </Shapes>
          <Annotation>
            <Display>true</Display>
            <Text>Ø= 0,30/7,0m</Text>
          </Annotation>
        </Point>
      </Points>
      <NumberOfPoints>1</NumberOfPoints>
      <Polylines/>
      <NumberOfPolylines>0</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
    <Feature>
      <Type>KM Sign</Type>
      <ID>KMS-3</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points>
        <Point>
          <ID>KMS-3-1</ID>
          <LaneID>0</LaneID>
          <PointerNumber>1</PointerNumber>
          <X>-88.31</X>
          <Y>-401.77</Y>
          <Z>1.92</Z>
          <Color/>
          <FeatureClass>KM Sign</FeatureClass>
          <FeatureID>KMS-3</FeatureID>
          <Direction>
            <X>-0.221946</X>
            <Y>-0.963767</Y>
            <Z>0.147964</Z>
          </Direction>
          <Annotation>
            <Display>true</Display>
            <Legible>partial</Legible>
            <Text>KM 46.5</Text>
            <Text>Abs. ??</Text>
          </Annotation>
          <Attributes>
            <Attribute name="direction_source" type="string">measured</Attribute>
          </Attributes>
        </Point>
      </Points>
      <NumberOfPoints>1</NumberOfPoints>
      <Polylines/>
      <NumberOfPolylines>0</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

Notes: the KM Sign direction is a tilted plate normal (Z != 0, R-5.5.1). Legible=partial — the kilometre line was read in full, two characters of the section line were not and are marked ?? (R-4.24.5), and the station line was entirely unreadable and is therefore omitted (R-4.23.1, §7.18).

The same sign with nothing readable at all carries no Text, and Display stays true so the symbol is still placed (R-4.23.3):

<Annotation>
  <Display>true</Display>
  <Legible>none</Legible>
</Annotation>

9.2 Paired polylines — trench top + bottom (G4$A / G4$B)

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>hbw_detectors</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Features>
    <Feature>
      <Type>Trench</Type>
      <ID>TRN-4-TOP</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points/>
      <NumberOfPoints>0</NumberOfPoints>
      <Polylines>
        <Polyline>
          <ID>TRN-4-TOP-1</ID>
          <LaneID>0</LaneID>
          <Type>top</Type>
          <Vertices>
            <Vertex>
              <ID>TRN-4-TOP-1-1</ID>
              <X>10.0</X>
              <Y>0.0</Y>
              <Z>1.2</Z>
            </Vertex>
            <Vertex>
              <ID>TRN-4-TOP-1-2</ID>
              <X>18.0</X>
              <Y>0.4</Y>
              <Z>1.25</Z>
            </Vertex>
          </Vertices>
          <SortingCode>G4$A</SortingCode>
          <Annotation>
            <Display>false</Display>
          </Annotation>
        </Polyline>
      </Polylines>
      <NumberOfPolylines>1</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
    <Feature>
      <Type>Trench Bottom</Type>
      <ID>TRN-4-BOT</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points/>
      <NumberOfPoints>0</NumberOfPoints>
      <Polylines>
        <Polyline>
          <ID>TRN-4-BOT-1</ID>
          <LaneID>0</LaneID>
          <Type>bottom</Type>
          <Vertices>
            <Vertex>
              <ID>TRN-4-BOT-1-1</ID>
              <X>10.2</X>
              <Y>-1.1</Y>
              <Z>0.35</Z>
            </Vertex>
            <Vertex>
              <ID>TRN-4-BOT-1-2</ID>
              <X>18.1</X>
              <Y>-0.7</Y>
              <Z>0.4</Z>
            </Vertex>
          </Vertices>
          <SortingCode>G4$B</SortingCode>
          <Annotation>
            <Display>false</Display>
          </Annotation>
        </Polyline>
      </Polylines>
      <NumberOfPolylines>1</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

9.3 Spline — Tree Line

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>hbw_detectors</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Features>
    <Feature>
      <Type>Tree Line</Type>
      <ID>TRL-2</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points/>
      <NumberOfPoints>0</NumberOfPoints>
      <Polylines/>
      <NumberOfPolylines>0</NumberOfPolylines>
      <Splines>
        <Spline>
          <ID>TRL-2-1</ID>
          <LaneID>0</LaneID>
          <Fit_Points/>
          <Control_Points>
            <Point>
              <ID>TRL-2-1_1</ID>
              <X>-20.0</X>
              <Y>7.5</Y>
              <Z>0.9</Z>
            </Point>
            <Point>
              <ID>TRL-2-1_2</ID>
              <X>-8.0</X>
              <Y>8.1</Y>
              <Z>0.95</Z>
            </Point>
            <Point>
              <ID>TRL-2-1_3</ID>
              <X>4.0</X>
              <Y>8.4</Y>
              <Z>1.0</Z>
            </Point>
          </Control_Points>
          <Annotation>
            <Display>false</Display>
          </Annotation>
        </Spline>
      </Splines>
      <NumberOfSplines>1</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

9.4 Closed polyline — Tree Group (profile specified, producer TBD)

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>hbw_detectors</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Features>
    <Feature>
      <Type>Tree Group</Type>
      <ID>TGR-1</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points/>
      <NumberOfPoints>0</NumberOfPoints>
      <Polylines>
        <Polyline>
          <ID>TGR-1-1</ID>
          <LaneID>0</LaneID>
          <Vertices>
            <Vertex>
              <ID>TGR-1-1-1</ID>
              <X>30.0</X>
              <Y>12.0</Y>
              <Z>1.1</Z>
            </Vertex>
            <Vertex>
              <ID>TGR-1-1-2</ID>
              <X>44.0</X>
              <Y>14.5</Y>
              <Z>1.2</Z>
            </Vertex>
            <Vertex>
              <ID>TGR-1-1-3</ID>
              <X>41.0</X>
              <Y>25.0</Y>
              <Z>1.15</Z>
            </Vertex>
            <Vertex>
              <ID>TGR-1-1-4</ID>
              <X>28.5</X>
              <Y>22.0</Y>
              <Z>1.05</Z>
            </Vertex>
          </Vertices>
          <Closed>true</Closed>
          <Annotation>
            <Display>false</Display>
          </Annotation>
        </Polyline>
      </Polylines>
      <NumberOfPolylines>1</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

9.5 Guard-rail annotation on an existing guardrail polyline

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>guardrails</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Features>
    <Feature>
      <Type>guardrail</Type>
      <ID>GR-7</ID>
      <LaneID>0</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points/>
      <NumberOfPoints>0</NumberOfPoints>
      <Polylines>
        <Polyline>
          <ID>GR-7-1</ID>
          <LaneID>0</LaneID>
          <RoadPoint>
            <From>120.0</From>
            <To>184.5</To>
          </RoadPoint>
          <Vertices>
            <Vertex>
              <ID>GR-7-1-1</ID>
              <X>0.0</X>
              <Y>-6.2</Y>
              <Z>0.75</Z>
            </Vertex>
            <Vertex>
              <ID>GR-7-1-2</ID>
              <X>64.5</X>
              <Y>-6.4</Y>
              <Z>0.78</Z>
            </Vertex>
          </Vertices>
          <Annotation>
            <Display>true</Display>
            <Text>ESP 2,0</Text>
          </Annotation>
          <Attributes>
            <Attribute name="faces" type="string">right</Attribute>
            <Attribute name="guardrail_type" type="string">ESP 2.0</Attribute>
            <Attribute name="length_m" type="float">64.5</Attribute>
            <Attribute name="side" type="string">right</Attribute>
            <Attribute name="top_height_p90_m" type="float">0.78</Attribute>
          </Attributes>
        </Polyline>
      </Polylines>
      <NumberOfPolylines>1</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

Attribute children are sorted by @name (R-4.28.1).

9.6 Legacy cross-section feature under 1.1 — frozen profile §7.23

Produced by an unmodified legacy producer. The tree is exactly the 1.0 shape; the only difference from 0.9.0 output is the SchemaVersion line (R-2.4.1).

<?xml version="1.0" encoding="UTF-8"?>
<HighwayData>
  <MetaData>
    <CreationDate>2026-08-28T09:12:00</CreationDate>
    <Source>cluster_stepper</Source>
    <SoftwareVersion>0.10.0</SoftwareVersion>
    <SchemaVersion>1.1</SchemaVersion>
  </MetaData>
  <Features>
    <Feature>
      <Type>Cross Section</Type>
      <ID>CS-left</ID>
      <LaneID>1</LaneID>
      <Lines/>
      <NumberOfLines>0</NumberOfLines>
      <Points>
        <Point>
          <ID>CS-left-1</ID>
          <LaneID>1</LaneID>
          <PointerNumber>0</PointerNumber>
          <X>-3.51</X>
          <Y>0.0</Y>
          <Z>0.12</Z>
          <Color>None</Color>
          <FeatureClass>None</FeatureClass>
          <FeatureID>None</FeatureID>
          <RoadPoint>0.0</RoadPoint>
        </Point>
        <Point>
          <ID>CS-left-2</ID>
          <LaneID>1</LaneID>
          <PointerNumber>1</PointerNumber>
          <X>-3.49</X>
          <Y>1.0</Y>
          <Z>0.13</Z>
          <Color>None</Color>
          <FeatureClass>None</FeatureClass>
          <FeatureID>None</FeatureID>
          <RoadPoint>1.0</RoadPoint>
        </Point>
      </Points>
      <NumberOfPoints>2</NumberOfPoints>
      <Polylines/>
      <NumberOfPolylines>0</NumberOfPolylines>
      <Splines/>
      <NumberOfSplines>0</NumberOfSplines>
    </Feature>
  </Features>
</HighwayData>

The literal None texts are the 1.0 str() coercion of present-but-None keys (R-4.17.2); PointerNumber is the cross-section plane index, not a 1-based counter (frozen semantics, §7.23). The consumer renders each point's elevation label from Z (N-5.7.2) and resolves the layer from Type (Appendix C).

10. Open items

10.1 Still open

Each item states the spec's default behaviour (already normative above) and the decider. None blocks implementation.

10.2 Closed items (IDs are never reused)

Revision 1 of this spec numbered its open items O-1…O-12. Those IDs are retired: five were resolved in round 2, and the seven that stayed open were re-issued as O-13…O-21 in §10.1 rather than renumbered in place. O-13 has since been closed by the Legible enumeration decision, leaving O-14…O-21 open.

O-20 (confirm consumer-side elevation rendering) and O-21 (confirm the Appendix C layer table) are new in revision 2 and have no revision-1 predecessor.

Appendix A — 1.0 → 1.1 change list

A.1 New elements

No Feature/Layer (R-2.2.4).

A.2 Relaxations (1.1 producers only; legacy output unchanged)

• Point/RoadPoint, Polyline/RoadPoint, Spline/RoadPoint become 0..1.
• Spline/Fit_Points MAY be empty; the container is still always emitted.
• Point/PointerNumber, Color, FeatureClass, FeatureID gain writer defaults for absent keys (R-4.17.1); a key present with value None keeps its 1.0 str() behaviour (R-4.17.2). All four are still always emitted.

A.3 Removed / rejected

• The stand-in exporter's derived tags (<Guardrailtype>, <Postspacingm name="post_spacing_m">) are not part of 1.1 (N-8.6.4). They are not lossy — the canonical key rides in @name for the longer fields — but they are non-uniform, requiring a per-key reader mapping; <Attribute name= type=> replaces them.
• The guardrails legacy-key adapter proposed in earlier drafts is removed: emitting <Attributes> from top-level polyline keys would break R-2.4.1 byte-identity. Attributes come only from attributes (R-8.6.1); the producer migrates per N-8.6.3.
• ExportNote (stand-in only) is not part of any schema version.
• Feature/Layer, present in earlier drafts of this spec, is removed (R-2.2.4).

A.4 Where the decisions override the plan

A.5 Where round 2 overrides round 1

A.6 Later owner decisions (after round 2)

Appendix B — poster → XML field mapping

B.1 Point classes (poster cols 3, 10, 11, 12, 13, 14, 15, 16; + verge post)

B.2 Polyline classes (poster cols 4, 5, 7, 8, 9, 17; + tree group)

B.3 Spline classes (poster cols 1a, 2, 6, 9)

B.4 Annotation-only / special (poster cols 7, 8 hatches; col 18 guard rails; col 1b group symbol)

Appendix C — Feature/Type → CAD layer name (INFORMATIVE)

This table is not normative and not part of the document. The layer name is a drawing artefact; it is constant per feature class and cannot be derived from point-cloud data, so it lives on the consumer side. The table lets HBW build its Type → layer → Data-catalog lookup independently. Values come from the poster and the Excel catalog; confirm before release (§10 O-21).

• N-C.1 Pedestrian Road is the only class whose layer depends on the container as well as the Type.
• N-C.2 Hatches (Schraffur_Böschung and the trench hatch) have no Feature/Type; the consumer derives them from the SortingCode A/B pairs.