module yuma-ncx {

  namespace "http://netconfcentral.org/ns/yuma-ncx";

  prefix "ncx";

  organization "Netconf Central";

  contact
    "Andy Bierman <andy at netconfcentral.org>";

  description
    "This module contains definitions for Yuma Netconf extensions.

     Some extensions are used to control yangdump translation
     format.  Some are used for CLI parsing in yangcli.

     These elements may be present in appinfo elements,
     used in YANG to XSD translation.";

  revision 2012-01-13 {
    description 
       "Added user-write extension.";
  }

  revision 2011-09-30 {
    description 
       "Added default-parm-equals and sil-delete-children-first
        extensions.";
  }

  revision 2009-12-21 {
    description 
       "Moved secure and very-secure extensions to yuma-nacm.";
  }

  revision 2009-06-12 {
    description 
       "Add sequence-id element for notifications";
  }

  revision 2009-04-10 {
    description 
       "Removed rpc-type extension; use 'nacm:secure' instead";
  }

  revision 2008-08-23 {
    description 
       "Added abstract extension.  Marked all objects as abstract
        so they will not be included in the NETCONF database.";
  }

  revision 2008-08-01 {
    description 
       "Added password, hidden, xsdlist, and root extensions.";
  }

  revision 2008-04-16 {
    description 
       "Added metadata and rpc-type extensions.";
  }

  revision 2008-03-21 {
    description 
       "Added no-duplicates extension.";
  }

  revision 2008-02-21 {
    description 
       "Initial revision.";
  }

  leaf belongs-to {
    description 
       "Contains the module name value for a belongs-to-stmt.
        Will be present in appinfo for a YANG submodule.";
    type string;
    ncx:abstract;
  }

  leaf case-name {
    description 
       "Contains the identifier-str value for a YANG case name.
        Will be present in appinfo for all choice case definitions.";
    type string;
    ncx:abstract;
  }
       
  leaf choice-name {
    description 
       "Contains the identifier-str value for a YANG choice name.
        Will be present in appinfo for all choice object definitions.";
    type string;
    ncx:abstract;
  }

  leaf config {
    description 
       "Contains the value from the config-stmt.
        Will be present in appinfo for top-level objects
        or if config-stmt is present in the object definition.";
    type boolean;
    ncx:abstract;
  }

  leaf contact {
    description 
       "Contains the value from the contact-stmt.
        Will be present in appinfo for the module.
        if defined in the module.";
    type string;
    ncx:abstract;
  }

  leaf default {
    description 
       "Contains the value from the default-stmt.
        Will be present in appinfo for a typedef that includes
        a default-stmt.";
    type string;
    ncx:abstract;
  }

  leaf mandatory {
    description 
       "Contains the value from the mandatory-stmt.
        Will be present in appinfo if mandatory-stmt is 
        present in the object definition.";
    type boolean;
    ncx:abstract;
  }

  leaf min-elements {
    description 
       "Contains the value from the min-elements-stmt.
        Will be present in appinfo for a list or leaf-list
        object, if the min-elements-stmt is present
        in the object definition.";
    type uint32;
    ncx:abstract;
  }

  leaf max-elements {
    description 
       "Contains the value from the max-elements-stmt.
        Will be present in appinfo for a list or leaf-list
        object, if the max-elements-stmt is present
        in the object definition.";
    type union {
      type uint32;
      type enumeration {
        enum unbounded;
      }
    }
    ncx:abstract;
  }

  container must {
    presence "Indicates a must statement is configured.";
    ncx:abstract;

    description 
     "Contains the fields from one must-stmt.  Will be present
      in appinfo for each must-stmt defined within an object.";
   
    leaf xpath {
      description 
       "The xpath statement specifying the system conditions
        that must be true for a valid configuration.";
      type string;
      mandatory true;
    }
   
    leaf description {
      description 
        "Contains the description-stmt value from the must-stmt,
         if present.";
      type string;
    }

    uses reference;

    leaf error-app-tag {
      description 
        "Contains the error-app-tag-stmt value from the must-stmt,
         if present.";
      type string;
    }

    leaf error-message {
      description 
        "Contains the error-message-stmt value from the must-stmt,
         if present.";
      type string;
    }
  }         

