@lanexio/parser-grammar-xml

This page documents @lanexio/parser-grammar-xml, the XML grammar package implementing XML 1.0 5th Edition with optional DTD validation, external entity resolution, and comprehensive attribute-level DTD information.

• Version: Stable
• Module name: parser-grammar-xml
• Package: @lanexio/parser-grammar-xml
• Import path: @lanexio/parser-grammar-xml
• Layer: 2 (Grammar)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Parse XML documents into a flat AST with optional DTD validation.

Scope and encodings

This grammar implements XML 1.0 5th Edition (ADR 0041 / ADR 0046). XML 1.1 stays out of scope: documents that require XML 1.1-only features are not supported, so conformance claims refer to XML 1.0 5th Edition on the supported subset.

Input is UTF-8 bytes by default. A UTF-16 or UTF-32 byte order mark is autodetected and transcoded losslessly so node ranges stay in the original byte space; a declared encoding that contradicts the BOM is flagged as an error node per XML 1.0 5th Ed. section 4.3.3.

Layer contract

Layer 2 dependency rules

This package depends only on Layer 1 core packages. It does not import from query, bridge, devtools, or entry packages. Grammar packs never depend on other grammar packs.

When to use this module

• You need to parse XML 1.0 documents into a traversable AST.
• You need optional DTD validation (content models, required attributes, ID/IDREF consistency).
• You need to resolve external DTD subsets via a callback.
• You need access to parsed DTD declarations (element, attribute-list, entity).

Module boundary

Boundary	Description
Inputs	Uint8Array (source bytes) + optional ParseXmlOptions
Outputs	LexTree (flat AST)
Side effects	None (the parser does no I/O; external DTD resolved via callback)
Determinism	Yes
External dependencies	@lanexio/parser-core
Never-throw guarantee	Yes
Security surface	None (parse only, no output generation; no entity expansion)

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-grammar-xml

   npm

   npm install @lanexio/parser-grammar-xml

   yarn

   yarn add @lanexio/parser-grammar-xml

2. Import the named export.

   import { parseXml } from '@lanexio/parser-grammar-xml';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

import { parseXml } from '@lanexio/parser-grammar-xml';

const encoder = new TextEncoder();
const bytes = encoder.encode('<root><item id="1">value</item></root>');

const tree = parseXml(bytes);

console.log(tree.nodeCount);

DTD validation

import { parseXml } from '@lanexio/parser-grammar-xml';

const encoder = new TextEncoder();
const tree = parseXml(
  encoder.encode('<!DOCTYPE root [ <!ELEMENT root (#PCDATA)> ]><root>text</root>'),
  { validate: true }
);

Strict profile

import { parseXml } from '@lanexio/parser-grammar-xml';

const encoder = new TextEncoder();
const tree = parseXml(encoder.encode('<a xmlns:p="urn:x"><p:b/></a>'), {
  mode: 'strict',
});

mode: "strict" (or the strict: true alias, ADR 0044) is the strict conformance profile whose contract is “WF + reject external-DTD / undefined-entity”. On top of the always-on well-formedness checks it runs:

• namespace-prefix well-formedness unconditionally: an unbound element or attribute prefix flags the node even in documents with no namespace declarations;
• internal-subset DTD validation when the document carries an internal DTD subset (VC: Root Element Type, element content models, attribute constraints);
• the external-DTD surface: a DOCTYPE that references an external subset (SYSTEM or PUBLIC) which no resolver read flags the DocType node as an error node and the Document root. A resolver that read the subset keeps the reference clean.

The parse profiles compose validate and strict:

Profile	What runs
default (lenient)	WF-only recovery; an unresolved external-DTD document parses clean
validate: true	full DTD validating pass
mode: "strict" / strict: true	namespace-prefix WF + internal-subset DTD validation + external-DTD surface
validate: true + strict	full DTD validating pass on top of the strict surface

Both validate and strict forward through the registered xmlGrammar.parse options bag and the pack parse entry point, so parse(bytes, { grammarOptions: { validate: true, mode: "strict" } }) behaves identically to the direct parseXml(bytes, { validate: true, mode: "strict" }) call.

Strict mode never throws; every input, including the large and non-UTF-8 fixtures in test_files/xml, produces a tree with metadata.language === "xml" (verified by the strict-mode corpus never-throw sweep).

