yang-openapi.yang

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

  import ietf-inet-types  { prefix inet; }
  import ietf-yang-types  { prefix yang; }
  import yang-json-schema { prefix json; }
  import yang-meta-types  { prefix meta; }

  organization
    "Corenova Technologies, Inc.";
  contact
    "Peter K. Lee <peter@corenova.com>";
  reference
    "https://openapis.org";

  /*
   * Identities
   */ 
  identity protocol {
    description "describes transfer protocol";
  }
  identity http {
    base protocol;
  }
  identity https {
    base protocol;
  }
  identity ws {
    base protocol;
  }
  identity wss {
    base protocol;
  }
  /*
   * Type definitions
   */
  typedef mimetype {
    type string {
      pattern '^.+\/.+$';
    }
  }
  typedef http-status-code {
    type uint16 {
      range '100..102 | 200..208 | 226 | 300..308 | 400..431 | 500..511';
    }
  }
  typedef http-method {
    type enumeration {
      enum get;
      enum put;
      enum post;
      enum delete;
      enum options;
      enum head;
      enum patch;
    }
  }
  typedef grouping-identifier {
    type string {
      length "1..max";
      pattern '[\w\-]*:?[a-zA-Z_][a-zA-Z0-9\-_.]*';
      pattern '[\w\-]*:?.|..|[^xX].*|.[^mM].*|..[^lL].*';
    }
  }
  /*
   * Groupings
   */
  grouping info {
    description
      "Contains metadata information to describe API.";
    leaf title       { type meta:title; mandatory true; }
    leaf description { type meta:description; }
    leaf version     { type meta:api-version; mandatory true; }
    container contact {
      leaf name { type meta:person-name; }
      leaf url { type inet:uri; }
      leaf email { type meta:email-address; }
    }
    container license {
      leaf name { type meta:license; mandatory true; }
      leaf url  { type inet:uri; }
    }
  }
  grouping parameters-list {
    list parameter {
      key "name";
      leaf name {
        type string;
        mandatory true;
      }
      leaf in {
        type enumeration {
          enum query;
          enum header;
          enum path;
          enum formData;
          enum body;
        }
        mandatory true;
      }
      leaf description {
        type meta:description;
      }
      leaf required {
        type boolean;
        default false;
        description "if ../in = 'path' this must be true";
      }
      uses json:json-datatype;
      container schema {
        when "../in = 'body'";
        uses json:json-schema;
      }
      /* TODO
       * allow-empty-value
       * items
       * collection-format
       * default
       * maximum
       * exclusive-maximum
       * minimum
       * exclusive-minimum
       * max-length
       * min-length
       * pattern
       * max-items
       * min-items
       * unique-items
       * enum
       * multiple-of
       */
    }
  }
  grouping response {
    leaf description {
      type meta:description;
      mandatory true;
    }
    container schema {
      uses json:json-schema;
    }
    list header {
      
    }
    list example {
      key mime;
      leaf mime {
        type mimetype;
        mandatory true;
      }
      container data;
    }
  }
  grouping responses-list {
    list response {
      key code;
      leaf code {
        type http-status-code;
      }
      uses openapi:response;
    }
  }
  grouping operations-list {
    grouping operation {
      leaf-list tags {
        type yang:yang-identifier;
      }
      leaf summary {
        type meta:description {
          length 0..120;
        }
      }
      leaf description {
        type meta:description;
      }
      leaf operationId {
        type string;
      }
      leaf-list consumes {
        type mimetype;
      }
      leaf-list produces {
        type mimetype;
      }
      leaf-list schemes {
        type identityref {
          base protocol;
        }
      }
      leaf deprecated {
        type boolean;
        default false;
      }
      uses openapi:parameters-list;
      uses openapi:responses-list;
      list security {
        key name;
        leaf name;
        // TODO
      }
    }
    list operation {
      //node:hash "..";
      key method;
      leaf method {
        type http-method;
      }
      uses operation;
    }
  }
  grouping paths-list {
    grouping path-item {
      leaf $ref {
        type json:json-schema-ref;
      }
      uses openapi:operations-list;
      uses openapi:parameters-list;
    }
    list path {
      key name;
      leaf name {
        type inet:uri;
      }
      uses path-item;
      min-elements 1;
    }
  }
  grouping definitions-list {
    list definition {
      key name;
      leaf name {
        type openapi:grouping-identifier;
      }
      container schema {
        uses json:json-schema;
      }
    }
  }
  grouping responses-def-list {
    list response {
      key name;
      leaf name {
        type yang:yang-identifier;
      }
      uses openapi:response;
    }
  }
  grouping tags-list {
    list tag {
      key name;
      leaf name {
        type yang:yang-identifier;
      }
      leaf description {
        type meta:description;
      }
      container externalDocs {
        leaf description {
          type meta:description;
        }
        leaf url {
          type inet:uri;
        }
      }
    }
  }
  grouping specification {
    leaf swagger {
      type meta:api-version;
      mandatory true;
      must "current() = '2.0'";
    }
    container info {
      uses openapi:info;
    }
    leaf host {
      type string;
    }
    leaf base-path {
      type inet:uri;
    }
    leaf-list schemes {
      type identityref {
        base protocol;
      }
    }
    leaf-list consumes {
      type mimetype;
      min-elements 1;
    }
    leaf-list produces {
      type mimetype;
      min-elements 1;
    }
    uses openapi:paths-list;
    uses openapi:definitions-list;
    uses openapi:responses-def-list;
    uses openapi:tags-list;
    /* TODO
     * parameters
     * security-definitions
     * security
     * externalDocs
     */

    action serialize {
      description
        "The serialize converts current Swagger/OpenAPI specification object
         into string format based on requested output format.";
      input {
        leaf format {
          type enumeration {
            enum json;
            enum yaml;
          }
          default json;
        }
      }
      output {
        leaf data {
          description "contains the serialized specification data";
          type string;
        }
      }
    }
  }
  /*
   * Configuration data nodes
   */ 
  container info {
    description
      "Contains API description metadata for use during 'transform' output";
    uses openapi:info;
  }

  /*
   * Remote procedures 
   */ 
  rpc transform {
    description
      "The transform accepts YANG module names/locations or pre-existing
       Swagger specification file contents and converts into YANG
       schema-defined Swagger/OpenAPI specification object instance.";
    input {
      choice source {
        case yang-modules {
          leaf-list modules {
            type yang:yang-identifier;
            min-elements 1;
          }
        }
        case swagger-file {
          leaf file {
            type meta:file-name;
            mandatory true;
          }
          leaf format {
            type enumeration {
              enum json;
              enum yaml;
            }
            mandatory true;
          }
          status planned;
        }
      }
      // TODO
      // openapi:example 'application/json' {
      //   value
      //     '{
      //        "modules": [ "yang-openapi" ]
      //      }';
      // }
    }
    output {
      container spec {
        uses openapi:specification;
      }
    }
  }
}