Stage 2 Draft / September 3, 2026

JSON.parse Options

1 Structured Data

Editor's Note

This proposal builds on top of ecma262 editorial PR #3933, which introduces the following SDOs:

1.1 The JSON Object

1.1.1 JSON.parse ( text [ , reviver ] )

This function parses a JSON text (a JSON-formatted String) and produces an ECMAScript language value. The JSON format represents literals, arrays, and objects with a syntax similar to the syntax for ECMAScript literals, Array Initializers, and Object Initializers. After parsing, JSON objects are realized as ECMAScript objects. JSON arrays are realized as ECMAScript Array instances. JSON strings, numbers, booleans, and null are realized as ECMAScript Strings, Numbers, Booleans, and null.

The optional reviver parameter is either a function that can filter and transform the results, or an options bag configuring native transforms. FWhen reviver is a function, for each value produced by the parse, reviver is called with three arguments (the associated property key, the value, and a context object). If the property is unmodified and its value is primitive, the provided context object has a "source" property containing source text of the corresponding Parse Node. If the call returns undefined, the property is deleted. Otherwise, the property is redefined to use the return value.

  1. Let jsonString be ? ToString(text).
  2. Let options be ? CreateJSONParseOptions(reviver).
  3. Let parseResult be ? ParseJSON(jsonString, options).
  4. If IsCallable(reviver) is false, return parseResult.[[Value]].
  5. Let root be OrdinaryObjectCreate(%Object.prototype%).
  6. Assert: parseResult.[[Key]] is the empty String.
  7. Perform ! CreateDataPropertyOrThrow(root, parseResult.[[Key]], parseResult.[[Value]]).
  8. Return ? InternalizeJSONProperty(root, parseResult.[[Key]], reviver, parseResult).

The "length" property of this function is 2𝔽.

1.1.1.1 ParseJSON ( text, options )

The abstract operation ParseJSON takes arguments text (a String) and options (a JSON Parse Options Record) and returns either a normal completion containing a JSON Parse Record, or a throw completion.

Note 1

This algorithm references the JSONValue nonterminal from ECMA-404.

It performs the following steps when called:

  1. If StringToCodePoints(text) is not a valid JSON text as specified in ECMA-404, throw a SyntaxError exception.
  2. NOTE: JSON whitespace is a strict subset of WhiteSpace, and JSON syntax does not support comments.
  3. Let jsonParseNode be ParseText(text, JSONValue).
  4. If jsonParseNode is not a Parse Node, throw a SyntaxError exception.
  5. Let key be the empty String.
  6. Let result be the JSONEvaluation of jsonParseNode with arguments key and options.
  7. Return result.

It is not permitted for a conforming implementation of JSON.parse to extend the JSON grammars. If an implementation wishes to support a modified or extended JSON interchange format it must do so by defining a different parse function.

Note 2

Valid JSON text is a syntactic subset of the ECMAScript PrimaryExpression syntax. However, because JSONEvaluation behaves differently than Evaluation, the same source text can produce different results when evaluated as a PrimaryExpression rather than as JSON. Furthermore, the early error for duplicate "__proto__" properties in object literals (13.2.5.1), which has no analogue in JSON, means that some texts accepted by ParseJSON are not valid as a PrimaryExpression, (e.g., {"__proto__":null,"__proto__":null}).

 Note 3

In the case where there are duplicate name Strings within an object, lexically preceding values for the same key shall be overwritten.

1.1.1.2 JSON Parse Options Records

A JSON Parse Options Record is a Record value used to specify JSON deserialization options.

JSON Parse Options Records have the fields listed in Table 1.

Table 1: JSON Parse Options Record Fields
Field Name Value Meaning
[[Freeze]] a Boolean Whether objects (including arrays) should be frozen upon creation.
[[PreferNullPrototype]] a Boolean Whether non-array objects should be created with a null prototype.

1.1.1.3 CreateJSONParseOptions ( [ options ] )

The abstract operation CreateJSONParseOptions takes optional argument options (an ECMAScript language value) and returns either a normal completion containing a JSON Parse Options Record or a throw completion. It performs the following steps when called:

  1. Let freeze be false.
  2. Let preferNullPrototype be false.
  3. If options is an Object and IsCallable(options) is false, then
    1. Let preferNullPrototypeChoice be undefined.
    2. If options ? HasProperty(options, "freeze"), then
      1. Let freezeChoice be ? Get(options, "freeze").
      2. If freezeChoice is not undefined, set freeze to ToBoolean(freezeChoice).
    3. If options ? HasProperty(options, "preferNullPrototype"), then
      1. Set preferNullPrototypeChoice to ? Get(options, "preferNullPrototype").
      2. If preferNullPrototypeChoice is not undefined, set preferNullPrototype to ToBoolean(preferNullPrototypeChoice).
    4. If freeze is true and preferNullPrototypeChoice is undefined, set preferNullPrototype to true.
  4. Return the JSON Parse Options Record { [[Freeze]]: freeze, [[PreferNullPrototype]]: preferNullPrototype }.

