module ietf-sid-file {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file";
  prefix sid;

  import ietf-yang-types {
    prefix yang;
    reference
      "RFC 6991: Common YANG Data Types";
  }
  import ietf-yang-structure-ext {
    prefix sx;
    reference
      "RFC 8791: YANG Data Structure Extensions";
  }

  organization
    "IETF CORE Working Group";

  contact
    "WG Web:   <https://datatracker.ietf.org/wg/core/>

     WG List:  <mailto:core@ietf.org>

     Editor:   Michel Veillette
               <mailto:michel.veillette@trilliant.com>

     Editor:   Andy Bierman
               <mailto:andy@yumaworks.com>

     Editor:   Alexander Pelov
               <mailto:alexander.pelov@imt-atlantique.fr>

     Editor:   Ivaylo Petrov
               <mailto:ivaylopetrov@google.com>";

  description
    "This module defines the structure of the '.sid' files.

     Each '.sid' file contains the mapping between each
     string identifier defined by a YANG module and a
     corresponding numeric value called a YANG SID.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2024 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 9595; see
     the RFC itself for full legal notices.";

  revision 2024-07-31 {
    description
      "Initial revision.";
    reference
      "RFC 9595: YANG Schema Item iDentifier (YANG SID)";
  }

  typedef revision-identifier {
    type string {
      pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}';
    }
    description
      "Represents a date in YYYY-MM-DD format.";
  }

  typedef sid-file-version-identifier {
    type uint32;
    description
      "Represents the version of a '.sid' file.";
  }

  typedef sid {
    type uint64 {
      range "0..9223372036854775807";
    }
    description
      "YANG Schema Item iDentifier.";
    reference
      "RFC 9595: YANG Schema Item iDentifier (YANG SID)";
  }

  typedef schema-node-path {
    type string {
      pattern
        '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' +
        '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*';
    }
    description
      "A schema-node path is an absolute YANG schema-node
       identifier as defined by the YANG ABNF rule
       'absolute-schema-nodeid', except that module names are used
       instead of prefixes.

       This string additionally follows the following rules:

       -  The leftmost (top-level) data node name is always in the
          namespace-qualified form.
       -  Any subsequent schema-node name is in the
          namespace-qualified form if the node is defined in a
          module other than its parent node.  Otherwise, the
          simple form is used.  No predicates are allowed.";
    reference
      "RFC 5234 (STD 68): Augmented BNF for Syntax Specifications:
                          ABNF
       RFC 7950: The YANG 1.1 Data Modeling Language,
                 Section 6.5: Schema Node Identifier";
  }

  sx:structure sid-file {
    uses sid-file-contents;
  }

  grouping sid-file {
    description
      "A grouping that contains a YANG container
       representing the file structure of a '.sid' file.";

    container sid-file {
      description
        "A wrapper container that together with the 'sx:structure'
         extension marks the YANG data structures inside as not
         being intended to be implemented as part of a
         configuration datastore or as an operational state within
         the server.";
      uses sid-file-contents;
    }
  }

  grouping sid-file-contents {
    description
      "A grouping that defines the contents of a container that
       represents the file structure of a '.sid' file.";

    leaf module-name {
      type yang:yang-identifier;
      mandatory true;
      description
        "Name of the YANG module associated with this
         '.sid' file.";
    }

    leaf module-revision {
      type revision-identifier;
      description
        "Revision of the YANG module associated with this '.sid'
         file.
         This leaf is not present if no revision statement is
         defined in the YANG module.";
    }

    leaf sid-file-version {
      type sid-file-version-identifier;
      default 0;
      description
        "Optional leaf that specifies the version number of the
         '.sid' file.  '.sid' files and the version sequence are
         specific to a given YANG module revision.  This number
         starts at zero when there is a new YANG module revision
         and increases monotonically.  This number can distinguish
         updates to the '.sid' file - for instance, as the result
         of new processing or reported errata.";
    }

    leaf sid-file-status {
      type enumeration {
        enum unpublished {
          description
            "This '.sid' file is unpublished (BCP 216) and is
             also called a work-in-progress or workfile.
             This may be when it accompanies an unpublished YANG
             module or when only the '.sid' file itself is
             unpublished.
             The 'item' list MAY contain entries with a status
             value of 'unstable'.";
          reference
            "RFC 8407 (BCP 216): Guidelines for Authors and
                                 Reviewers of Documents Containing
                                 YANG Data Models";
        }
        enum published {
          description
            "This '.sid' file is published.  This status
             applies to '.sid' files for published YANG modules.
             The 'item' list MUST NOT contain entries with a
             status value of 'unstable'.";
        }
      }
      default "published";
      description
        "Optional leaf that specifies the status of the
         '.sid' file.";
    }

    leaf description {
      type string;
      description
        "Free-form meta-information about the generated file.  It
         might include a '.sid' file generation tool and time,
         among other things.";
    }

    list dependency-revision {
      key "module-name";

      description
        "Information about the revision used during the
         '.sid' file generation of each dependency, i.e., each
         YANG module that the YANG module associated with this
         '.sid' file imported.";

      leaf module-name {
        type yang:yang-identifier;
        description
          "YANG module name of this dependency.";
      }
      leaf module-revision {
        type revision-identifier;
        mandatory true;
        description
          "Revision of the YANG module of this dependency.";
      }
    }

    list assignment-range {
      key "entry-point";
      description
        "YANG-SID Range(s) allocated to the YANG module
         identified by 'module-name' and 'module-revision'.

         -  The first available value in the YANG-SID Range is
            'entry-point', and the last available value in the
            range is ('entry-point' + size - 1).
         -  The YANG-SID Ranges specified by all
            'assignment-range' entries MUST NOT overlap.";

      leaf entry-point {
        type sid;
        description
          "Lowest YANG SID available for assignment.";
      }

      leaf size {
        type uint64;
        mandatory true;
        description
          "Number of YANG SIDs available for assignment.";
      }
    }

    list item {
      key "namespace identifier";
      unique "sid";

      description
        "Each entry within this list defines the mapping between
         a YANG item string identifier and a YANG SID.  This list
         MUST include a mapping entry for each YANG item defined
         by the YANG module identified by 'module-name' and
         'module-revision'.";

      leaf status {
        type enumeration {
          enum stable {
            value 0;
            description
              "This SID allocation has been published as the
               stable allocation for the given namespace and
               identifier.";
          }
          enum unstable {
            value 1;
            description
              "This SID allocation has been done during a
               development process; it is not yet stable.";
          }
          enum obsolete {
            value 2;
            description
              "This SID allocation is no longer in use.  It is
               recorded to avoid reallocation of its SID value.";
          }
        }
        default "stable";
        description
          "The status field contains information about the
           stability of the allocation.  For each specific SID
           value, over time it can only transition from
           'unstable' to 'stable', and possibly from 'stable' to
           'obsolete'.";
      }

      leaf namespace {
        type enumeration {
          enum module {
            value 0;
            description
              "All module and submodule names share the same
               global module identifier namespace.";
          }
          enum identity {
            value 1;
            description
              "All identity names defined in a module and its
               submodules share the same identity identifier
               namespace.";
          }
          enum feature {
            value 2;
            description
              "All feature names defined in a module and its
               submodules share the same feature identifier
               namespace.";
          }
          enum data {
            value 3;
            description
              "The namespace for all data nodes, as defined in
               YANG.";
          }
        }
        description
          "Namespace of the YANG item for this mapping entry.";
      }

      leaf identifier {
        type union {
          type yang:yang-identifier;
          type schema-node-path;
        }
        description
          "String identifier of the YANG item for this mapping
           entry.

           If the corresponding 'namespace' field is 'module',
           'feature', or 'identity', then this field MUST
           contain a valid YANG identifier string.

           If the corresponding 'namespace' field is 'data',
           then this field MUST contain a valid schema-node
           path.";
      }

      leaf sid {
        type sid;
        mandatory true;
        description
          "YANG SID assigned to the YANG item for this mapping
           entry.";
      }
    }
  }
}
