XML and NETCONF XML Management Protocol Conventions Overview

Request and Response Tag Elements

A request tag element is one generated by a client application to request information about a device’s current status or configuration, or to change the configuration. A request tag element corresponds to a CLI operational or configuration command. It can occur only within an <rpc> tag.

A response tag element represents the NETCONF server’s reply to a request tag element and occurs only within an <rpc-reply> tag.

The following example represents an exchange in which a client application emits the <get-interface-information> request tag element with the <extensive/> flag and the NETCONF server returns the <interface-information> response tag element.

Client Application

NETCONF Server

Child Tag Elements of a Request Tag Element

Some request tag elements contain child tag elements. For configuration requests, each child tag element represents a configuration element (hierarchy level or configuration object). For operational requests, each child tag element represents one of the options you provide on the command line when issuing the equivalent CLI command.

Some requests have mandatory child tag elements. To make a request successfully, a client application must emit the mandatory tag elements within the request tag element’s opening and closing tags. If any of the children are themselves container tag elements, the opening tag for each must occur before any of the tag elements it contains, and the closing tag must occur before the opening tag for another tag element at its hierarchy level.

In most cases, the client application can emit children that occur at the same level within a container tag element in any order. The important exception is a configuration element that has an identifier tag element, which distinguishes the configuration element from other elements of its type. The identifier tag element must be the first child tag element in the container tag element. Most frequently, the identifier tag element specifies the name of the configuration element and is called <name>. For more information, see Mapping for Objects That Have an Identifier.

Child Tag Elements of a Response Tag Element

The child tag elements of a response tag element represent the individual data items returned by the NETCONF server for a particular request. The children can be either individual tag elements (empty tags or tag element triples) or container tag elements that enclose their own child tag elements. For some container tag elements, the NETCONF server returns the children in alphabetical order. For other elements, the children appear in the order in which they were created in the configuration.

The set of child tag elements that can occur in a response or within a container tag element is subject to change in later releases of the Junos XML API. Client applications must not rely on the presence or absence of a particular tag element in the NETCONF server’s output, nor on the ordering of child tag elements within a response tag element. For the most robust operation, include logic in the client application that handles the absence of expected tag elements or the presence of unexpected ones as gracefully as possible.

Spaces, Newline Characters, and Other White Space

As dictated by the XML specification, the NETCONF server ignores white space (spaces, tabs, newline characters, and other characters that represent white space) that occurs between tag elements in the tag stream generated by a client application. Client applications can, but do not need to, include white space between tag elements. However, they must not insert white space within an opening or closing tag. If they include white space in the contents of a tag element that they are submitting as a change to the candidate configuration, the NETCONF server preserves the white space in the configuration database.

In its responses, the NETCONF server includes white space between tag elements to enhance the readability of responses that are saved to a file: it uses newline characters to put each tag element on its own line, and spaces to indent child tag elements to the right compared to their parents. A client application can ignore or discard the white space, particularly if it does not store responses for later review by human users. However, it must not depend on the presence or absence of white space in any particular location when parsing the tag stream.

For more information about white space in XML documents, see the XML specification from the World Wide Web Consortium (W3C), Extensible Markup Language (XML) 1.0, at http://www.w3.org/TR/REC-xml/ .

XML Comments

Client applications and the NETCONF server can insert XML comments at any point between tag elements in the tag stream they generate, but not within tag elements. Client applications must handle comments in output from the NETCONF server gracefully but must not depend on their content. Client applications also cannot use comments to convey information to the NETCONF server, because the server automatically discards any comments it receives.

XML comments are enclosed within the strings <!-- and -->, and cannot contain the string -- (two hyphens). For more details about comments, see the XML specification at http://www.w3.org/TR/REC-xml/ .

The following is an example of an XML comment:

Predefined Entity References

By XML convention, there are two contexts in which certain characters cannot appear in their regular form:

• In the string that appears between opening and closing tags (the contents of the tag element)

• In the string value assigned to an attribute of an opening tag

When including a disallowed character in either context, client applications must substitute the equivalent predefined entity reference, which is a string of characters that represents the disallowed character. Because the NETCONF server uses the same predefined entity references in its response tag elements, the client application must be able to convert them to actual characters when processing response tag elements.

Table 1 summarizes the mapping between disallowed characters and predefined entity references for strings that appear between the opening and closing tags of a tag element.

Table 2 summarizes the mapping between disallowed characters and predefined entity references for attribute values.

As an example, suppose that the following string is the value contained by the <condition> tag element:

The <condition> tag element looks like this (it appears on two lines for legibility only):

Similarly, if the value for the <example> tag element’s heading attribute is Peer’s "age" <> 40, the opening tag looks like this: