Bumping versions by 0.0.1 for next dev cycle

[ttp.git] / ttp-model / src / main / yang / ttp.yang

/*
 * Copyright (c) 2014 Brocade Communications Systems others. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
 * and is available at http://www.eclipse.org/legal/epl-v10.html
 */

module onf-ttp {
  /* Notes:
   *  => Comments that start with "SPEC:" are feedback for the ONF
   *  => Comments that start with "REFINE:" are notes for where we could enhance things
   *  => Comments that start with "TODO:" are places where we *need* to do work
   *
   * High-level TODOs:
   *  => add "mandatory true;" where things are required
   *     - note that this might involve variants of universal TTP properties when some are required
   *  => how to handle the "all", "one_or_more", "zero_or_more", "exactly_one", and "zero_or_one"
   *     meta-member keywords?
   *     - We currently support "all", "one_or_more" and "zero_or_more" directly under
   *       "flow_mod_types" because that is all that was illustrated.
   *     - We currently support "exactly_one" and "zero_or_one" directly under "match_set" and
   *       "instruction_set" because that was all that was illustrated.
   *     - We currently support "exactly_one" and "zero_or_one" for action lists, i.e., actions in
   *       instructions_set, action_set in bucket_type, and actions in packet_out
   *     - In all the above cases, I believe we accept JSON which would not be a valid TTP and
   *       might need to add extra validation. This is true elsewhere as well.
   *
   *     - "all" is only used in one example under "flow_mod_types" in the middle of page 43
   *     - "one_or_more" is never illustrated with an example
   *     - "zero_or_more" sometimes points to an object and sometimes to an array. It seems like it
   *                      should always do one or the other. Only used under "flow_mod_types" in the
   *                      example.
   *     - "exactly_one" examples for "instruction_set" and "match_set"
   *     - "zero_or_one" is only used in "instruction_set" and only to point to a single object;
   *                     never to an array. It seems like it should always point to an array, even
   *                     if it is an array with a single element.
   *
   *     - SPEC: It's really unclear how these work. For example, "instruction_set" usually points
   *             to a list, but at the bottom of page 26 it points to an object with a single
   *             "exactly_one" list. While at the top of page 27, it points to a list which contains
   *             an object with a single "zero_or_more" list.
   *     - SPEC: It's not clear what "optional support" vs. "optional use" meta-member keywords are.
   *
   * High-level SPECs:
   *  => where are (and aren't) universal ttp properties valid?
   *     - everywhere but lists? this seems the most likely.
   */

  namespace "urn:onf:ttp";
  prefix ttp;

  // Not using these because the TTP spec makes it difficult to reuse prior modeling efforts. Maybe
  // we can use it in the future.
  //import openflow-extensible-match {prefix oxm;}
  //import openflow-instruction {prefix ofi;}
  //import openflow-types {prefix oft;}

  revision 2014-07-11 {
    description "ONF TTP schema 2014/07/11";
  }

  grouping name-property {
    description "denotes something that has a name, which is a string";

    leaf name {
      type string;
    }
  }

  grouping opt-tag-property {
    description "denotes strings that represent optional functionality in the TTP";

    leaf opt_tag {
      type string;
    }
  }

  grouping doc-property {
    description "denotes something that has documentation as a list of strings";

    leaf-list doc {
      type string;
    }
  }

  grouping universal-TTP-properties {
    //SPEC: exactly what can have have these?
    description "these properties are applicable to all objects in TTPs";

    uses name-property;
    uses opt-tag-property;
    uses doc-property;
  }


  grouping type-property {
    description "denotes something that has a type identified with a string";

    leaf type {
      type string;
    }
  }

  grouping NDM_metadata-properties {
    description "metadata about an NDM (or TTP)";

    leaf authority {
       type string;
    }

    leaf OF_protocol_version {
       type string;
    }

    leaf version {
       type string;
    }

    uses type-property;
    uses universal-TTP-properties;
  }

  grouping action-properties {
    uses universal-TTP-properties;
    leaf action {
      type string;
      // REFINE: enum ofp_action_type string after "OFPAT_"
    }
    leaf port {
      type string; // REFINE: port number or variable name or reserved port name (enum ofp_port_no
                   //         string after "OFPP_")
    }
    leaf group_id {
      type string; // TODO: or number?
    }
    leaf queue_id {
      type string; // TODO: or number?
    }
    leaf ttl {
      description "MPLS or IP TTL";
      type string;
    }
    leaf ethertype {
      type string; // TODO: or number?
    }
    leaf field {
      type string; // REFINE: enum oxm_ofb_match_fields string after "OFPXMT_OFB_"
    }
    leaf value {
      type string; // REFINE: value for the field being set, e.g., bitmap of the appropriate size,
                   //         or variable name
    }
  }

  grouping action-all-properties{
    uses action-properties;
    list all {
      uses action-properties;
    }
    list one_or_more {
      uses action-properties;
    }
  }

  // possible bug in yangtools? using this works, but pasting it's content where it's used fails
  grouping action-zero-exactly-one-properties {
    uses action-properties;
    list exactly_one {
      uses action-all-properties;
    }
    list zero_or_one {
      uses action-all-properties;
    }

    //TODO: are these two allowed here?
    list zero_or_more {
      uses action-all-properties;
    }
    list one_or_more {
      uses action-all-properties;
    }
  }

  grouping match_set-properties {

    // SPEC: mentions that pre-requisites are assumed even if not listed
    // SPEC: this implies requirement that explicit pre-reqs that mismatch are illegal

    uses universal-TTP-properties;
    leaf field {
      type string; //REFINE: enum oxm_ofb_match_fields string after "OFPXMT_OFB_"
      // type identityref {
      //   base oxm:match-field;
      // }
    }
    leaf match_type { // was "wc_type" in older (pre-spec) TTP
      type enumeration {
        enum exact; // exact match, as if all mask bits = 1 (also default)
        enum mask;  // arbitrary mask field allowed for this field
                    // SPEC: is it clear what happens if no mask present? All 1's?
        enum prefix; // mask must be contiguous ones from MSB of field (like subnet mask)
        enum all_or_exact; // field may be omitted, but exact match if present
      }
    }
    leaf mask { // has 1's where must match. Presence and value must agree with match_type
      type string; // a string representing numbers (dec, hex, etc)
    }
    leaf value {
      type string; // either a variable name or fixed value for the field
      // REFINE: add pattern to say it's either a string or variable?
      // SPEC: would be nice if this was easier to specify in a schema
    }
    leaf const_mask { // mask for specifying value bits that cannot be varied
      type string;
      // SPEC: would be good to have an example! [There is one on the middle of page 24]
    }
    leaf const_value { // value used to specify the value of unvarying bits
      type string;

      // SPEC: seems like const_mask and const_value must come together?
      // SPEC: const_mask and const_value invalid with "exact" or "all_or_exact"?
      // SPEC: const_mask and const_value valid with mask...but prefix? Clarify
    }
  }

  grouping instruction_set-properties {
    uses universal-TTP-properties;
    leaf instruction {
    type string; //REFINE: enum ofp_instruction_type string after "OFPIT_"

    // Perhaps come back to this approach?
    // type identityref {
    //   base oft:instruction-base;
    // }
    }
    leaf table {
      type string; //REFINE: should be the name of a table defined here
    }
    leaf metadata {
      type uint64; //SPEC: is this an integer in JSON or a string storing a 64-bit value?
    }
    leaf metadata_mask {
      type uint64; //SPEC: is this an integer in JSON or a string storing a 64-bit value?
    }
    list actions {
      uses action-zero-exactly-one-properties;
    }
    leaf meter_name {
      type string;
      // SPEC: this belongs in "instruction_set" not in "actions"
    }
  }

  grouping flow_mod-properties {
    uses universal-TTP-properties;
    leaf priority {
      description
        "Must have exactly one of priority or priority_rank. Integer greater than zero, or an
         integer range of the form \"n..m\" where n and m are integers with 0 < n < m.";
      type string; //REFINE: add pattern for integer or integer range

      // TODO: all flow_mod_type entries must select the same one of priority and priority_rank
      // SPEC: how to schema the constraints on priority?
    }
    leaf priority_rank {
      description
        "Must have exactly one of priority or priority_rank. An integer greater than zero
         indicating relative priority of flow_mod_types.";
      type string; // strings that represent numbers

      // SPEC: priority ranks must be unique within flow table?
      // SPEC: priority-rank is incompatible with built-in-flow-mods
      // SPEC: That is, cannot be used in the same flow table (see below)
    }
    list match_set {
      // NOTE: in the ODL version, this *must* be a list (in the spec it can also be a singleton)
      uses match_set-properties;
      list exactly_one {
        uses match_set-properties;
      }
      list zero_or_one {
        uses match_set-properties;
      }
    }
    list instruction_set {
      // NOTE: in the ODL version, this *must* be a list (in the spec it can also be a singleton)
      description "A list of the instructions possible. Can also optionally include lists of
                   other instructions in the \"exactly_one\" and \"zero_or_one\" lists.";
      uses instruction_set-properties;
      list exactly_one {
        uses instruction_set-properties;
      }
      list zero_or_one {
        uses instruction_set-properties;
      }
      // TODO: I think the intention is to be ale to specify multiple entries for exactly_one
      //       as well as zero_or_one, but this gives one list. We could do a list of lists, but
      //       the inner lists wouldn't be anonymous.
      // SPEC: The spec says this is an array, but there are examples where it is not, e.g., the
      //       bottom of page 26.
    }
  }

