Opt-in JSON comments and trailing commas

Under discussion; not accepted. The RFC page (version 1.0, dated 2026-10-13, status Under Discussion) and the official RFC index both list it as under discussion. The proposed version is PHP 8.7. The page was created on 13 October, after RFC karma was requested and granted that morning. The RFC change feed lists an edit at 19:24 UTC, and the header now links the discussion thread. The author opened the discussion at 18:36 UTC. The voting thread reads "tbd", so there is no vote date.

Proposal

Two new global constants in ext/json, accepted in $flags by json_decode() and json_validate():

• JSON_ALLOW_COMMENTS (1 << 23) accepts // line comments and /* … */ block comments.
• JSON_ALLOW_TRAILING_COMMAS (1 << 24) accepts one comma after the last element or member of a nonempty array or object.

The flags are independent. Without them, results, error codes and error locations do not change. json_encode() does not change and ignores both flags. Before this RFC, json_validate() accepted only JSON_INVALID_UTF8_IGNORE. Other flags still throw ValueError, and its message would name the three accepted flags.

Comment rules in the RFC:

• A comment can appear where JSON allows whitespace, but not inside a token (tr/**/ue and -/**/1 are syntax errors). Comment markers inside strings are string text.
• Block comments do not nest. /*/1 is an unterminated comment, and /**/1 is the value 1.
• A line comment ends at LF, CR or CR LF, but not at U+2028/U+2029. # comments are not accepted.
• Input that contains only comments is a syntax error, the same as empty input.
• A NUL byte in a comment raises JSON_ERROR_CTRL_CHAR, even with the invalid-UTF-8 flags. Invalid UTF-8 raises JSON_ERROR_UTF8 unless JSON_INVALID_UTF8_IGNORE/_SUBSTITUTE is given.
• An unterminated block comment raises JSON_ERROR_SYNTAX at the position of its /*. Error line numbers count lines inside comments.

Trailing-comma rules: [1, 2, 3,] and {"a": 1,} are accepted, but [,], {,}, [1,,], [1,,2] and a top-level 1, stay syntax errors. [1,} gives the same state-mismatch error as [1}. No new error codes are added, nesting depth is unchanged, and a UTF-8 BOM is still a syntax error.

Relation to JSON5, JSONC and JWCC

The RFC does not add JSON5 (single quotes, unquoted keys, hexadecimal numbers, NaN/Infinity). It says JSON_ALLOW_COMMENTS matches the JSONC draft without trailing commas, and that both flags together match JWCC, except that in this RFC a CR alone also ends a line comment.

A single JSON_ALLOW_JSONC flag, suggested by Tim Düsterhus in the pre-RFC thread, is listed under rejected features. The reasons given are that the jsonc.org specification is a draft, it makes trailing commas optional, and the name JSONC has more than one meaning. Later RFCs could add a combined constant if a stable standard appears.

Ballot

Two primary votes, one per flag, each needing a 2/3 majority. The results are independent.

Evidence the RFC cites

These are the author's measurements, not independently reproduced here:

• A differential test of 120,025 generated inputs (840,175 checks) found the same results, error codes and messages on master and on the branch without the new flags.
• Callgrind instruction counts for a 7.6 MB document show +1.60% for json_decode() and +1.69% for json_validate() on strict JSON without the new flags. The RFC says two scanner changes, not yet in the pull request, reduce this to +0.56% and +0.59%.
• Demand: Packagist install counts for colinodell/json5 and adhocore/json-comment as of 2026-10-12.

Compatibility and limitations

• A user-defined global constant with either name now triggers an "already defined" warning, and the built-in value wins. Namespaced constants are not affected.
• json_decode() currently ignores unknown flag bits, so code that already passes bit 23 or 24 by mistake could start accepting comments or trailing commas.
• The implementation pull request is labelled "ABI break" because it adds macros to php_json.h. The RFC says no struct or function signature changes.
• The RFC says no other JSON_* flag uses bits 23 and 24. The pull request description notes that the proposed duplicate-key flags in php-src #22473 use the same bits, so whichever is merged second must move. These two statements don't contradict each other, because #22473 isn't merged.

Discussion

On 13 October Tim Düsterhus replied that he was "not happy, but the rejected [section] is well-argued" and had no other comments. Larry Garfield agreed: "I have no remaining objections to it." Both had raised points in the pre-RFC thread. These are list replies, not votes.

Related

• 13 October 2026 digest