module ietf-nmda-compare {

    yang-version 1.1;

    namespace
      "urn:ietf:params:xml:ns:yang:ietf-nmda-compare";

    prefix cmp;

    import ietf-yang-types {
      prefix yang;
      reference
        "RFC 6991: Common YANG Data Types";


    }
    import ietf-datastores {
      prefix ds;
      reference
        "RFC 8342: Network Management Datastore
        Architecture (NMDA)";


    }
    import ietf-yang-patch {
      prefix ypatch;
      reference
        "RFC 8072: YANG Patch Media Type";


    }
    import ietf-netconf {
      prefix nc;
      reference
        "RFC 6241: Network Configuration Protocol (NETCONF)";


    }

    organization
      "IETF NETMOD (Network Modeling) Working Group";

    contact
      "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
     WG List:  <mailto:netmod@ietf.org>

     Author: Alexander Clemm
             <mailto:ludwig@clemm.org>

     Author: Yingzhen Qu
             <mailto:yqu@futurewei.com>

     Author: Jeff Tantsura
             <mailto:jefftant.ietf@gmail.com>

     Author: Andy Bierman
             <mailto:andy@yumaworks.com>";

    description
      "The YANG data model defines a new operation, <compare>, that
     can be used to compare NMDA datastores.

     Copyright (c) 2021 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC 9144; see the
     RFC itself for full legal notices.";

    revision "2021-12-10" {
      description "Initial revision.";
      reference
        "RFC 9144: Comparison of Network Management Datastore
        Architecture (NMDA) Datastores";

    }


    rpc compare {
      description
        "NMDA datastore compare operation.";
      input {
        leaf source {
          type identityref {
            base ds:datastore;
          }
          mandatory true;
          description
            "The source datastore to be compared.";
        }

        leaf target {
          type identityref {
            base ds:datastore;
          }
          mandatory true;
          description
            "The target datastore to be compared.";
        }

        leaf all {
          type empty;
          description
            "When this leaf is provided, all data nodes are compared,
           whether their schema node pertains to both datastores or
           not.  When this leaf is omitted, a prefiltering step is
           automatically applied that excludes data nodes from the
           comparison that can occur in only one datastore but not
           the other.  Specifically, if one of the datastores
           (source or target) contains only configuration data and
           the other datastore is <operational>, data nodes for
           the config that is false are excluded from the
           comparison.";
        }

        leaf report-origin {
          type empty;
          description
            "When this leaf is provided, origin metadata is
           included as part of RPC output.  When this leaf is
           omitted, origin metadata in comparisons that involve
           <operational> is by default omitted.";
        }

        choice filter-spec {
          description
            "Identifies the portions of the datastores to be
               compared.";
          anydata subtree-filter {
            description
              "This parameter identifies the portions of the
             target datastore to retrieve.";
            reference
              "RFC 6241, Section 6.";

          }
          leaf xpath-filter {
            if-feature nc:xpath;
            type yang:xpath1.0;
            description
              "This parameter contains an XPath expression
             identifying the portions of the target
             datastore to retrieve.";
            reference
              "RFC 6991: Common YANG Data Types";

          }
        }  // choice filter-spec
      }

      output {
        choice compare-response {
          description "Comparison results.";
          leaf no-matches {
            type empty;
            description
              "This leaf indicates that the filter did not match
             anything and nothing was compared.";
          }
          container differences {
            description
              "The list of differences, encoded per RFC 8072 with an
             augmentation to include source values where applicable.
             When a datastore node in the source is not present in
             the target, this can be indicated either as a 'delete'
             or as a 'remove' as there is no difference between
             them for the purposes of the comparison.";
            container yang-patch {
              description
                "Represents a conceptual sequence of datastore edits,
called a patch.  Each patch is given a client-assigned
patch identifier.  Each edit MUST be applied
in ascending order, and all edits MUST be applied.
If any errors occur, then the target datastore MUST NOT
be changed by the YANG Patch operation.

It is possible for a datastore constraint violation to occur
due to any node in the datastore, including nodes not
included in the 'edit' list.  Any validation errors MUST
be reported in the reply message.";
              reference
                "RFC 7950, Section 8.3.";

              leaf patch-id {
                type string;
                mandatory true;
                description
                  "An arbitrary string provided by the client to identify
the entire patch.  Error messages returned by the server
that pertain to this patch will be identified by this
'patch-id' value.  A client SHOULD attempt to generate
unique 'patch-id' values to distinguish between
transactions from multiple clients in any audit logs
maintained by the server.";
              }

              leaf comment {
                type string;
                description
                  "An arbitrary string provided by the client to describe
the entire patch.  This value SHOULD be present in any
audit logging records generated by the server for the
patch.";
              }

              list edit {
                key "edit-id";
                ordered-by user;
                description
                  "Represents one edit within the YANG Patch request message.
The 'edit' list is applied in the following manner:

  - The first edit is conceptually applied to a copy
    of the existing target datastore, e.g., the
    running configuration datastore.
  - Each ascending edit is conceptually applied to
    the result of the previous edit(s).
  - After all edits have been successfully processed,
    the result is validated according to YANG constraints.
  - If successful, the server will attempt to apply
    the result to the target datastore.";
                leaf edit-id {
                  type string;
                  description
                    "Arbitrary string index for the edit.
Error messages returned by the server that pertain
to a specific edit will be identified by this value.";
                }

                leaf operation {
                  type enumeration {
                    enum "create" {
                      value 0;
                      description
                        "The target data node is created using the supplied
value, only if it does not already exist.  The
'target' leaf identifies the data node to be
created, not the parent data node.";
                    }
                    enum "delete" {
                      value 1;
                      description
                        "Delete the target node, only if the data resource
currently exists; otherwise, return an error.";
                    }
                    enum "insert" {
                      value 2;
                      description
                        "Insert the supplied value into a user-ordered
list or leaf-list entry.  The target node must
represent a new data resource.  If the 'where'
parameter is set to 'before' or 'after', then
the 'point' parameter identifies the insertion
point for the target node.";
                    }
                    enum "merge" {
                      value 3;
                      description
                        "The supplied value is merged with the target data
node.";
                    }
                    enum "move" {
                      value 4;
                      description
                        "Move the target node.  Reorder a user-ordered
list or leaf-list.  The target node must represent
an existing data resource.  If the 'where' parameter
is set to 'before' or 'after', then the 'point'
parameter identifies the insertion point to move
the target node.";
                    }
                    enum "replace" {
                      value 5;
                      description
                        "The supplied value is used to replace the target
data node.";
                    }
                    enum "remove" {
                      value 6;
                      description
                        "Delete the target node if it currently exists.";
                    }
                  }
                  mandatory true;
                  description
                    "The datastore operation requested for the associated
'edit' entry.";
                }

                leaf target {
                  type target-resource-offset;
                  mandatory true;
                  description
                    "Identifies the target data node for the edit
operation.  If the target has the value '/', then
the target data node is the target resource.
The target node MUST identify a data resource,
not the datastore resource.";
                }

                leaf point {
                  when
                    "(../operation = 'insert' or ../operation = 'move')and (../where = 'before' or ../where = 'after')" {
                    description
                      "This leaf only applies for 'insert' or 'move'
operations, before or after an existing entry.";
                  }
                  type target-resource-offset;
                  description
                    "The absolute URL path for the data node that is being
used as the insertion point or move point for the
target of this 'edit' entry.";
                }

                leaf where {
                  when
                    "../operation = 'insert' or ../operation = 'move'" {
                    description
                      "This leaf only applies for 'insert' or 'move'
operations.";
                  }
                  type enumeration {
                    enum "before" {
                      value 0;
                      description
                        "Insert or move a data node before the data resource
identified by the 'point' parameter.";
                    }
                    enum "after" {
                      value 1;
                      description
                        "Insert or move a data node after the data resource
identified by the 'point' parameter.";
                    }
                    enum "first" {
                      value 2;
                      description
                        "Insert or move a data node so it becomes ordered
as the first entry.";
                    }
                    enum "last" {
                      value 3;
                      description
                        "Insert or move a data node so it becomes ordered
as the last entry.";
                    }
                  }
                  default "last";
                  description
                    "Identifies where a data resource will be inserted
or moved.  YANG only allows these operations for
list and leaf-list data nodes that are
'ordered-by user'.";
                }

                anydata value {
                  when
                    "../operation = 'create' or ../operation = 'merge' or ../operation = 'replace' or ../operation = 'insert'" {
                    description
                      "The anydata 'value' is only used for 'create',
'merge', 'replace', and 'insert' operations.";
                  }
                  description
                    "Value used for this edit operation.  The anydata 'value'
contains the target resource associated with the
'target' leaf.

For example, suppose the target node is a YANG container
named foo:

    container foo {
      leaf a { type string; }
      leaf b { type int32; }
    }

The 'value' node contains one instance of foo:

    <value>
       <foo xmlns='example-foo-namespace'>
	  <a>some value</a>
	  <b>42</b>
       </foo>
    </value>
 ";
                }

                anydata source-value {
                  when
                    "../operation = 'delete'or ../operation = 'merge'or ../operation = 'move'or ../operation = 'replace'or ../operation = 'remove'";
                  description
                    "The anydata 'value' is only used for 'delete',
'move', 'merge', 'replace', and 'remove'
operations.";
                }
              }  // list edit
            }  // container yang-patch
          }  // container differences
        }  // choice compare-response
      }
    }  // rpc compare
  }  // module ietf-nmda-compare