1.1.1.4 Runtime Semantics: JSONEvaluation

The syntax-directed operation JSONEvaluation takes arguments key (a property key) and options (a JSON Parse Options Record) and returns a JSON Parse Record.

It generally produces the same values as Evaluation given the same inputs, but is defined over a much narrower set of productions, namely ECMA-404's JSONValue. Unlike Evaluation, it does not raise an early error when "__proto__" appears twice as a key (see 13.2.5.1). It also does not perform [[SetPrototypeOf]] when encountering a "__proto__" key, and instead creates an ordinary data property (see 13.2.5.5).

It is defined piecewise over the following productions:

JSONArray : [ ] [ JSONElementList ]
  1. Let array be ! ArrayCreate(0).
  2. Let elements be a new empty List.
  3. If JSONElementList is present, perform JSONArrayAccumulation of JSONElementList with arguments array, options, elements, and 0.
  4. If options.[[Freeze]] is true, perform ! SetIntegrityLevel(array, frozen).
  5. Return the JSON Parse Record { [[ParseNode]]: JSONArray, [[Key]]: key, [[Value]]: array, [[Elements]]: elements, [[Entries]]: « » }.
 JSONObject : { } { JSONMemberList }
  1. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  2. If options.[[PreferNullPrototype]] is true, then
    1. Let obj be OrdinaryObjectCreate(null).
  3. Else,
    1. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  4. Let entries be a new empty List.
  5. If JSONMemberList is present, perform JSONMemberListEvaluation of JSONMemberList with argument obj, options, and entries.
  6. If options.[[Freeze]] is true, perform ! SetIntegrityLevel(obj, frozen).
  7. Return the JSON Parse Record { [[ParseNode]]: JSONObject, [[Key]]: key, [[Value]]: obj, [[Elements]]: « », [[Entries]]: entries }.

1.1.1.5 Runtime Semantics: JSONArrayAccumulation

The syntax-directed operation JSONArrayAccumulation takes arguments array (an Array), options (a JSON Parse Options Record), elements (a List of JSON Parse Records), and nextIndex (a non-negative integer) and returns a non-negative integer. It is analagous to ArrayAccumulation, except defined over a much narrower grammar (namely ECMA-404), and calls JSONEvaluation on its elements, rather than Evaluation. It is defined piecewise over the following productions:

JSONElementList : JSONValue JSONElementList , JSONValue
  1. If the derived JSONElementList is present, set nextIndex to the JSONArrayAccumulation of the derived JSONElementList with arguments array, options, elements, and nextIndex.
  2. Let key be ! ToString(𝔽(nextIndex)).
  3. Let parseRecord be the JSONEvaluation of JSONValue with arguments key and options.
  4. Perform ! CreateDataPropertyOrThrow(array, key, parseRecord.[[Value]]).
  5. Append parseRecord to elements.
  6. Return nextIndex + 1.

1.1.1.6 Runtime Semantics: JSONMemberListEvaluation

The syntax-directed operation JSONMemberListEvaluation takes arguments obj (an Object), options (a JSON Parse Options Record), and entries (a List of JSON Parse Records) and returns unused. It is analagous to PropertyDefinitionEvaluation, except 1) it is defined over a much narrower grammar, 2) it does not include the special handling of "__proto__" described in 1.1.1.4, and 3) it calls JSONEvaluation instead of Evaluation. It is defined piecewise over the following productions:

JSONMemberList : JSONMemberList , JSONMember
  1. Perform JSONMemberListEvaluation of the derived JSONMemberList with arguments obj, options, and entries.
  2. Perform JSONMemberListEvaluation of JSONMember with arguments obj, options, and entries.
  3. Return unused.
 JSONMember : JSONString : JSONValue
  1. Let dummyKey be the empty String.
  2. Let propertyKeyRecord be the JSONEvaluation of JSONString with arguments dummyKey and options.
  3. Let key be propertyKeyRecord.[[Value]].
  4. Assert: key is a property name.
  5. Let propertyValueRecord be the JSONEvaluation of JSONValue with arguments key and options.
  6. Assert: obj is an ordinary, extensible object with no non-configurable properties.
  7. Perform ! CreateDataPropertyOrThrow(obj, key, propertyValueRecord.[[Value]]).
  8. Append propertyValueRecord to entries.
  9. Return unused.

A Copyright & Software License

Copyright Notice

© 2026 Robin Ricard, Rick Button, Ashley Claymore, Nicolò Ribaudo, Peter Klecha

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.