YANG metadata can be defined with the "structure" extension in RFC 8791


  • Like regular YANG data nodes except they are not part of any datastore

  • Used to define abstract data for use within a YANG tool.


The "rc:yang-data" extension defined in RFC 8040 SHOULD NOT be used.
It will continue to be supported in YumaPro. The extension is not deprecated.
Instead the "sx:structure" extension is just preferred over "rc:yang-data".


The "sx:augment-structure" should be used to augment metadata defined with "sx:structure. 
The non-standard use of "augment" supported by YumaPro SHOULD NOT be used.


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"


Existing Grouping

  grouping errors {
    description
      "A grouping that contains a YANG container
       representing the syntax and semantics of a
       YANG Patch errors report within a response message.";

    container errors {

      description
        "Represents an error report returned by the server if
         a request results in an error.";

      list error {
        description
          "An entry containing information about one
           specific error that occurred while processing
           a RESTCONF request.";
        reference "RFC 6241, Section 4.3";

        leaf error-type {
          type enumeration {
            enum transport {
              description "The transport layer";
            }
            enum rpc {
              description "The rpc or notification layer";
            }
            enum protocol {
              description "The protocol operation layer";
            }
            enum application {
              description "The server application layer";
            }
          }
          mandatory true;
          description
            "The protocol layer where the error occurred.";
        }

        leaf error-tag {
          type string;
          mandatory true;
          description
            "The enumerated error tag.";
        }

        leaf error-app-tag {
          type string;
          description
            "The application-specific error tag.";
        }

        leaf error-path {
          type instance-identifier;
          description
            "The YANG instance identifier associated
             with the error node.";
        }

        leaf error-message {
          type string;
          description
            "A message describing the error.";
        }

        anyxml error-info {
           description
             "This anyxml value MUST represent a container with
             zero or more data nodes representing additional
             error information.";
        }
      }
    }
  }

Keep the existing "errors" grouping but move the contents and replace them with a "uses" statement



Modified Grouping +  New Grouping

  grouping errors {
    description
      "A grouping that contains a YANG container
       representing the syntax and semantics of a
       YANG Patch errors report within a response message.";

    container errors {

      description
        "Represents an error report returned by the server if
         a request results in an error.";

      uses errors-contents;
    }
  }


  grouping errors-contents {
    description
      "A grouping that contains YANG data nodes
       representing the syntax and semantics of a
       YANG Patch errors report within a response message.";

      list error {
        description
          "An entry containing information about one
           specific error that occurred while processing
           a RESTCONF request.";
        reference "RFC 6241, Section 4.3";

        leaf error-type {
          type enumeration {
            enum transport {
              description "The transport layer";
            }
            enum rpc {
              description "The rpc or notification layer";
            }
            enum protocol {
              description "The protocol operation layer";
            }
            enum application {
              description "The server application layer";
            }
          }
          mandatory true;
          description
            "The protocol layer where the error occurred.";
        }

        leaf error-tag {
          type string;
          mandatory true;
          description
            "The enumerated error tag.";
        }

        leaf error-app-tag {
          type string;
          description
            "The application-specific error tag.";
        }

        leaf error-path {
          type instance-identifier;
          description
            "The YANG instance identifier associated
             with the error node.";
        }

        leaf error-message {
          type string;
          description
            "A message describing the error.";
        }

        anyxml error-info {
           description
             "This anyxml value MUST represent a container with
             zero or more data nodes representing additional
             error information.";
        }
      }
  }

Step 3: Change the "rc:yang-data" statement to 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 your changes with pyang (if you have it installed)


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

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>