JSON, XML and YAML

A RESTCONF payload can be refused for an unknown element when the model is fine and the encoding is not. JSON's type system is object, array, number, string, true, false and null, with no namespace. XML carries namespaces in xmlns attributes. JSON has to put them in the name: RFC 7951 requires a module-qualified member name at the top level and wherever the module changes, and the simple form elsewhere.

In Daveth Pro (Network)7 min video · lab: Automation

By , founder of Daveth · Updated

Opening frame of the video walkthrough of JSON, XML and YAML

Watch this lesson

7 min · Video walkthrough

In Daveth Pro (Network)

The full 7 min walkthrough is in Daveth Pro (Network). See what the plan opens

Upcoming practical lab

Lab C20: Automation

What the lab covers

What this page answers

How are YANG namespaces encoded in JSON?

Under RFC 7951, by qualifying the member name with the module: a namespace-qualified name must be used for top-level members and wherever a node's namespace differs from its parent's, and the simple form everywhere else. Read it in “What RFC 7951 requires”

What data types does JSON support?

A JSON value must be an object, array, number or string, or one of the literals false, null and true. There is no date, binary, comment or namespace type. Read it in “What JSON actually promises”

Why does a RESTCONF URI start with a module name?

The same rule applies to paths: a node defined in a different module from its parent, or whose parent is the datastore, is prefixed with the module name and a colon, as in Cisco-IOS-XE-native:native. Read it in “The same convention, one layer up”

A payload the server will not take

This course's scenario: your RESTCONF request comes back with an error naming an unknown element. You check the YANG module. The node is there, spelled exactly as you spelled it, in the container you put it in. The model is fine. The encoding is not.

You can already read all three formats; that is not what is being tested. What is tested, by the exam and by a strict server, is the belief underneath: that XML and JSON are the same data in different punctuation, and choosing between them is taste. For plain data that is close enough. For YANG-modelled data, which is all the data in this domain, it is false in one specific way.

What JSON actually promises

JavaScript Object Notation (JSON) is a text format for the serialization of structured data. JSON's design goals were for it to be minimal, portable, textual, and a subset of JavaScript.

Minimal is the operative word. What can a value be?

A JSON value MUST be an object, array, number, or string, or one of the following three literal names:
  • false
  • null
  • true

That is the whole type system: object, array, number, string and three literals. No date, no binary, no comment and, the one that matters here, no namespace. Two more commitments worth carrying:

Which sets up the distinction this whole lesson rests on: valid and accepted are two different verdicts, given by two different things. A parser checks the shape. The device checks the meaning. A payload can pass the first with nothing to complain about and be refused by the second, and formatting it neatly changes neither answer.

JSON text exchanged between systems that are not part of a closed ecosystem MUST be encoded using UTF-8 The names within an object SHOULD be unique. When the names within an object are not unique, the behavior of software that receives such an object is unpredictable. Many implementations report the last name/value pair only.

SHOULD, not MUST. Notice many implementations: if a loop emits the same key twice, you have not written an override. You have written something whose result depends on the parser at the far end.

Where XML keeps the namespace

Here is the guide's YANG-Patch body, whole:

The guide's YANG-Patch example, as printed, trailing spaces trimmed.

<yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-patch">
        <patch-id>add-hostname-patch</patch-id>
        <edit>
          <edit-id>edit1</edit-id>
          <operation>create</operation>
          <target>/hostname</target>
          <value>
              <hostname xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">Cat9K-test</hostname>
          </value>
        </edit>
        <edit>
          <edit-id>edit2</edit-id>
          <operation>create</operation>
          <target>/interface/Loopback=1</target>
          <value>
              <interface xmlns="http://cisco.com/ns/yang/Cisco-IOS-XE-native">
              <Loopback>
                <name>1</name>
              </Loopback>
              </interface>
          </value>
        </edit>
</yang-patch>