The default mode: "lenient" stays well-formedness-strict and byte-lossless but does not run the strict profile; files that error only in strict mode are strict-profile rejections (unbound prefixes, internal-subset DTD violations, unresolved external-DTD references), not well-formedness defects. See the XML conformance page for the artifact reclassification table (xml-1.1, not-wf, errors/fail, non-UTF-8 encodings, c14n, errata, and the remaining documented buckets) that keeps the REAL-DEFECT bucket empty.

Exports

Export	Type	Description
parseXml	(bytes: Uint8Array, options?: ParseXmlOptions) => LexTree	Parse XML. Never throws.
XmlKind	const object	Numeric kind IDs for all XML node types.
XmlField	const object	Numeric field IDs for XML element slots.
XML_FIELD_NAMES_BY_ID	readonly string[]	Field name lookup by numeric field ID.
XML_KIND_NAMES_BY_ID	readonly Record<number, string>	Kind-name lookup by numeric ID.
xmlGrammar	LanexioParserPureGrammar	Grammar descriptor for use with parser-pure.
xmlRegistration	GrammarRegistration	Registration for the unified grammar registry.
xmlReuseOracle	ReuseOracle	Incremental reuse oracle.

Options

ParseXmlOptions

Field	Type	Required	Default	Description
mode	"lenient" | "strict"	No	"lenient"	"strict" runs the strict conformance profile (ADR 0044): namespace-prefix well-formedness unconditionally, internal-subset DTD validation, and the external-DTD surface (an unresolved external subset flags the DocType). Never throws.
validate	boolean	No	false	When true, runs the full DTD validating pass after parsing (VC Root Element Type, element content models, attribute constraints). Forwarded through xmlGrammar.parse and the pack parse entry point.
resolveExternal	ExternalResolver	No	undefined	Callback for resolving external DTD subset references. The parser does no I/O.
baseUri	string	No	""	Base URI for resolving relative SYSTEM identifiers.
namespaceCheck	boolean	No	true	When false, skip namespace prefix resolution and xmlns declaration tracking.
language	string	No	"xml"	Language stamp written to tree.metadata.language on every parse result. Future sub-dialects (such as the registered xhtml/svg aliases) may pass their own.

Return shape

Property	Type	Description
root	LexNode	Root node of the XML document.
nodeCount	number	Total nodes in the tree.
source	Uint8Array	Original parsed bytes.
metadata.language	string	Language stamp on every parse result — "xml" by default, or the language option value. An empty document parses to a Document node containing a single XmlKind.Error leaf (root.hasError is true).

Exported types

Type	Purpose	Notes
ParseXmlOptions	Options for parseXml	See options table above.
ExternalResolver	Callback for resolving external DTD subsets	(publicId, systemId, baseUri) => Uint8Array | null
DtdInfo	Parsed DTD declarations	Elements, attlists, entities
DtdElementDecl	DTD element declaration	Name and content model
DtdAttlistDecl	DTD attribute-list declaration	Element name and attr defs
DtdAttrDef	Single attribute definition in ATTLIST	Name, type, default
DtdEntityDecl	DTD entity declaration	Name and value
XmlKindType	Union of all XmlKind values	Type-safe kind reference
XmlFieldType	Union of all XmlField values	Type-safe field reference

Configuration and Extension

DTD resolution

The resolveExternal callback allows callers to provide external DTD content without the parser performing network I/O. The parser’s no-expand security model prevents billion-laughs attacks.

Accessibility

Accessibility requirements

• No direct accessibility surface. The XML parser produces flat AST data structures.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (data format)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• parseXml never throws on any byte sequence.
• The parser uses a no-expand security model for entities (billion-laughs guarantee).

Threat	Mitigation	Status
Malformed input byte sequence	Panic-free guarantee: all inputs accepted, errors produce LexError AST nodes	Implemented
Billion-laughs (entity expansion)	No entity expansion: entities are tracked but not substituted in parsed output	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser	Consumes	6	Unified entry point

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-08-28	Current	Never-throw on large spans in both profiles: chunked decodeRange replaces the unbounded spread-decode sites. Strict-mode corpus sweep (6112 files) never throws.
1.0.0	2026-05-29	Prior	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.