Glossary

Relevant source files

• .claude/docs/context.md
• .claude/docs/dependencies.md
• .claude/docs/error-formatting.md
• .claude/docs/libxml2-parity.md
• .claude/docs/node-types.md
• .claude/docs/packages.md
• .claude/docs/xpath3-types.md

This page defines codebase-specific terms, abbreviations, and domain concepts used throughout the Helium XML toolkit. It serves as a technical reference for onboarding engineers to bridge the gap between XML specification terminology and the actual Go implementation.

---

Core System Concepts

DOM (Document Object Model)

The in-memory tree representation of an XML document. Helium's DOM tree is implemented with a hierarchy of structs and interfaces to support efficient traversal, mutation, and serialization while maintaining libxml2 parity.

• Implementation: The fundamental tree linkage uses the docnode struct, which holds links to parent, children, and sibling nodes, along with a node name and element type enum. docnode is embedded into the node struct, which adds content storage, attribute linked-list storage, and namespace management for element nodes.
• Node Types: There are 21 distinct node types identified by the ElementType enum including Element, Attribute, Text, CDATA, Entity, ProcessingInstruction, Comment, Document, DTD, Namespace wrappers, and others. Attributes are stored not as children but as a linked list accessible via an Element's properties field.
• Namespaces: Elements maintain three separate fields related to namespaces:
  • ns — the active namespace qualifying the element name.
  • nsDefs — all namespace declarations (xmlns:) attached to this element.
  • properties — linked list of attributes, some of which correspond to namespace declarations initially parsed before promotion to nsDefs.
    Namespace is NOT a tree node — it's a lightweight struct: {etype, href, prefix, context}. No parent/child/sibling links. For XPath queries, a NamespaceNodeWrapper adds docnode linkage around a Namespace for read-only querying.
• Text Nodes Consolidation: Adjacent text nodes are automatically merged (merged sibling content) to reduce fragmentation and mimic libxml2 behavior for whitespace handling and text nodes.
• ID Element Lookup: The Document maintains an O(1) map from ID values to elements for fast retrieval by id attribute, with a fallback to a linear tree walk if the map is empty.

DOM Hierarchy Overview

Sources: node-types.md5-110

---

SAX2 (Simple API for XML)

An event-driven callback interface delivering parse events such as StartElementNS, EndElementNS, Characters, CDataBlock, and DTD-related events asynchronously during XML streaming.

• Interface: Defined by the SAX2Handler interface in the sax package packages.md31
• TreeBuilder: The default SAX2Handler implementation constructs the DOM tree by converting SAX events to DOM nodes and linking them appropriately. The TreeBuilder listens to SAX callbacks and creates Document, Element, Text, Comment, and other nodes dynamically parser-internals.md68-72
• Usage: SAX2 handlers can be replaced by clients for customized streaming processing or for partial parsing workflows. The parser calls the SAX2Handler methods during parsing for event delivery.

Sources: dependencies.md24 packages.md31 parser-internals.md68-72 parser-internals.md147-152

---

Parser Context (parserCtx)

Internal state machine and data structure managing XML parsing, implementing the full XML parse pipeline with libxml2-compatible behaviors.

• Responsibilities:

  • Controls parsing phases such as prolog, doctype, element content, and epilogue via explicit states (psStart, psContent, psPrologue, etc.) parser-internals.md57-60
  • Manages input reading via a stack of cursors (ByteCursor/RuneCursor) to support entity expansion, external DTD inclusion, and encoding switching parser-internals.md54-56
  • Performs encoding detection for UTF-8, UTF-16 (LE, BE), UCS-4, EBCDIC, BOM-based detection strategies parser-internals.md93-107
  • Maintains namespace stacks and elements stacks for correct namespace scoping during recursive parsing parser-internals.md62-67
  • Implements security features such as the Entity Amplification Guard to limit expansion and prevent XML External Entity (XXE) attacks parser-internals.md80-85
  • Dispatches SAX2 events during parsing for callbacks or TreeBuilder construction parser-internals.md68-72
  • Supports recovery on errors to parse partially malformed documents parser-internals.md87-90

• Use: Created by NewParser() and drives the parse methods such as Parse and ParseReader parser-internals.md5-6

Parsing Pipeline Overview:

Sources: parser-internals.md11-100

---

Context Carrier Pattern

A design pattern to propagate package-specific state (namespaces, variables, options) using Go's context.Context with typed keys. This avoids global state and enables thread-safe context passing.

• Implementation:
  • Define unexported contextKey structs for type safety context.md35
  • Export helper functions of the form WithX(ctx, val) context.Context to attach immutable state context.md19
  • Export GetX(ctx) accessor functions to retrieve attached state safely context.md22
