# Error Code Reference

> Every `XmlErrorCode` value that `XmlError.code` can hold, with description and trigger.
> **v1.7.0** — All codes are stable across minor and patch versions.

---

## Error Code Stability

`XmlErrorCode` is a string literal union. Codes are:
- **Never removed** in minor or patch versions
- **Never renamed** in minor or patch versions
- Adding a new code is a **minor version** change
- Removing or renaming a code requires a **major version** bump

---

## Well-Formedness Errors

| Code | Trigger |
|------|---------|
| `PARSE_UNCLOSED_TAG` | Element not properly closed |
| `PARSE_MISMATCHED_TAG` | `</b>` closing tag for `<a>` |
| `PARSE_MISSING_ROOT` | Empty document or no root element |
| `PARSE_MULTIPLE_ROOTS` | More than one root element |
| `PARSE_UNCLOSED_CDATA` | `<![CDATA[` without `]]>` |
| `PARSE_UNCLOSED_COMMENT` | `<!--` without `-->` |
| `PARSE_INVALID_CHAR` | Illegal character in XML |
| `PARSE_INVALID_ATTR` | Malformed attribute syntax |
| `PARSE_DUPLICATE_ATTR` | Same attribute name twice on one element |
| `PARSE_DUPLICATE_ID` | Same `xml:id` value on two elements |
| `PARSE_EXPECTED_TOKEN` | Unexpected token in input |
| `PARSE_INVALID_PI` | Malformed processing instruction |
| `PARSE_INVALID_DOCTYPE` | Malformed DOCTYPE declaration |
| `LEX_UNEXPECTED_CHAR` | Unexpected character in XML name position |

---

## Namespace Errors

| Code | Trigger |
|------|---------|
| `NS_UNKNOWN_PREFIX` | Prefix used without declaration |
| `NS_DUPLICATE_ATTR` | Two attributes with same namespace URI and local name |
| `NS_INVALID_DECL` | Malformed namespace declaration |

---

## Security Errors

| Code | Trigger |
|------|---------|
| `SEC_MAX_DEPTH` | `maxDepth` exceeded |
| `SEC_MAX_ATTRIBUTES` | `maxAttributes` exceeded on one element |
| `SEC_MAX_TEXT` | `maxTextLength` exceeded |
| `SEC_MAX_NODES` | `maxNodeCount` exceeded |
| `SEC_ENTITY_EXPANSION` | Entity expansion limit exceeded (Billion Laughs protection) |
| `SEC_EXTERNAL_ENTITY` | External entity reference blocked (`SYSTEM`/`PUBLIC` without resolver) |
| `SEC_CIRCULAR_ENTITY` | Circular entity definition detected in DTD |

---

## Schema Errors

| Code | Trigger |
|------|---------|
| `SCHEMA_UNDEFINED_REF` | `ref=""` pointing to non-existent element or type |
| `SCHEMA_CIRCULAR_TYPE` | Type A extends B extends A |
| `SCHEMA_INVALID_DERIVATION` | Extending/restricting a `final` type |
| `SCHEMA_CONFLICTING_DECL` | Same element name declared with different types |
| `SCHEMA_UNDEFINED_TYPE` | Element references type not defined in schema |
| `SCHEMA_CIRCULAR_EXTENSION` | Extension chain depth > 20 |

---

## Validation Errors

| Code | Trigger |
|------|---------|
| `VALID_UNKNOWN_ELEMENT` | Element not declared in schema (strict mode) |
| `VALID_MISSING_ELEMENT` | Required element absent (DFA: minOccurs not met) |
| `VALID_UNEXPECTED_ELEMENT` | Element not in content model (DFA: not a valid transition) |
| `VALID_WRONG_ORDER` | Sequence elements out of declared order |
| `VALID_TOO_FEW` | minOccurs not satisfied |
| `VALID_TOO_MANY` | maxOccurs exceeded |
| `VALID_INVALID_TYPE` | Value fails type / facet check |
| `VALID_MISSING_ATTR` | Required attribute absent |
| `VALID_UNEXPECTED_ATTR` | Attribute not in schema |
| `VALID_INVALID_ATTR_VALUE` | Attribute value fails type check |
| `VALID_NIL_NOT_ALLOWED` | `xsi:nil="true"` on non-nillable element |
| `VALID_ABSTRACT_TYPE` | Abstract type used directly |
| `VALID_XSI_TYPE_UNSAFE` | *(v1.7)* `xsi:type` override resolved to a type not in the derivation chain of the declared type; substitution rejected |
| `VALIDATION_MISSING_ELEMENT` | Required element absent (pipeline alias) |
| `VALIDATION_UNEXPECTED_ELEMENT` | Unexpected element (pipeline alias) |
| `VALIDATION_WRONG_ORDER` | Sequence out of order (pipeline alias) |
| `VALIDATION_TOO_FEW` | minOccurs not satisfied (pipeline alias) |
| `VALIDATION_TOO_MANY` | maxOccurs exceeded (pipeline alias) |
| `VALIDATION_INVALID_TYPE` | Value fails type check (pipeline alias) |
| `VALIDATION_MISSING_ATTR` | Required attribute absent (pipeline alias) |
| `VALIDATION_UNEXPECTED_ATTR` | Unexpected attribute (pipeline alias) |
| `VALIDATION_INVALID_ATTR_VALUE` | Attribute value fails type check (pipeline alias) |
| `VALIDATION_NIL_NOT_ALLOWED` | xsi:nil on non-nillable (pipeline alias) |
| `VALIDATION_ABSTRACT_TYPE` | Abstract type used directly (pipeline alias) |

