Course sections

Software Development and Design

Lesson 1: Compare Data Formats (XML, JSON, YAML)

devnet associate 200-901 exam study guide course

Compare data formats (XML, JSON, and YAML)

When using Application Programming Interfaces (or APIs) through software, it is super critical to receive and transmit data in forms that are standards-based and machine and human readable.

Let’s go over a few reasons why it is so.

  • It allows use of off-the-shelf software tools to convert and accept them into native data structures (e.g. JSON value/pairs to Python dictionaries)
  • It makes it easier to write code that communicates with messages in format that another remote endpoint can easily consume
  • It is easier to read and manipulate received messages
  • It makes it easier to detect malformed messages

Extensible Markup Language (XML) and JavaScript Object Notation (or JSON, pronounced as Jay-sun) and YAML Ain’t Markup Language (YAML) are the main data encoding formats used in remote APIs today. JSON is both a human-friendly and machine-readable format and sends data in name-value pairs. JSON and YAML can be converted to each other without much effort.

JSON is best known for the curly brace syntax. It is popular because it is easier to read and natively maps to Python dictionary data structure. However, XML is bit of an outlier, it is less simple to parse and convert to JSON or YAML. It is an older format so there are plenty of mature APIs that still use it.

Parsing JSON, YAML and XML is a common requirement of interacting with REST APIs.

XML Example

XML is the parent of HTML. It is generic method to wrapping textual data in symmetrical tags to indicate semantics. XML files typically carry an extension of .xml.

XML Prologue

The first line in XML file is known as the XML prologue. It has a special format and bracketed by <? and ?>. It contains the tag name xml and attributes stating the version and a character encoding. Normally, you’d find the version to be “1.0” and the character encoding to be “UTF-8” or 8-bit Unicode Transformation Format.

XML Comments

XML files can include comments, much like their HTML counterpart, they are enclosed in <! — and –> tags.

XML Body

Everything after the prologue is considered to be the XML body. The individual elements are surrounded by symmetrical pairs of tags, the opening tag < and the closing tag > symbols. The closing tag includes a “/” preceding the closing tag.

The main body of the document as a whole is always surrounded by an outermost tag pair, e.g. <root> and </root> in the example.

The structure of an XML document is like a tree with branches (known as elements) containing further branches (known as sub-elements), e.g. <element></element> are elements whereas <gender></gender> are sub-elements.

XML Attributes

XML allows you to embed attributes inside the tags to convey additional information. Version and the encoding types in the XML prologue are examples of attributes. Attribute values are carried inside double quotes and an element can have multiple attributes each with a unique name.

XML Namespaces

Some XML messages or documents incorporate a reference to a specific namespace to convey how they should be consumed. Namespaces are defined by standard bodies such as the IETF, e.g. xml:ns:netconf for NETCONF.

JSON Example

Now, let’s convert above XML into JSON.

JSON Data Types

JSON data types include numbers, strings, and boolean (True or False). JSON filenames typically end in “.json”.

JSON Objects

Much like JavaScript, individual objects comprise of key/value pairs surrounded by braces e.g. {“key”:”value”}.

JSON Maps and Lists

Objects can also contain multiple key/value pairs, separated by commas, similar to Python dictionaries. JSON values can also contain lists of data objects.

Unlike XML or YAML, JSON doesn’t support adding any kind of comments. JSON format also doesn’t give any significance to white spaces, so you can indent your JSON data using tabs or spaces or nothing at all.

YAML Example

YAML format is like a superset of JSON but even easier to read. One of the most commonly known use of YAML is configuration files and particularly for writing declarative automation templates such as Ansible playbooks. YAML parsers can also parse JSON but not vice versa.

YAML File Structure

YAML files open with “—” and end with “…”. You can also have multiple YAML documents within one file where each document is separated by “—“. YAML filenames typically end in “.yaml”.

YAML Data Types

YAML data types include numbers, strings, and Boolean. Strings don’t need to be quoted, quotes are only needed when strings contain characters that have meaning in YAML.

YAML Indentation and File Structure

YAML uses indentation to describe hierarchies. Items indented below a label are considered members of that labeled element. There are no specific requirements for indentation amount, you can use a space or a tab. However, the best practice is to use two spaces per indent level.

YAML Maps and Lists

YAML maps can contain multiple key/value pairs and ordered lists. Maps are expresses over multiple lines, beginning with a label key and a colon, followed by members.

Lists are represented in a similar way, but members are preceded with a hyphen (dash) and a space.

Maps and lists can also be written in flow syntax (much like Python).

YAML Comments

Comments in YAML can be inserted anywhere inside the document with the exception of in a long string. All comments are preceded by the hash sign.

Now, let’s convert our JSON document into YAML.