Look at the xmlns attributes. The one on yang-patch puts the whole document in the IETF YANG-Patch namespace. The ones on hostname and interface switch those elements, and their children, into the native model's namespace. Namespace membership is part of the document itself. The W3C namespaces specification scopes a default declaration from the element that carries it to that element's end tag, minus any inner declaration: declared on an element, inherited below it, changeable at any depth. JSON has no mechanism for that. So when this tree moves into JSON, where does the namespace go?

Where JSON has to put it

Into the name. RFC 7951 defines the JSON encoding of YANG data, and its answer is a naming convention:

Two offices in one company can each keep a field called name, and neither of them is wrong. What tells you whose name you are holding is the office it came from. Drop that and you have a value that is perfectly readable and no longer means anything in particular.

Where the offices stop: you can walk down the corridor and ask which one they meant. A server cannot. It gets one payload, and a member it cannot attribute to a module is a member it will not accept.

the data node identifier is prefixed with the name of the module in which the data node is defined, separated from the data node identifier by the colon character

So hostname from the native model becomes Cisco-IOS-XE-native:hostname. The colon is not a path separator, and the prefix is not an alias you declare somewhere: it is the module's own name, written into the member name whenever it is needed. The guide prints this patch only in XML, so here is its first edit in JSON three ways, rendered by this course. First with no prefixes at all:

The first edit in JSON, no prefixes: this course's rendering.

{
  "yang-patch": {
    "patch-id": "add-hostname-patch",
    "edit": [
      {
        "edit-id": "edit1",
        "operation": "create",
        "target": "/hostname",
        "value": {
          "hostname": "Cat9K-test"
        }
      }
    ]
  }
}

Then with every member qualified:

The first edit in JSON, every member prefixed: this course's rendering.

{
  "ietf-yang-patch:yang-patch": {
    "ietf-yang-patch:patch-id": "add-hostname-patch",
    "ietf-yang-patch:edit": [
      {
        "ietf-yang-patch:edit-id": "edit1",
        "ietf-yang-patch:operation": "create",
        "ietf-yang-patch:target": "/hostname",
        "ietf-yang-patch:value": {
          "Cisco-IOS-XE-native:hostname": "Cat9K-test"
        }
      }
    ]
  }
}

What RFC 7951 requires

Before you read it: you know the qualified form exists and you know it carries the module. Which of those two renderings follows the rule? Commit to an answer. Step 3 of the walk asks the same.

A namespace-qualified member name MUST be used for all members of a top-level JSON object and then also whenever the namespaces of the data node and its parent node are different. In all other cases, the simple form of the member name MUST be used.

Two MUSTs, pointing in opposite directions. Qualify at the top level. Qualify wherever a child comes from a different module than its parent. Everywhere else, qualifying is itself the error. So neither rendering is right: the first misses two prefixes, the second adds six that the rule forbids.

The first edit in JSON, qualified exactly where the rule says: this course's rendering.

{
  "ietf-yang-patch:yang-patch": {
    "patch-id": "add-hostname-patch",
    "edit": [
      {
        "edit-id": "edit1",
        "operation": "create",
        "target": "/hostname",
        "value": {
          "Cisco-IOS-XE-native:hostname": "Cat9K-test"
        }
      }
    ]
  }
}

Look at where the two prefixes landed: on yang-patch and on hostname. Those are exactly the two elements that carried an xmlns in the first edit of the XML. The condition tracks a change of module between a node and its parent, which is what an xmlns expresses by being present on one element and absent below it.

The same convention, one layer up

You have met this rule already without being told it was the same rule. Here is a resource URI from the guide:

https://10.85.116.30/restconf/data/Cisco-IOS-XE-native:native/logging/monitor/severity

Cisco-IOS-XE-native:native at the front, then three plain segments. Why those three and not the first?

If a node in the path is defined in a module other than its parent node or its parent is the datastore, then the module name followed by a colon character

Same convention, same condition, applied to a path instead of a member name. native's parent is the datastore, so it is qualified; logging, monitor and severity are in the same module as their parents, so they are not. Learn the condition once and it answers both questions.