Defining Abstract YANG Data

YANG can be used to define abstract data that can be used within server SIL callbacks and system callbacks. This sort of data is commonly used to read/write files containing YANG data or protocol messages defined in YANG.

This functionality replaces the deprecated ncx:abstract extension, because it is based on standards. There are 4 YANG extensions available that can be used to define abstract data structures in YANG modules.

Extension	Source	Module	Description
sx:structure	RFC 8791	ietf-yang-structure-ext.yang	Define a YANG data structure (current)
sx:augment-structure	RFC 8791	ietf-yang-structure-ext.yang	Augment a YANG data structure (current)
rc:yang-data	RFC 8040	ietf-restconf.yang	Define a YANG data structure (deprecated; sx:structure preferred; see How to Convert rc:yang-data to sx:structure)
yd:augment-yang-data	none	yang-data-ext.yang	Augment a YANG data structure (deprecated; sx:augment-structure preferred)

sx:structure

The YANG Data Structures (RFC 8791) includes this YANG extension definition. It is not the same as the RESTCONF version.

The structure name defines the abstract YANG container.
There is no restriction on the child data nodes.

The following example shows how the abstract container test1 would be created with this extension:

module foo {
   // header
   import ietf-yang-structure-ext { prefix sx; }

   sx:structure test1 {
      leaf leaf1 { type string; }
      leaf leaf2 { type int32; }
   }
}

sx:augment-structure

The YANG Data Structures (RFC 8791) includes this YANG extension definition. It is not the same as the YumaPro version.

The structure name defines the abstract YANG container.
The first node in the augment path is the structure name.

The following example shows how the abstract container test1 would be augmented with this extension:

module bar {
   // header
   import ietf-yang-structure-ext { prefix sx; }
   import foo { prefix f; }

   sx:augment-structure "/f:test1"  {
      leaf leaf3 { type uint32; }
      leaf leaf4 { type boolean; }
   }
}

rc:yang-data

The RESTCONF Protocol (RFC 8040) includes the YANG extension definition for yang-data. It is used within ietf-restconf.yang and ietf-yang-patch.yang. Any module can define YANG data structures;

Restrictions:

YANG does not allow multiple top-level nodes with the same name to be defined in the same module.

Make sure that the top-level nodes defined within the yang-data statement do not conflict with other top-level object names.
The data defined within the yang-data statement must be 1 container statement or 1 uses statement where the grouping contains one container.

Note

This extension is deprecated. Use sx:structure instead.

module foo {
   // header
   import ietf-restconf { prefix rc; }

   rc:yang-data test1 {
      container test1 {
        leaf leaf1 { type string; }
        leaf leaf2 { type int32; }
      }
   }
}

How to Convert rc:yang-data to sx:structure

YANG metadata can be defined with the "structure" extension in RFC 8791. These nodes are like regular YANG data nodes except they are not part of any datastore. They can be used to define abstract data for use within a YANG tool.

"rc:yang-data" defined in RFC 8040 is a legacy extension (unofficially deprecated); sx:structure is preferred.

To augment metadata defined with "sx:structure", use "sx:augment-structure".

Important differences between "rc:yang-data" and "sx:structure":

The "rc:yang-data" extension statement does not represent a schema node. Instead, the first schema node is the one child container that is expected as the sub-statements within the "yang-data" extension.
The "sx:structure" extension statement does represent a container schema node, using the parameter value for the "sx:structure" statement. The sub-statements within this statement can define any schema object nodes.

The following 2 statements produce the same schema nodes:

rc:yang-data mydata {
  container mydata {
    leaf myleaf { type string; }
  }
}

sx:structure mydata {
  leaf myleaf { type string; }
}

Example: Convert the RESTCONF "errors" meta-data to sx:structure

Step 1: Change the import statement to use the new YANG module.

Old:

import ietf-restconf { prefix rc; }

New:

import ietf-yang-structure-ext { prefix sx; }

Step 2: Move the child nodes of the "errors" container to a new grouping called "errors-contents". Keep the existing "errors" grouping but move the contents and replace them with a "uses" statement.

Existing grouping:

grouping errors {
  container errors {
    list error {
      // ...
    }
  }
}

Modified grouping and new grouping:

grouping errors {
  container errors {
    uses errors-contents;
  }
}

grouping errors-contents {
  list error {
    // ...
  }
}

Step 3: Replace the "rc:yang-data" statement with a "sx:structure" statement.

Old statement to remove:

rc:yang-data yang-errors {
  uses errors;
}

New statement to add:

sx:structure errors {
  uses errors-contents;
}

Step 4: Verify the changes with pyang.

pyang -f tree --tree-print-structures ietf-restconf.yang

Example output:

module: ietf-restconf

  structure errors:
    +-- error* []
       +-- error-type       enumeration
       +-- error-tag        string
       +-- error-app-tag?   string
       +-- error-path?      instance-identifier
       +-- error-message?   string
       +-- error-info?      <anyxml>

yd:augment-yang-data

The yang-data-ext.yang module defines a YANG extension to allow yang-data nodes to be augmented from a different module.

This is not supported by the RESTCONF standard, just supported in netconfd-pro.
The plain augment statement can be used instead of this extension, but this should be avoided because a standard YANG compiler is not required to support the RESTCONF yang-data extension (so it will not find the augmented node)

Note

This extension is deprecated. Use sx:augment-structure instead.

module bar {
   // header
   import yang-data-ext { prefix yd; }
   import foo { prefix f; }

   yd:augment-yang-data /f:test1 {
      leaf test2 { type string; }
   }
}