JSON, XML, and structured data

Objectives

By the end of the lesson, you can read and write a simple JSON, you know the data types of JSON and its typical errors, you know when XML may come into play, and you understand why a data format does not replace the API contract.

Why do we need a common data format?

An API response is useful not because it contains text, but because the client can interpret it consistently. If the server described a course in free text ("There are nine places left for the Web Programming course"), the client would have to extract the data by text analysis, which is brittle. That is why we send data in structured form: with named fields, types, and lists. The two most widespread web forms are JSON and XML.

JSON

JSON (JavaScript Object Notation) is, according to RFC 8259, a "lightweight, text-based, language-independent data interchange format". It derives from the object-literal syntax of JavaScript, but any programming language can handle it. It has six data types: four simple ones (string, number, boolean, null) and two structured ones (object, array).

{
  "id": "webprog",
  "cim": "Webprogramozás 1.",
  "ferohely": 40,
  "jelentkezett": 31,
  "elerheto": true,
  "oktato": null,
  "temak": ["HTTP", "böngésző", "API"]
}

• An object ({ ... }) consists of key–value pairs; the keys are strings, between quotation marks.
• An array ([ ... ]) is an ordered list of values.
• The boolean and null values are lowercase (true, false, null), as the RFC also requires.
• JSON sent over the network is encoded in UTF-8, and its media type is application/json (2.5).

The keys in the example are deliberately without accents (cim, ferohely): JSON also allows accented keys, but restricting identifiers to ASCII (American Standard Code for Information Interchange) characters is a common convention, because it causes fewer encoding and handling errors.

Run: what does a program do with JSON?

Reading the text above with Node.js (JSON.parse):

const k = JSON.parse(szoveg);
console.log(typeof k.id, typeof k.ferohely, typeof k.elerheto, Array.isArray(k.temak), k.oktato, k.nincs_ilyen);
console.log("oktato in k:", "oktato" in k, "| nincs_ilyen in k:", "nincs_ilyen" in k);
console.log(k.ferohely - k.jelentkezett);

string number boolean true null undefined
oktato in k: true | nincs_ilyen in k: false
9

Numbers stay numbers, the field with a null value exists (the instructor has not been assigned yet), whereas the missing field is not in the JSON. The two cases are not the same: the contract must state which one the service uses. The number of free places (ferohely - jelentkezett) is 9.

Typical errors

Invalid JSON cannot be read in. Tried examples:

{'cim': 'x'}        -> SyntaxError   (apostrophe instead of a double quote)
{"cim": "x",}       -> SyntaxError   (trailing comma)
{"cim": "x"         -> SyntaxError   (missing closing brace)
{"ferohely": 040}   -> SyntaxError   (leading zero in a number)

A type error is also possible. If according to the API contract ferohely is a number, but it arrives as a string ("40"), the client's code silently calculates wrongly:

const x = JSON.parse('{"ferohely":"40"}');
console.log(x.ferohely + 1, typeof x.ferohely);   // 401 string

Concatenation took place instead of addition. JSON itself does not protect against such errors; the contract and validation must.

Finally: JSON has no date type. JavaScript's JSON.stringify turns a date into a string ("2026-10-11T12:00:00.000Z") and leaves out a field whose value is undefined. The format of dates must therefore be agreed on in the contract.

XML

XML (Extensible Markup Language) is a W3C Recommendation (XML 1.0, fifth edition, 2008): a general-purpose markup language designed so that content can be transmitted and processed on the web. The same course in XML:

<kurzus id="webprog" elerheto="true">
  <cim>Webprogramozás 1.</cim>
  <temak><tema>HTTP</tema><tema>böngésző</tema><tema>API</tema></temak>
</kurzus>

XML consists of elements and attributes, which can be nested within each other. Here the value of the elerheto attribute is text: whether it is a boolean is stated by the data schema or the documentation, not by the format itself. (We did not run the XML example, because the Node.js standard library contains no XML parser.)

XML is not "old JSON", but a different model with a different toolset. It comes into play where a document-like structure, namespaces, or interoperation with existing XML-based systems is needed.

flowchart LR
    A[Meaning of a course] --> J[JSON structure]
    A --> X[XML structure]
    J --> K[Client interprets]
    X --> K

Data and document

JSON typically describes data records, lists, and relationships that the client processes. HTML, by contrast, is a web document: besides structure, it carries the meaning and links needed for presentation. XML can be used both for data exchange and for document-like content. The categories are not exclusive, but the purpose of use helps in choosing the format.

Missing data and changing structure

The format alone does not say whether a field is mandatory. If the instructor of a course has not been assigned yet, the contract must clarify whether the field is missing, has a null value, or gets some other signal. The client cannot infer all possible states from a single successful sample response. Likewise, the order of a list, the shape of dates, and the meaning of identifiers must be agreed on. Choosing a format is therefore only the first layer; real data exchange rests on a contractual meaning.

RFC 8259 also warns that it does not forbid repeated key names within an object, but "the behavior of software that receives such an object is unpredictable": some parsers keep the last value, others signal an error. Repeated keys should therefore be avoided.

Worked example: the course data of Kurzuspont

The contract of Kurzuspont for the course object:

Field	Type	Mandatory?	Note
id	string	yes	identifier, not a number
cim	string	yes
ferohely	number	yes	integer
jelentkezett	number	yes	at most ferohely
oktato	string or null	yes (but may be null)	null = not yet assigned
temak	list of strings	no	may be missing

From this a client knows that it must always find the oktato field, but its value can be null, while temak may even be missing. A sample JSON would not replace this table.

Common misconceptions

Statement	Clarification
"JSON is the API itself."	JSON is a data format; the API also defines the operations and the contract.
"Content-Type describes the meaning of every field."	It indicates only the format of the body.
"XML and HTML are the same."	Both are markup languages, but they were made for different purposes and with different rules.
"One sample response reveals every possible state."	Missing fields and errors need separate description.
"In JSON, null and a missing field are the same."	They are two separate states; the contract must define them.

In brief

• Structured data makes the response machine-processable with named fields, types, and lists.
• JSON has six data types; because of its strict syntax even a small error makes it unreadable.
• null and a missing field, and a number and a string containing a number, are not the same.
• XML works with elements and attributes; it is used in document-like or XML-based systems.
• A format is not a contract: the meaning of the fields must be fixed separately.

Review questions

1. What is the difference between "ferohely": 40 and "ferohely": "40"?
2. What does it mean that a field is null, and how is it different from a missing field?
3. Why is {"cim": "x",} invalid JSON?
4. What extra information does Content-Type not tell you?

Learning resources

• The JSON Data Interchange Format, RFC 8259 — the official description of JSON.
• Extensible Markup Language (XML) 1.0 — the W3C Recommendation; advanced reading.