  leaf ordered-by {
    description 
       "Contains the value from the ordered-by.
        Will be present in appinfo for all list and leaf-list
        object definitions.";
    type enumeration {
      enum system;
      enum user;
    } 
    ncx:abstract;
  }

  leaf organization {
    description 
       "Contains the value from the organization-stmt.
        Will be present in appinfo if oraganization-stmt is 
        present in the module.";
    type string;
    ncx:abstract;
  }

  leaf path {
    description 
       "Contains the path-stmt Xpath expression value for a leafref.
        Will be present in appinfo for all leafref typedefs, and
        inline type-stmts for leafref leafs and leaf-lists.";
    type string;
    ncx:abstract;
  }

  leaf position {
    description 
       "Contains the position-stmt value for a bit definition.
        Will be present in appinfo for all 'bits' typedefs, and
        inline type-stmts for leafs and leaf-lists.";
    type uint32;
    ncx:abstract;
  }

  grouping reference {
    container reference {
      ncx:abstract;
      presence "Indicates a reference statement is configured.";

      description 
        "Contains information from the reference-stmt.  Will
         be present in appinfo for objects which contain a
         reference-stmt.";

      leaf text {
        description "Value from the reference-stmt.";
        type string;
        mandatory true;
      }

      leaf url {
        description 
          "URL for the specified reference.  Will be present
           if the 'text' field begins with 'RFC xxxx' or 'draft-'";
        type string;
      }
    }
  }

  uses reference;

  container revision {
    ncx:abstract;

    presence "Indicates a revision statement is configured.";
    description 
     "Contains the fields from one revision-stmt.  Will be present
      in appinfo for each revision-stmt defined within the module.";
   
    leaf version {
      description 
        "Contains the date string value from the revision-stmt.";
      type string;
      mandatory true;
      ncx:abstract;
    }
   
    leaf description {
      description 
        "Contains the description-stmt value from the revision-stmt.";
      type string;
      mandatory true;
      ncx:abstract;
    }
  }

  leaf rpc-output {
    description 
       "Contains the XSD type name value for the RPC output data
        for one RPC method.  Will be present in appinfo for 
        all rpc definitions which contain an output-stmt.";
    type string;
    ncx:abstract;
  }

  leaf source {
    description 
       "Contains the complete filespec of the source file used
        for the XSD translation. Will be present in the appinfo
        for the module header.";
    type string;
    ncx:abstract;
  }

  leaf units {
    description 
       "Contains the units-stmt value for a type or leaf.
        Will be present in appinfo for typedefs, and 
        inline type-stmts for leafs and leaf-lists,
        which contain a units-stmt.";
    type string;
    ncx:abstract;
  }

  leaf value {
    description 
       "Contains the value-stmt value for an enum definition.
        Will be present in appinfo for all 'enumeration' 
        typedefs, and inline type-stmts for leafs and leaf-lists.";
    type int32;
    ncx:abstract;
  }


  // Internal objects for anyxml parsing
  // every value node must be assigned an object template
  // even within the anyxml implementation

  anyxml any {
    ncx:hidden;
    ncx:abstract;
  }

  container struct {
     ncx:hidden;
     ncx:abstract;
  }

  leaf string { 
     type string;
     ncx:hidden;
     ncx:abstract;
  }

  leaf empty {
     type empty;
     ncx:hidden;
     ncx:abstract;
  }

  container root {
     ncx:hidden;
     ncx:abstract;
     ncx:root;
  }

  leaf binary { 
     type binary;
     ncx:hidden;
     ncx:abstract;
  }


  // NCX <error-info> extensions

  leaf bad-value {
     description
       "Contains the value that was associated with the error.
        Usually added to 'invalid-value' errors, but may be present
        for other errors as well.";
     type string;
     ncx:abstract;
  }