---

## Identity Constraint Errors

| Code | Trigger |
|------|---------|
| `IDENTITY_DUPLICATE_KEY` | xs:key or xs:unique — duplicate value found |
| `IDENTITY_KEY_MISSING` | xs:key — field value absent on selector node |
| `IDENTITY_KEYREF_UNRESOLVED` | xs:keyref — referenced key does not exist |
| `KEYREF_TUPLE_LIMIT` | *(warning, v1.7)* `StreamingKeyrefTracker` accumulated more than `maxTuples` (default 50,000) key tuples; validation continues but referential-integrity checking is incomplete |

---

## Assertion Errors

| Code | Trigger |
|------|---------|
| `ASSERTION_FAILED` | xs:assert test expression evaluated to false |

---

## Streaming Validation Codes *(v1.7)*

Streaming validation (`validateStreaming`, `validateStreamingGenerator`) uses the same `XmlErrorCode` values when available. The following codes may also appear in `StreamingIssue.code`:

| Code | Context |
|------|---------|
| `PARSE_UNCLOSED_TAG` | Malformed XML detected by SAX parser |
| `VALID_UNKNOWN_ELEMENT` | Element not in schema (strict mode) |
| `VALID_MISSING_ELEMENT` | Required child absent at endElement |
| `VALID_UNEXPECTED_ELEMENT` | Unexpected child at endElement |
| `VALID_TOO_MANY` | maxOccurs exceeded |
| `VALID_INVALID_TYPE` | Text content fails simple type / facet check |
| `VALID_XSI_TYPE_UNSAFE` | `xsi:type` resolved to a type not in the declared type's derivation chain |
| `IDENTITY_KEYREF_UNRESOLVED` | xs:keyref not found after full parse |
| `IDENTITY_DUPLICATE_KEY` | xs:key / xs:unique duplicate in streaming pass |
| `KEYREF_TUPLE_LIMIT` | *(warning)* Tuple accumulation cap (`maxTuples`) exceeded; referential-integrity check skipped |

---

## Example: Catching XmlError

```ts
import { parseXml, XmlError } from 'xml-xsd-engine';

try {
  const doc = parseXml('<a></b>');
} catch (e) {
  if (e instanceof XmlError) {
    console.log(e.code);     // 'PARSE_MISMATCHED_TAG'
    console.log(e.message);  // human-readable description
    console.log(e.line);     // line number (if available)
    console.log(e.col);      // column number (if available)
  }
}
```

---

## ValidationIssue

Validation produces `ValidationIssue` objects (not thrown exceptions):

```ts
interface ValidationIssue {
  severity:  'error' | 'warning' | 'info';
  message:   string;
  path:      string;       // XPath-like: /catalog/item[2]/price
  line?:     number;
  col?:      number;
  offset?:   number;       // 0-based char offset
  endLine?:  number;       // range end
  endCol?:   number;       // range end column
  code?:     XmlErrorCode;
  category?: 'well-formedness' | 'namespace' | 'schema' | 'validation' | 'identity' | 'security' | 'assertion';
  stage?:    string;       // pipeline stage that produced this issue
}
```

---

## StreamingIssue *(v1.7)*

```ts
interface StreamingIssue {
  severity: 'error' | 'warning';
  message:  string;
  path:     string;
  line?:    number;
  col?:     number;
  code?:    string;  // XmlErrorCode or streaming-specific string
}
```