Skip to content

Numeric character references (A, A) are not decoded unless htmlEntities is enabled #892

Open

Description

@philppplik

With default options, processEntities is true and the five predefined XML entities (<, >, &, ", ') are decoded as expected. Numeric character references, however, are silently left as literal text unless htmlEntities: true is passed:

const { XMLParser } = require('fast-xml-parser');

const parser = new XMLParser(); // processEntities defaults to true

parser.parse('<r>&lt;&gt;&amp;</r>');
// { r: '<>&' }  -- named entities decoded

parser.parse('<r>&#65;&#x42;</r>');
// { r: '&#65;&#x42;' }  -- numeric refs NOT decoded (expected: { r: 'AB' })

parser.parse('<r a="&#65;"/>', { ignoreAttributes: false });
// attributes affected the same way

new XMLParser({ htmlEntities: true }).parse('<r>&#65;&#x42;</r>');
// { r: 'AB' }  -- only decoded when htmlEntities is on

Numeric character references are not HTML entities - they are part of core XML. Per the XML 1.0 spec (section 4.1, "Character and Entity References"), a well-formed XML processor must recognize &#...; and &#x...; references in content and attribute values, independent of any HTML entity table.

Looking at the source, this seems to come from OrderedObjParser wiring numericAllowed to the htmlEntities option when constructing the EntityDecoder:

this.entityDecoder = new EntityDecoder({
  namedEntities: { ...namedEntities, ...externalEntities },
  numericAllowed: this.options.htmlEntities, // <-- ties XML char refs to the HTML entities option
  ...
});

So a user who parses XML with default options (and htmlEntities defaults to false) gets raw &#65; sequences in their data, while named XML entities are decoded. I ran into this with a feed that encodes non-ASCII characters as numeric refs.

Tested on fast-xml-parser 5.11.2 (npm latest) with Node 22. The same behavior exists in 4.x, so it may be intentional - but if so, it would be great to have it documented next to processEntities, since the current default contradicts XML spec compliance.

Activity

  1. github-actions commented on Oct 18, 2026

    @github-actions

    We're glad you find this project helpful. We'll try to address this issue ASAP. You can join Discord channel(https://discord.gg/X4Qp9u6Vz) for anonucements and pre release discussions. Don't forget to star this repo.

  2. guocn commented on Oct 22, 2026

    @guocn

    I am working on the numeric-reference decoding fix and regression coverage for text, attributes, HTML-entity opt-in, and disabled entity processing. AI assistance: OpenClaw (cpa/gpt-6.1-sol); no human review is claimed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions