Analysis of Duplicate Key Syntax Validity and Implementation Differences in JSON Objects

The Issue of Duplicate Keys in JSON Syntax Specifications

In discussions about the JSON data interchange format, the validity of duplicate key names within objects is a frequently mentioned technical detail. According to the ECMA-404 standard "The JSON Data Interchange Syntax," the document clearly specifies the format of JSON text but does not impose mandatory requirements on the uniqueness of key names within objects. The definition of a JSON object on page 2 of the standard describes it merely as "zero or more name/value pairs surrounded by a pair of curly bracket tokens," where a name is a string, each name is followed by a colon token, and values are separated by commas. This openness in formulation provides theoretical possibility for the existence of duplicate keys.

Divergent Positions in Standard Documents

However, RFC 8259 "The JavaScript Object Notation (JSON) Data Interchange Format" takes a different stance on this issue. The document explicitly states in Section 4: "The names within an object SHOULD be unique." The term "SHOULD" here needs to be understood according to the definition in BCP 14—this means there may be valid reasons in particular circumstances to ignore this recommendation, but all implications must be fully understood and carefully weighed before choosing a different course of action.

RFC 8259 further explains why unique key names are important: when all names in an object are unique, the object is interoperable in the sense that all software implementations receiving that object will agree on the name-value mappings. When the names are not unique, the behavior of software receiving such an object becomes unpredictable. Many implementations report only the last name/value pair, others may report an error or fail to parse the object, while some implementations may report all name/value pairs, including duplicates.

Specific Differences in Programming Language Implementations

JSON libraries in different programming languages exhibit significant variations in handling duplicate keys, reflecting the tension between standard specifications and practical implementations. Here are several typical examples:

JavaScript Implementation

ECMA-262 "ECMAScript® Language Specification" stipulates in the JSON.parse section: "In the case where there are duplicate name Strings within an object, lexically preceding values for the same key shall be overwritten." This means that in JavaScript environments, the principle of "last value wins" is adopted. For example:

const jsonString = '{"a": "x", "a": "y"}';
const parsedObject = JSON.parse(jsonString);
console.log(parsedObject.a); // Outputs "y"

Java Implementation

The Java JSON implementation created by Douglas Crockford takes a stricter position. When attempting to parse a string containing duplicate keys, this library throws an exception. For example:

import org.json.JSONObject;
import org.json.JSONException;

public class JsonDuplicateExample {
    public static void main(String[] args) {
        try {
            JSONObject obj = new JSONObject("{"a": "x", "a": "y"}");
        } catch (JSONException e) {
            System.out.println(e.getMessage()); // Outputs: Duplicate key "a"
        }
    }
}

Flexibility in C++ Standard Library

The implementation in the C++ standard library demonstrates another possibility for handling duplicate keys. When deserializing a JSON object into a std::map, rejecting duplicate keys is reasonable since map containers require key uniqueness. However, when deserializing into a std::multimap, accepting duplicate keys as normal is entirely reasonable. This design choice reflects the perspective stated in the preface of the ECMA-404 standard: "It is expected that other standards will refer to this one, strictly adhering to the JSON text format, while imposing restrictions on various encoding details. Such standards may require specific behaviours. JSON itself specifies no behaviour."

Practical Recommendations and Conclusion

Based on the above analysis, for handling duplicate keys in JSON objects, developers should consider the following practical recommendations:

1. When designing and implementing JSON data interchange, follow the recommendation of RFC 8259 to ensure the uniqueness of object key names, thereby guaranteeing cross-platform interoperability.
2. When it is necessary to handle JSON data that may contain duplicate keys, clearly understand the specific behavior of the JSON library being used and document these behaviors.
3. In scenarios requiring support for duplicate keys (such as conversion to std::multimap), choose JSON parsing libraries that support this functionality and explicitly document it in interface documentation.
4. For data validation and error handling, consider checking key name uniqueness before parsing or providing appropriate error handling mechanisms after parsing.

From a technical essence perspective, the issue of duplicate keys in JSON reflects the balance between data format specifications and concrete implementations. The ECMA-404 standard maintains openness at the syntactic level, while RFC 8259 offers practical recommendations from an interoperability standpoint. Implementations in different programming languages make different design choices based on their data structures and application scenarios, providing developers with flexibility but also requiring clear understanding of their tools' behaviors.