This tool helps you work with XML in JavaScript and TypeScript projects. It can understand XML even if it has errors, and it gives features like auto complete, hover info, formatting, renaming tags, finding definitions, and validating with XSD. You can use it in editors, language servers, CLI tools, web apps, or tests.. without needing Java or installing native software.

Links

| Resource | URL | | --- | --- | | npm package | https://www.npmjs.com/package/xml-language-service | | Documentation | https://harshanacz.github.io/xml-language-service/ | | Repository | https://github.com/harshanacz/xml-language-service | | Issues | https://github.com/harshanacz/xml-language-service/issues | | Project using this | https://github.com/harshanacz/xml-review-bot-demo |

Install

npm install xml-language-service

Requirements:

• Node.js 18 or newer
• ESM-compatible project setup

The npm package includes the Xerces WASM assets, so consumers do not need to install Java, Xerces, Emscripten, or a native compiler.

Quick Start

import { getLanguageService } from "xml-language-service";

const service = getLanguageService();

const xml = `<catalog>
  <book id="bk101">
    <title>XML Developer Guide</title>
  </book>
</catalog>`;

const document = service.parseXMLDocument("file:///catalog.xml", xml);

const completions = service.doComplete(document, { line: 1, character: 4 });
const hover = service.doHover(document, { line: 2, character: 6 });
const symbols = service.findDocumentSymbols(document);
const foldingRanges = service.getFoldingRanges(document);

console.log(completions.items);
console.log(hover);
console.log(symbols);
console.log(foldingRanges);

service.dispose();

What You Get

| Feature | Description | | --- | --- | | Fault-tolerant parser | Builds a usable partial tree even when the XML is incomplete or malformed. | | Completion | Suggests element names, attributes, and closing tags. Can become XSD-aware when a schema is registered. | | Hover | Returns contextual information for XML elements, comments, and schema-backed nodes. | | Document symbols | Produces a hierarchical outline for editor sidebars and navigation views. | | Folding | Finds multi-line XML regions that can be collapsed. | | Formatting | Returns text edits for consistent XML indentation and spacing. | | Rename | Renames matching opening and closing tags together. | | Definition | Jumps between matching opening and closing tags. | | References | Finds elements with the same tag name in the document. | | XSD validation | Reports syntax and schema diagnostics through Xerces-C++ WASM. | | AST/CST printer | Prints parser output as a tree or JSON for debugging and snapshot tests. |

Public API

The main entry point is getLanguageService().

import { getLanguageService } from "xml-language-service";

const service = getLanguageService();

Common service methods:

| Method | Purpose | | --- | --- | | parseXMLDocument(uri, text) | Parse XML text into an XMLDocument. | | doComplete(document, position, fileName?, documentPath?) | Get completion items. | | doHover(document, position, fileName?, documentPath?) | Get hover content. | | findDocumentSymbols(document) | Get a nested document symbol tree. | | getFoldingRanges(document) | Get folding ranges. | | format(document, options?) | Get formatting text edits. | | doRename(document, position, newName) | Rename an element tag pair. | | doDefinition(document, position) | Find the matching tag definition. | | findReferences(document, position) | Find same-name element references. | | registerSchema(schema) | Register an XSD schema or schema bundle. | | validate(schemaUri, document) | Validate a parsed document against a registered schema. | | addUserAssociation(association) | Associate schemas with file names, paths, or namespaces. | | printTreeAST(document) | Print the AST as a visual text tree (├──, └──). | | printAST(document, options?) | Print the parsed AST for debugging. | | printCST(document, options?) | Print the raw CST for debugging. | | dispose() | Release schema provider resources. |

The package also exports core types such as XMLDocument, XMLNode, XMLAttribute, Position, Range, Diagnostic, SchemaBundle, CompletionItem, HoverResult, DocumentSymbol, FoldingRange, and TextEdit.

XSD Validation

XSD validation is handled by Apache Xerces-C++ compiled to WebAssembly. Xerces uses a SAX streaming parser, so parsing and schema validation happen in the same pass.

raw XML text
    |
    v
Xerces SAX stream
    |
    +-- syntax diagnostics
    +-- XSD diagnostics

This matters because diagnostics can still be reported for the part of the document Xerces was able to read before a fatal syntax error.

Register A Single XSD

const service = getLanguageService();

await service.registerSchema({
  uri: "file:///schema.xsd",
  xsdText: xsdContent,
});

const document = service.parseXMLDocument("file:///catalog.xml", xmlText);
const diagnostics = await service.validate("file:///schema.xsd", document);

Register A Schema Bundle

Use a SchemaBundle when the root schema references other files with xs:include or xs:import. The imports keys should match the schemaLocation values used inside the XSD.

await service.registerSchema({
  uri: "file:///root.xsd",
  xsdText: rootXsdContent,
  imports: {
    "types.xsd": typesXsdContent,
    "common.xsd": commonXsdContent,
  },
});

Built-In Schemas

The service ships with built-in schemas for common XML files and can associate them automatically by filename or namespace.

| File | Schema | | --- | --- | | pom.xml | Maven 4.0.0 | | web.xml | Java Servlet 3.1 |

You can register additional associations with addUserAssociation().

Debugging AST And CST Output

Three functions let you inspect parser output, create snapshot tests, or understand the tree structure of any XML document.

import { getLanguageService } from "xml-language-service";

const service = getLanguageService();
const document = service.parseXMLDocument(
  "file:///catalog.xml",
  `<catalog><book id="bk101"/></catalog>`,
);

// Visual text tree — quick structural overview
console.log(service.printTreeAST(document));
// Document
// └── catalog
//     └── book

// Full AST — includes attributes, text and comment nodes
console.log(service.printAST(document));
console.log(service.printAST(document, { includePositions: true }));
console.log(service.printAST(document, { format: "json" }));

// Raw CST — every grammar rule and token produced by the parser
console.log(service.printCST(document));

printAST and printCST accept these options:

| Option | Type | Default | | --- | --- | --- | | format | "tree" \| "json" | "tree" | | indent | number | 2 | | includePositions | boolean | false | | includeTokens | boolean | true |

Manual Debug Script

A ready-made script at tests/utils/manual.mjs exercises all three printers against a sample XML document. Run it directly with Node — no test runner needed:

npm run build
node tests/utils/manual.mjs

Architecture

TextDocument
    |
    v
@xml-tools/parser
    |
    v
XMLDocument
    |
    +-- completion
    +-- hover
    +-- symbols
    +-- folding
    +-- formatting
    +-- rename
    +-- definition
    +-- references
    |
    v
SchemaProvider
    |
    v
Xerces-C++ WASM

Development

npm install
npm run build
npm run build:watch
npm run test:run
npm test

Useful scripts:

| Script | Description | | --- | --- | | npm run build | Compile TypeScript and copy schema/WASM assets into dist. | | npm run build:watch | Compile TypeScript in watch mode. | | npm run test:run | Run the Vitest suite once. | | npm test | Run Vitest in watch mode. |

License

MIT