# Glossary

> Domain terms, engine-specific concepts, and abbreviations used across xml-xsd-engine.

---

## A

**Abstract type** — A complex type declared with `abstract="true"` that cannot be used directly to validate element content. Must be substituted via a substitution group.

**Ancestor axis** — XPath axis selecting all ancestor elements of the context node.

**Attribute Value Template (AVT)** — XSLT syntax `{expr}` inside an attribute value. Evaluated as XPath and replaced with its string result.

---

## B

**Billion Laughs** — A DoS attack using nested XML entities to cause exponential memory expansion. Mitigated by `maxEntityExpansion` limit.

---

## C

**C14N** — Short for Canonical XML. A standardized serialization form producing byte-for-byte reproducible output. Required for XML Digital Signatures.

**Cold tier** — The first level of the XPath LRU cache (512 slots by default). Newly compiled expressions enter here.

**CompiledSchema** — The normalized, optimized form of a `SchemaModel` produced by `compileSchema()`. Used by `ValidationEngine` for fast validation.

**Content model** — The set of allowed child elements and text content for a complex type, defined by its compositor (sequence/choice/all).

**Compositor** — An element in XSD that defines how child elements are grouped: `xs:sequence`, `xs:choice`, or `xs:all`.

---

## D

**DFA** — Deterministic Finite Automaton. A state machine used for content-model validation. Built by `buildDfa(particles, compositor)` and stored per complex type in `CompiledSchema.compiledDfas`. The `DfaModel.particleIndex` map provides O(1) element-name lookup.

**Default namespace** — The namespace bound to the empty prefix via `xmlns="..."`. Applies to elements (not attributes).

**DOM** — Document Object Model. In-memory tree representation of an XML document. Built by `XmlParser`.

---

## E

**Empty element** — An element with no content, written as `<tag/>` or `<tag></tag>`.

**Entity expansion** — Replacing `&name;` with the entity's defined value.

**exclusive C14N** — Canonical XML mode where only actually-used namespace declarations are rendered on each element.

---

## F

**Facet** — A constraint on a simple type. Examples: `xs:minLength`, `xs:pattern`, `xs:enumeration`.

**Fingerprint (XmlDiff)** — A hash string computed from an element's tag name, attributes, text content, and child fingerprints. Cached in a WeakMap.

---

## H

**Hot tier** — The second level of the XPath LRU cache (128 slots by default). Frequently evaluated expressions are promoted here for lowest eviction pressure.

---

## I

**Identity constraint** — `xs:key`, `xs:unique`, or `xs:keyref` declaration that enforces uniqueness and referential integrity within a document.

**Inclusive C14N** — Canonical XML mode where all in-scope namespace declarations are rendered on each element regardless of usage.

---

## L

**LRU** — Least Recently Used. Cache eviction policy used by `SchemaCache` and the XPath expression cache.

---

## M

**Mixed content** — An element that may contain both text nodes and child elements. Declared with `mixed="true"` on the complex type.

---

## N

**Namespace prefix** — A short string (e.g. `xs:`) bound to a namespace URI via `xmlns:prefix="uri"`.

**Nillable** — An element declared with `nillable="true"` may have `xsi:nil="true"` and be empty even if its type requires content.

---

## P

**Particle** — A schema component that defines an element, group, wildcard, or compositor occurrence in a content model.

**PSVI** — Post-Schema-Validation Infoset. The set of type annotations attached to each element after validation. Contains `xsdType`, `normalizedValue`, `validity`, and optional `memberType`.

**PsviMap** — `Map<XmlElement, PsviAnnotation>`. The PSVI storage structure. Changed from `WeakMap` to `Map` in v1.7 to expose `.size`. The map must be released when the document is discarded to allow GC of element nodes.

---

## Q

**QName** — A qualified name with an optional namespace prefix: `prefix:localName` or just `localName`.

---

## R

**Resolved QName** — A QName where the prefix has been replaced with its full URI: `{http://ns}localName`.

---

## S

**SAX** — Simple API for XML. Event-driven parsing that does not build a DOM.

**SchemaMerger** — Internal component that resolves `xs:import`, `xs:include`, and `xs:redefine` using SHA-256 content-hash caching.

**Sequence** — XSD compositor requiring child elements in declared order.

**Substitution group** — A mechanism allowing one element to be substituted for another. The substitutable element declares `substitutionGroup="headElement"`.

---

## T

**Two-tier LRU** — The XPath compiled-expression cache structure with a cold tier (new expressions) and a hot tier (frequently evaluated expressions).

---

## V

**Validity** — The PSVI validity status of an element: `valid` (type checks passed), `invalid` (type check failed), `notKnown` (type could not be resolved).

---

## W

**Well-formed** — An XML document that conforms to XML 1.0 syntax rules (proper nesting, single root, valid character encoding, etc.).

**Wildcard** — `xs:any` or `xs:anyAttribute` allows elements/attributes not explicitly declared in the schema.

---

## X

**xs:all** — Compositor allowing child elements in any order, each appearing at most once.

**xs:assert** — XPath 1.0 assertion on a complex type instance. Evaluated after structure and type validation.

**xs:choice** — Compositor requiring exactly one of the declared child element alternatives.

**xs:keyref** — Identity constraint requiring that values matching a `xs:field` selector also appear as a key in a `xs:key` declaration. Supported in both DOM and streaming (v1.7) validation modes.

**xsi:type** — Runtime type override: `xsi:type="ns:DerivedType"` instructs the validator to use the specified derived type instead of the declared type. Supported in both DOM and streaming (v1.7) validators.

**XSD** — XML Schema Definition. W3C standard for describing the structure and constraints of XML documents.

**XXE** — XML External Entity injection. An attack that uses external entity references to read files or trigger server-side requests.

---

## New in v1.7

**CompiledSchema** — (updated) Now includes `compiledDfas: ReadonlyMap<string, DfaModel>` — one pre-compiled DFA per named complex type. Populated by `compileSchema()` via `_compileDfas()`.

**particleIndex** — Field on `DfaModel`. A `Map<string, NormalisedParticle>` built at `buildDfa()` time for O(1) element-name to particle lookup. Used by `_runAll` and `_runChoice` to avoid O(n) `Array.find` per child element.

**revalidateSubtree** — API function (G38) that re-validates a single `XmlElement` subtree. Designed for editor/IDE "lint on edit" integrations where only a changed region needs rechecking.

**StreamingKeyrefTracker** — SAX-aware xs:key/unique/keyref tracker. Builds an element-name index at construction for O(1) per-element dispatch; accumulates tuples during SAX pass; validates referential integrity after parse.

**StreamingIssue** — Per-issue type emitted by `validateStreaming` and `validateStreamingGenerator`: `{ severity, message, path, line?, col?, code? }`.

**StreamingValidationResult** — Full result from `validateStreaming`: `{ valid, issues[], errorCount, warningCount, durationMs }`.

**statFast** — `SchemaCacheOptions.statFast?: boolean`. When `true`, `getOrLoad` uses `fs.stat` (mtime + size) as a fast freshness fingerprint before reading the file. Skips SHA-256 computation on cache hit.

**sticky regex** — A JavaScript `RegExp` with the `/y` flag. Used in `_XML_NAME_RE` in `XmlParser` and `XmlLexer` for single-pass, SIMD-friendly element name scanning via `consumePattern()`.

**validateStreamingGenerator** — Async generator function that yields `StreamingIssue` as produced. Callers can react to each issue without waiting for the full document.