Working with APIs and JSON
XML uses tags and attributes; JSON uses curly braces and key-value pairs to represent the same information.
Two Ways to Structure Data
When two programs exchange information across the web, they must agree on a data format. XML and JSON can both represent the same information, but they organize that information differently. XML uses nested tags and attributes. JSON uses curly braces and key-value pairs.
Tags, Attributes, and Keys
XML uses nested tags to structure information. A person element can contain name, phone, and email child elements. An opening tag can also contain an attribute, such as intl on a phone element, to attach additional information to that element. The attribute belongs to the phone tag rather than appearing as a separate child element.
JSON abandons the tag-and-attribute model. Its outer curly braces represent an object, and the information inside is organized as key-value pairs. In the JSON representation, the XML intl attribute can become an ordinary key such as phone_intl. It is placed at the same structural level as phone rather than being attached through a separate attribute system.
Representing a phone detail
Represent a person's name, phone number, and whether that phone number is international using the two structural approaches.
- 1Start with the XML approach
Place the information inside nested tags. The phone element can carry intl as an attribute in its opening tag.
- 2Translate to the JSON approach
Use an object surrounded by curly braces. Represent phone and the international-number detail as separate key-value pairs, such as phone and
phone_intl. - 3Compare the structures
XML distinguishes the phone element from its intl attribute. JSON treats both pieces of information as keys at the same level.
The two formats can describe the same information, but JSON uses one consistent key-value model instead of separate tags and attributes.
From JSON to Native Data
JSON is designed around structures that programmers commonly use. Curly braces represent objects, which map to dictionary-like structures such as dictionaries, hash maps, objects, or associative arrays. Square brackets represent arrays, which map to list-like structures. JSON also supports strings, numbers, booleans, and null.
Nearly all programming languages have equivalents to dictionaries and lists. Because JSON uses the same broad organization, a program can often parse incoming JSON directly into its native data structures. A Python program can receive JSON as a Python dictionary, while a JavaScript program can parse it into a JavaScript object. This avoids the need to build a custom object model before using the data.
The API Exchange Path
Consider two programs that need to share information. Program A, written in Python, can organize its data as a dictionary, serialize that dictionary to JSON, and send the JSON over a network. Program B, written in JavaScript, can receive the JSON and parse it into a JavaScript object. The shared JSON format allows the programs to exchange data even though they use different programming languages.
This flow explains why JSON is a natural bridge for program communication. The sender and receiver do not need to use the same programming language. They need to agree on the JSON structure. Because that structure resembles data structures already available in many languages, the receiving program can use the parsed data with relatively little translation.
| Concern | JSON | XML |
|---|---|---|
| Main structure | Objects with curly braces and key-value pairs | Nested tags |
| Additional information | Another key-value pair | An attribute attached to an opening tag |
| Programming-language mapping | Directly resembles dictionaries, objects, and lists | Requires understanding tags, attributes, and nested hierarchies before conversion |
| Design emphasis | Minimal and consistent | More capable and able to represent advanced metadata |
Both formats can exchange data, but they use different structural models.
Choosing the Simpler Bridge
JSON is simpler than XML because it has fewer syntactic concepts. JSON does not include XML's separate attribute system, namespaces, processing instructions, or other advanced features. Instead, it focuses on objects, arrays, strings, numbers, booleans, and null. This reduces the number of ideas a programmer must learn and the complexity a parser must handle.
This simplicity is useful when programs need to exchange data quickly and consistently. JSON is the default choice for modern web APIs and mobile applications because its structure maps naturally to common programming-language data structures. XML remains useful for complex document formats, configuration files requiring extensive metadata, and existing XML-based or legacy systems.
Mistakes in Structural Thinking
Common mistake Treating JSON attributes as a separate feature
What it looks likeAssuming that phone_intl must be attached to phone through an attribute mechanism
Why it failsJSON does not have a separate concept of attributes. Information that XML represents as an attribute becomes another JSON key-value pair.
Do this insteadRead every JSON entry as part of the same object structure unless the format explicitly nests it inside another object.
Common mistake Assuming that JSON is tied to one programming language
What it looks likeThinking that JSON is only useful to JavaScript programs
Why it failsNearly all programming languages have equivalents to dictionaries and lists, so JSON can act as a bridge between programs written in different languages.
Do this insteadFocus on the shared data shape rather than the language used by the sender or receiver.
Common mistake Concluding that simpler means less useful
What it looks likeRejecting JSON because XML supports more advanced metadata features
Why it failsJSON's smaller set of concepts reduces parsing complexity and learning overhead, which is valuable for ordinary program-to-program exchange.
Do this insteadChoose JSON for a new, straightforward exchange and consider XML when an existing system or advanced XML features require it.
Common mistake Comparing only the visual appearance
What it looks likeNoticing curly braces in JSON but missing the connection to dictionaries and lists
Why it failsThe important reason for JSON's popularity is its alignment with how programs store and organize data.
Do this insteadWhen evaluating a format, ask how its structures map to the receiving program's native data structures.
Check Your Understanding
A data exchange contains a person element, a phone element with an intl attribute, and an email element. Explain how JSON would represent the same information without using tags or attributes. Then identify which JSON structure would map to a dictionary-like data structure and which structure would map to a list-like data structure.
Hints
- Start with an object represented by curly braces.
- Represent the phone detail and the international-number detail as ordinary key-value pairs.
- Look for the difference between an object and an array.
- 1XML organizes information with nested tags and can attach metadata through attributes.
- 2JSON uses objects, curly braces, and key-value pairs, so it has no separate attribute concept.
- 3JSON objects and arrays map naturally to dictionary-like and list-like structures in many programming languages.
- 4That direct mapping makes JSON an effective bridge when different programs exchange data through an API.
- 5XML remains appropriate for existing XML systems and situations that need its advanced metadata capabilities.
Key Takeaways
- XML uses nested tags and attributes, while JSON uses curly-brace objects and key-value pairs.
- JSON turns information that might be an XML attribute into an ordinary key-value pair.
- JSON's objects and arrays resemble dictionaries, objects, and lists available in many programming languages.
- This direct mapping makes JSON a simple and effective format for data exchange between programs.
- XML is still useful when advanced metadata, complex documents, or existing XML-based systems require it.