• Use Cases:
  • Used in XPath evaluation to carry namespaces, variables, custom functions, operation limits, and configured resolvers packages.md51-56 packages.md70-75
  • Used in parsing pipelines to attach error handlers or catalog resolvers.
• Strictness: Avoid storing mutable state for concurrency safety and never store context in struct fields context.md11-12 context.md45

Sources: packages.md51-56 packages.md70-75 context.md1-120

---

Technical Terms & Abbreviations

Term	Definition	Relevant Code & Files
C14N	Canonical XML: Algorithm to produce a normalized XML document byte sequence for digital signature verification. Supports 1.0, Exclusive 1.0, 1.1.	c14n package packages.md36-43
IDC	Identity Constraints: XSD rules such as xs:unique, xs:key, and xs:keyref for validating uniqueness and referential integrity.	xsd package validation logic error-formatting.md149
UPA	Unique Particle Attribution: An XSD rule requiring deterministic content model validation, ensuring no ambiguous element matches.	xsd compiler layers packages.md101
FLWOR	For-Let-Where-Order-Return expressions in XPath 3.1 providing looping and filtering constructs.	xpath3 package packages.md79
EBV	Effective Boolean Value: Evaluation logic converting XPath sequences to boolean per XPath semantics.	xpath3 sequence.go xpath3-types.md165-173
HOF	Higher-Order Function: Functions that accept or return other functions, supported in XPath 3.1 function items.	xpath3 function item xpath3-types.md74-79
XXE	XML External Entity: Potential security vulnerability due to entity inclusion; mitigated by parser option BlockXXE(true).	helium.Parser packages.md10
Atomization	Conversion of nodes or items to atomic values (such as strings, numbers) following XPath 3.1 specification.	xpath3 type system xpath3-types.md174-182

---

Architecture Diagrams

Parsing Pipeline: From XML Input to DOM Tree

Sources: packages.md9-31 node-types.md5-110 parser-internals.md23-47

---

XPath 3.1 Evaluation: From Query String to Result

Sources: xpath3-types.md1-180 packages.md65-81

---

Data Structures & Implementation Details

Node Linkage & Namespace Management

• docnode: Base struct for all node types providing essential parent, child, and sibling pointers for tree linkage. Holds name string, etype ElementType enum, and links such as firstChild, lastChild, parent, next, and prev node-types.md5-18
• node: Embeds docnode and adds text content storage ([]byte), linked list of attributes (properties *Attribute), active namespace pointer (ns *Namespace), and namespace declarations slice (nsDefs []*Namespace) node-types.md22-31
• Attributes: Stored as a doubly linked list via the properties pointer on an Element; each Attribute itself is a node with children representing the attribute value as text or entities node-types.md46-52
• Namespaces: Represented by the lightweight Namespace struct (no tree links), with prefix, href (URI), and context to avoid duplication node-types.md42 The XPath-specific NamespaceNodeWrapper adds read-only docnode linkage so XPath queries can treat namespaces as nodes node-types.md44

Sources: node-types.md5-52

XPath 3.1 Type System

• Item Interface: The root abstraction for all XPath runtime values, implemented by multiple types xpath3-types.md6-12
• NodeItem: Wraps helium Node for XPath operations; carries schema-aware TypeAnnotation and fallback AtomizedType for typed nodes xpath3-types.md29-35
• AtomicValue: Represents XSD atomic types such as xs:string (Go string), xs:integer (*big.Int), xs:decimal (*big.Rat), xs:boolean (bool), xs:dateTime (time.Time), among others xpath3-types.md40-70
• FunctionItem: Callable function objects, supporting anonymous functions, named functions with arity, and partial applications for higher-order function support xpath3-types.md74-79
• MapItem and ArrayItem: Immutable data structures for XPath maps and arrays, implemented with copy-on-write and stable iteration order guarantees. Maps use normalized keys and safe cloning of stored sequences xpath3-types.md84-129
• Sequence: Simply a slice of Item. XPath expressions evaluate to sequences of nodes or atomic values xpath3-types.md24

Sources: xpath3-types.md1-149

Error Handling & Formatting

• ErrParseError: Wraps parsing errors with location (line, column), domain, severity level, and the source context line. Formats errors to match libxml2 style for golden test compatibility error-formatting.md17-32
• ErrorHandler Interface: Receives asynchronous error notifications during parsing, validation, or runtime errors. Implementations include collectors and no-op handlers error-formatting.md40-55
• XSLT Errors: Represented by XSLTError struct including W3C error codes (e.g. XTSE* for static, XTDE* for dynamic errors) and optionally a cause and embedded value for xsl:catch processing error-formatting.md104-121

Sources: error-formatting.md7-121

---

This glossary should assist engineers in understanding core abstractions, key packages, and concepts in the helium project. It also provides direct references to files and line ranges for in-depth study of each topic.