Understanding Junos OS YANG Extensions for Formatting RPC Output

Junos OS natively supports XML for the operation and configuration of devices running Junos OS. The Junos OS infrastructure and CLI communicate using XML. When you issue an operational command in the CLI, the CLI converts the command into XML for processing. After processing, Junos OS returns the output in the form of an XML document, which the CLI converts back into text format for display. Remote client applications also use XML-based data encoding for operational and configuration requests on devices running Junos OS.

The Junos OS Output Definition Language (ODL) defines the transformation of the XML-tagged data into the formatted ASCII output that is displayed when you execute a command in the CLI or request RPC output in text format. The Junos OS ODL extensions module defines YANG extensions for the ODL, which you can include in custom YANG RPCs to translate the XML RPC reply into formatted ASCII output.

The YANG RPC output statement defines output parameters to the RPC operation. Within the RPC output statement, you can include ODL extension statements to customize the RPC’s output. Table 1 outlines the available statements, provides a brief description of each statement’s formatting impact, and specifies the locations where the statement can be defined within the RPC output statement.

You include some ODL extension statements under the leaf statement that defines the data, and you include others within the output container or at various levels within the format statement, which defines the CLI formatting. The placement of a statement within the format statement determines the statement’s scope, which might apply to a single field, all fields in a line, or all fields in all lines of output. Statements that can be defined at any level in the format statement can be included at the top level as a direct child of the format statement, directly under the line statement, or within a field statement.

Note:

Starting in Junos OS Release 17.3, the CLI formatting for a custom RPC is defined within the junos-odl:format extension statement. In earlier releases, the CLI formatting is defined using a container that includes the junos-odl:cli-format statement.

Table 1: Statements in the Junos OS ODL Extensions Module
Statement	Description	Placement Within RPC `output` Statement
`blank-line`	Insert a blank line between each repetition of data when the RPC reply returns the same set of information for multiple entities.	`format` statement (top level)
`capitalize`	Capitalize the first word of a node’s value in an output field.	`format` statement (any level)
`cli-format`	Indicate that the enclosing container defines the CLI formatting for the parent container. The formatting container is not included as a node in the XML RPC reply. This statement is obsolete starting in Junos OS Release 17.3. Use the `format` statement instead.	formatting container (top level)
`colon`	Insert a colon following the node’s label in an output field. This statement is only used in conjunction with the `leading` statement to insert the formal name of the node, as defined by the `formal-name` statement, and a colon before the value of the node in the output field.	`format` statement (any level)
`comma`	Insert a comma after a node’s value in an output field.	`format` statement (any level)
`default-text`	Specify the text to display when the node corresponding to an output field is missing.	`field` statement
`explicit`	Direct the renderer to display a value that is unrelated to the node name or its contents. This statement is used in Junos OS RPCs only and cannot be included in custom RPCs.	–
`field`	Map a leaf node in the output tree to a field in the formatted ASCII output.	`line` statement
`fieldwrap`	Wrap a field’s complete contents to the following line when the current line is wider than the screen. Omitting this statement causes the output to wrap without regard for appropriate word breaks or the prevailing margin.	`field` statement
`float`	Enable the value in a field to move to the left into an empty field. Use this statement to indicate subsequent mutually exclusive values for a set of adjacent fields so that only the leftmost field includes one of these possible values. If the leftmost field is not populated by the first value, a value mapped to a subsequent field that includes the `float` statement can move into the empty field.	`field` statement
`formal-name`	Define the label that precedes a node’s value in an output field whenever the field for that node includes the `leading` statement in the formatting instructions.	`leaf` node
`format`	Define the CLI formatting for the parent container within the RPC `output` statement. Starting in Junos OS Release 17.3, the CLI formatting is defined within the `format` statement rather than within a container that includes the `cli-format` statement.	output container or as a substatement to the `style` statement.
`header`	Define a header row in the CLI output.	`format` statement (top level)
`header-group`	Require that only the first header string as defined by the `header` statement be emitted in the CLI output for that header group.	`format` statement (top level)
`indent`	Indent all lines other than the header row by the specified number of spaces in the CLI output.	`format` statement (top level)
`leading`	Insert a label, which is defined by the `formal-name` statement in the definition of a leaf node, before the node’s value in an output field.	`format` statement (any level)
`line`	Define the group of fields that comprises a single line of output.	`format` statement (top level)
`no-line-break`	Display multiple values on the same line in the case where multiple entities with the same tag names are emitted.	`format` statement (top level)
`picture`	Graphically specify the placement, justification, and width of the columns in a table in the RPC’s formatted ASCII output.	`format` statement (top level)
`space`	Insert a space after the node’s value in an output field. If the `space` statement is used in conjunction with the `comma` statement, the output inserts a comma and then a space after the node’s value, in that order.	`format` statement (any level)
`style`	Define a format, or style, for the RPC output. Use this statement in conjunction with an enumerated input parameter that defines the names for each style. Define this statement with the appropriate style name to specify the CLI formatting for that style.	output container
`template`	Explicitly define the format for an output field, including the output string and the placement of the node’s value within that string. Use `%s` or `%d` to indicate the placement of the node’s string or integer value, respectively, within the output string. If a leaf statement defines both a `template` and a `formal-name` statement, and the corresponding field’s formatting instructions include the `leading` statement, the output displays the text defined for the `formal-name` statement and not the text defined for the `template` statement.	`leaf` node
`truncate`	Truncate a node’s value to fit the field width defined by the `picture` statement if the node’s contents would otherwise exceed the width of the field.	`field` statement
`wordwrap`	Wrap some of the field to the following line when the current line is wider than the screen. This statement should only be used for fields in the rightmost column of a table.	`field` statement

For more information about the structure of YANG RPCs, see Create Custom RPCs in YANG for Devices Running Junos OS.

Release History Table

Release

Description

17.3R1

Understanding Junos OS YANG Extensions for Formatting RPC Output

Related Documentation