  grouping table-type-pattern-properties {
    container NDM_metadata {
      uses NDM_metadata-properties;
    }

    list identifiers {
      uses universal-TTP-properties;
      leaf var {
        type string;
      }
      leaf range {
        //REFINE: we can add a regex patter to restrict this
        //REFINE: also make sure range in YANG doesn't do this
        type string;
      }

      leaf id {
        type string;
      }
      leaf type {
        type enumeration {
          enum field;
          enum inst;
          enum action;
          enum error;
        }
      }
      leaf exp_id {
        type string; //TODO: is this a string?
                     //SPEC: not state what this is.
      }
      leaf exp_code {
        type string; //TODO: is this a string?
                     //SPEC: not state what this is.
      }

      //SPEC: should be clearer about Variables vs. Identifiers
    }

    list features {
      uses universal-TTP-properties;
      leaf feature {
        type string;
        //REFINE: can we restrict this more than just a string?
      }
    }

    list table_map { // intentionally not using the "univ TTP props"
      key name;
      leaf name {
        type string;
        mandatory true;
      }
      leaf number {
        type uint8;
        mandatory true;
      }
      //SPEC: you can't do what is there in YANG, maybe put name in the tables in flow_tables?
    }

    container meter_table {
      uses universal-TTP-properties;
      list meter_types {
        uses universal-TTP-properties;
        list bands {
          uses universal-TTP-properties;
          leaf type {
            type enumeration {
              enum DROP;
              enum DSCP_REMARK;
            }
          }
          leaf rate {
            type string;
            //REFINE: use a regex patter?
            //SPEC: make min and max as ints?
          }
          leaf burst {
            type string;
            //REFINE: use a regex patter?
            //SPEC: make min and max as ints?
          }
        }
      }
      list built_in_meters {
        uses universal-TTP-properties;
        leaf meter_id {
          type uint32; //borrowed from OF spec
        }
        leaf type {
          type string;
          //REFINE: should be enum ofp_meter_band_type string after "OFPMBT_"
        }
        list bands {
          leaf rate {
            type uint32;
            //REFINE: right int?
          }
          leaf burst {
            type uint32;
            //REFINE: right int?
          }
        }
      }
    }

    list flow_tables {
      uses universal-TTP-properties;
      list flow_mod_types {
        uses flow_mod-properties;
        list all {
          uses flow_mod-properties;
        }
        list one_or_more {
          uses flow_mod-properties;
        }
        list zero_or_more {
          uses flow_mod-properties;
        }
      }
      list built_in_flow_mods {
         uses flow_mod-properties;

         // SPEC: says "usually are flow_mods that ..."  Usually? Always?

         // built-ins are flow_mods, not just templates like flow_mod_types
         // so the allowed fields are similar
         // can we leverage similarity, or do we need to repeat the fields?
         // as flow-mod-types get more complex, leverage is important

         // SPEC: Only "priority" allowed for built-ins? (rank doesn't work?) (rank doesn't work
         //       because implies "specified later")
         // SPEC: if built-in and flow-mod-types are defined for same table...
         //       and if "priority" is required for built-in, then...
         //       then flow-mod-types in same table must be "priority" (not rank)

         // SPEC: For built-in flow mods, these are not templates (constraints), but actual flow
         //       mods. For flow mod, match type is expressed, not described as such, "match_type"
         //       seems pointless?  Or maybe "prefix"? const_value and const_mask meaningless
      }
      list table_subsets {
        uses universal-TTP-properties; //REFINE: "name" is a required field, used as alias
        leaf-list subset {
           type string;
           //REFINE: should be "MISS", a flow_mod_type name or a "built_in_flow_mod" name
        }
      }
    }

    list group_entry_types {
      uses universal-TTP-properties;
      leaf group_type {
        type string; // REFINE: enum ofp_group_type string after "OFPGT_"
      }
      list bucket_types {
        uses universal-TTP-properties;
        list action_set {
          uses action-zero-exactly-one-properties;
        }
      }
    }

    list packet_out {
      uses universal-TTP-properties;
      list actions {
        uses action-zero-exactly-one-properties;
      }
      //SPEC: no examples in the spec and text is ambiguous
    }

    list parameters {
      uses universal-TTP-properties;
      uses type-property;
      leaf default {
        type union {
          type uint32;
          type string;
          //TODO: is this sufficient?
          //SPEC: this seems ambiguous in the spec
        }
      }
    }

    list flow_paths {
      uses universal-TTP-properties;
      leaf-list path {
        description "a list of strings each of which must be the name of a
                     table from the table_map or the name of a table in square
                     brackets.";
        type string;
        //SPEC: rework, can't have this in YANG
        // We wanted: "flow_paths": ["path": ["table1", ["table2"] ] ]
        // We did: "flow_paths": ["path": ["table1", "[table2]" ] ]
      }
      leaf-list no-path {
        description "a list of strings each of which must be the name of a
                     table from the table_map or the name of a table in square
                     brackets.";
        type string;
      }
      //REFINE: this is really either path or no-path. can we do better in modeling?
      //SPEC: could be clearer about whether you can mix path and no-path and if so, what happens.
    }

    container security {
      uses universal-TTP-properties;
    }
  }

  container opendaylight-ttps {
    container table-type-patterns {
      list table-type-pattern {
        uses table-type-pattern-properties;
      }
    }
    description "The global TTP registry for OpenDaylight";
  }
}