  leaf error-number {
     description
       "Contains the internal error code associated with the error.
        Added for all error types.";
     type uint32 { range "1 .. max"; }
     ncx:abstract;
  }

  // Netconf Central Extensions

  extension abstract {
    description
      "Used with object definitions to indicate that they
       do not represent CLI or NETCONF configuration database
       data instances.  Instead, the node is simply an object
       identifier, an 'error-info' extension, or some other
       abstract data structure.";
  }

  extension cli {
    description
     "Used within a container definition to indicate it is
      only used as a conceptual container for a set of CLI parameters.
      A top-level container containing this extension will not
      be included in any NETCONF configuration databases.";
  }

  extension default-parm {
    description
     "Used within a CLI container or rpc definition to specify a
      leaf parameter within the CLI container or rpc input
      section, that is used as the default if no parameter name 
      is entered.

      These values must not begin with a dash (-) or 
      double dash (--) sequence or they will be mistaken
      for CLI parameter names.

      This option is somewhat risky because any unrecognized
      parameter without any prefix (- or --) will be tried
      as the default parameter type, instead of catching
      the unknown parameter error.  It can also be useful though, 
      for assigning file name parameters through shell expansion,
      or if there is only one parameter.";
    argument parm {
     yin-element true;
    }
  }

  extension default-parm-equals-ok {
    description
     "Used within a CLI container or rpc definition to specify a
      leaf parameter within the CLI container or rpc input
      section, that is used as the default if no parameter name 
      is entered.

      This can be used in addition to ncx:default-parm to
      allow an equals sign '=' in the default parm string value.

      This option is quite risky because any unrecognized
      parameter without any prefix (- or --) will be tried
      as the default parameter type, instead of catching
      the unknown parameter error.  This includes strings containing
      an equals sign, so an unknown parameter error will never
      be generated.

           rpc foo {
             input {
               ncx:default-parm a;
               ncx:default-parm-equals-ok;
               leaf a { type string; }
               leaf b { type int32; }
             }
           }
               
           yangcli> foo bogus-parm=fred

      This will interpreted as if parameter 'a' were entered:

           yangcli> foo a='bogus-parm=fred'
      ";
  }

  extension hidden {
    description
      "Used to prevent publication of a YANG data object.
       Will be ignored for typedefs and other constructs.
       If present, that node and any sub-nodes will be ignored
       when generating HTML documentation or cYANG output.

       The yangdump -f=copy mode will not be affected by
       this extension. ";
  }

  extension metadata {
    description 
      "Used to define an XML attribute to be associated with a
       data-def-stmt node.  Only optional metadata can be
       defined.  Errors for missing XML attributes (except
       as specified by the YANG language) will not be
       checked automatically.

       The syntax string has the following format:

          [prefix:]typename  attribute-name

       Any YANG typedef of builtin type can be specified as
       the type name, except 'empty'.

       Example from get command in netconf.yang:
          ncx:metadata 'FilterType type';   ";

    argument syntax-string {
      yin-element true;
    }
  }

  extension no-duplicates {
    description 
      "Used to indicate that no duplicate values are allowed
       in an ncx:xsdlist leaf or leaf-list object.";
  }    

  extension password {
    description
      "Used to indicate the data type for the leaf is really
       a password.  Only the encrypted version of the password
       is allowed to be generated in any output.";
  }

  extension root {
    description
      "Used within a container definition to indicate it is
       really a root container for a conceptual NETCONF database,
       instead of just an empty container.  This is needed
       for yuma to correctly process any RPC method
       that contains a 'config' parameter.";
  }

  extension sil-delete-children-first {
    description
      "Used within a container or list definition to indicate
       that the SIL callbacks for descendant nodes should
       be invoked first, when a data node instance of
       the object containing this extension is deleted.

       Normally, the parent node is expected to delete all its
       own sub-structures when the SIL edit callback is
       invoked.  If this extension is present, then any 
       SIL callbacks for any of the child nodes will be 
       invoked first instead.

       If a child node is a list or a container, and
       it also contains an 'ncx:sil-delete-children-first'
       extension, then its children will be checked first.

       The SIL edit callback will not be invoked for leaf,
       leaf-list, or anyxml descendant nodes in this mode.
       They will only will called if their parent node
       is not getting deleted.

         container foo {
           ncx:sil-delete-children-first;
           list foos {
             ncx:sil-delete-children-first;
             key a;
             leaf a { type string; }
             container b {
               list c { ... }
             }
             leaf d { type empty; }
           }
         }

       In this example, assume node /foo gets deleted.
       Then the SIL edit callbacks would be done as follows:

       1) /foo/foos[a='n']/b   (called for row 'n' of /foo/foos)
       2) /foo/foos[a='n']     (called for row 'n' of /foo/foos)
       3) repeat (1,2) until all rows in /foo/foos are deleted
       4) /foo 

     Note that the SIL edit callback is not done for list
     /foo/foos[a='n']/b/c because this extension is
     not present in container '/foo/foos/b'.

     Note that the SIL edit callback is not done for 
     nodes /foo/foos[a='n']/a or /foo/foos[a='n']/d because
     they are leafs.
    ";
  }

  extension xsdlist {
    description
      "Used to indicate the leaf string type is really an
       XSD list, which is a series of whitespace separated
       strings. The type argument represents the data type
       to use for the list members, for validation purposes.

       Allowed to be present within the type sub-section
       for a string.";
    argument type {
      yin-element true;
    }
  }

  extension xpath {
    description
      "Used to indicate that the content of a data type
       is an XPath expression.  This is needed to properly
       evaluate the namespace prefixes within the expression.

       The xpath extension may appear within the type-stmt,
       within a typedef, leaf, or leaf-list.  The builtin
       data type must be 'string', or the 'xpath' extension
       will be ignored.

       All data using the 'instance-identifier' built-in type
       will automatically be processed as an XPath string,
       so the xpath extension is not needed in that case.";
  }

  extension qname {
    description
      "Used to indicate that the content of a data type
       is a Qualified Name.  This is needed to properly
       evaluate the namespace prefix, if used.

       The qname extension may appear within the type-stmt,
       within a typedef, leaf, or leaf-list.  The builtin
       data type must be 'string', or the 'qname' extension
       will be ignored.";
  }

  extension schema-instance {
    description
      "Used to indicate that the typedef or type statement
       for a string data type really identifies a
       special schema-instance node, not a generic string.
       
       A schema-instance value string is an unrestricted YANG
       instance-identifier expression.  All the same rules
       as an instance-identifier apply except:
 
           * predicates for keys are optional;
             The dataRule will apply to all instances
             of any missing key leaf predicate.

      This extension will be ignored unless it is present
      in the type-stmt of a typedef-stmt, leaf-stmt, 
      or leaf-list-stmt, or directly within a leaf-stmt or
      leaf-list-stmt.";
  }

  extension user-write {
    description
      "Used within database configuration data definition
       statements to control user write access to the
       database object containing this statement.

       The 'permitted' argument is a list of operations
       that users are permitted to invoke for the specified node.
       These permissions will over-ride all NACM access control rules,
       even if NACM is disabled.
       
       This extension does not apply to descendant nodes!
       This extension has no effect if config-stmt is false!

       The following values are supported:

         * create : allow users to create instances of the object
         * update : allow users to modify instances of the object
         * delete : allow users to delete instances of the object

       To dis-allow all user access, provide an empty string
       for the 'permitted' parameter (user-write '';)

       To allow only create and delete user access, provide
       the string 'create delete' for the 'permitted' parameter.
       Use this for parameters that cannot be changed once they
       are set.

       Providing all 3 parameters has the same affect as not using
       this extension at all, but can be used anyway.

       leaf user-write {
         description 'equivalent YANG definition';
         type bits {
          bit create;
          bit update;
          bit delete;
        }
        default 'create update delete';
      }

    ";

    argument exceptions {
      yin-element true;
    }
  }

}