[groupbasedpolicy.git] / groupbasedpolicy / src / main / yang / model / policy.yang

/*
 * Copyright (c) 2014 Cisco Systems, Inc. and 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 policy {
    yang-version 1;

    namespace "urn:opendaylight:groupbasedpolicy:policy";
    prefix "gbp-policy";

    import gbp-common {prefix gbp-common;}
    import ietf-inet-types {prefix inet;}

    description
        "This module defines the group-based policy configuration
         model.";

    revision "2014-04-21" {
        description
            "Initial revision.";
    }

    // ***************
    // Label groupings
    // ***************

    grouping label {
        description
            "Labels are used for matching contracts to endpoint groups
             through selectors and targets, as well as determining how
             those contracts will be applied.  See more detailed
             documentation for qualities, conditions, requirements,
             and capabilities.";

        leaf description {
            description "A human-readable description for the label";
            type gbp-common:description;
        }
        leaf inclusion-rule {
            description "Specify how inheritance will work for this label";
            default include;

            type enumeration {
                enum include {
                    description
                        "This label will be included normally in the
                         matching.";
                }
                enum exclude {
                    description
                        "This label will be excluded from the
                         matching.  This allows removing labels that
                         would have otherwise been included because of
                         inheritence rules.";
                }
            }
        }
    }

    grouping quality-base {
        description "Base type for qualities and matcher qualities.";
        leaf name {
            description "A user-visible name for the quality";
            type gbp-common:quality-name;
            mandatory true;
        }
        uses label;
    }

    grouping has-qualities {
        description "An object with a list of qualities";
        list quality {
            description
                "A quality is a label which selects which selects the
                 contracts that are in scope.  Another name for
                 'quality' could be 'attribute' or 'characteristic.'
                 Qualities can be scoped to either a specific contract
                 or to a target within that contract.

                 Contracts are matched to provider and consumer
                 endpoint groups based on the selectors in those
                 endpoint groups that match the quality.

                 Qualities for a contract are inherited from the
                 enclosing contract.

                 Qualities for a target with a given name are
                 inherited both from the enclosing parent contract and
                 from any targets with the same name within the
                 enclosing parent contract.";

            key name;
            uses quality-base;
        }
    }

    grouping requirement-base {
        description "Base type for requirements and matcher requirements.";
        leaf name {
            description "A user-visible name for the requirement";
            type gbp-common:requirement-name;
            mandatory true;
        }
        uses label;
    }

    grouping has-requirements {
        list requirement {
            description
                "A requirement is a label that, along with capabilities,
                 selects how contracts are applied by selecting the
                 applicable subjects within that contract.
                 Requirements represent the fact that an endpoint
                 group requires that some specific functionality be
                 provided to it in order to function.

                 Requirements scoped to an endpoint group (as well as
                 any parent endpoint groups) are inherited by all of
                 that group's contract selectors.  Contract selectors
                 also inherit requirements from any contract selectors
                 in the parent groups that have with matching names.

                 Note that requirements play no role in choosing which
                 contracts apply; they only affect how the contracts
                 that are chosen will be interpreted.";

            key name;
            uses requirement-base;
        }
    }

    grouping capability-base {
        description "Base type for capabilities and matcher capabilities.";
        leaf name {
            description "A user-visible name for the capability";
            type gbp-common:capability-name;
            mandatory true;
        }
        uses label;
    }

    grouping has-capabilities {
        list capability {
            description
                "A capability is a label that, along with requirements,
                 selects how contracts are applied by selecting the
                 applicable subjects within that contract.
                 Capabilities are specific pieces of functionality
                 that can be exposed to other endpoint groups that may
                 meet functional requirements of those endpoint
                 groups.

                 Capabilities scoped to an endpoint group (as well as
                 any parent endpoint groups) are inherited by all of
                 that group's contract selectors.  Contract selectors
                 also inherit capabilities from any contract selectors
                 in the parent groups that have matching names.

                 Note that capabilities play no role in choosing which
                 contracts apply; they only affect how the contracts
                 that are chosen will be interpreted.";

            key "name";
            uses capability-base;
        }
    }

    grouping has-conditions {
        list condition {
            description
                "A condition is a state label for endpoints that can
                 change over time.  As conditions change for certain
                 endpoints, this can affect which subjects are in
                 scope as determined by how the clauses in the
                 contract match against the requirements and
                 capabilities for the endpoint group, and the
                 conditions for the endpoints.";

            key "name";
            leaf name {
                description "A user-visible name for the condition";
                type gbp-common:condition-name;
                mandatory true;
            }
            uses label;
        }
    }

    grouping matcher {
        description
            "A matcher allows matching against labels.  This is used
             to both to match contracts to endpoint groups by matching
             on qualities, and then to match against subjects in the
             contract by matching on requirements, capabilities, and
             conditions.";

        leaf match-type {
            description
                "Specify how many of the labels must match.  If not
                 specified, defaults to 'all'.";
            type enumeration {
                enum all {
                    description
                        "All specified labels must match.";
                }
                enum any {
                    description
                        "At least one of the specified labels must match.";
                }
                enum none {
                    description
                        "None of the specified labels can match.";
                }
            }
        }
    }

    grouping has-condition-matchers {
        description "Objects with condition matchers";
        list condition-matcher {
            description "Match against conditions on endpoints.";

            key "name";
            leaf name {
                description
                    "A name for the condition matcher";
                type gbp-common:condition-matcher-name;
                mandatory true;
            }

            uses matcher;
            uses has-conditions;
        }
    }

    grouping has-endpoint-identification-constraints {
        container endpoint-identification-constraints {
            description
                "Identify endpoints via other attributes other than conditions.
                These can be things such as ip-prefix, vlan, mpls label etc. These
                things are intended to be explicity stated, and should not contain
                references to other objects like endpointsIDs.";
            container l3-endpoint-identification-constraints {
                list prefix-constraint {
                    key ip-prefix;
                    leaf ip-prefix {
                        type inet:ip-prefix;
                    }
                }
            }
        }
    }

    // ************************
    // Network domains grouping
    // ************************

    grouping network-domain {
        description
            "A base type for network domains.  Network domains
             represent some logical grouping or namespace of
             network addresses.";
        leaf name {
            description
                "A human-readable name for the network domain.";
            type gbp-common:name;
        }
        leaf description {
            description
                "A human-readable description for the context.";
            type gbp-common:description;
        }
    }

    grouping forwarding-context {
        description "A base type for forwarding contexts.";
        uses network-domain;
    }

    grouping l2-context {
        description
            "A base type for layer 2 contexts.  Layer 2 contexts
             represent a namespace or logical grouping of layer 2
             addresses.";

        uses forwarding-context;
    }

    // ************************
    // Endpoint group groupings
    // ************************

    grouping relator {
        description
            "Relators allow contracts and endpoint groups to be related
             to each other through a matching process.  See target,
             selection-relator, target-selector, and named-selector
             for more information.";
    }

    grouping selection-relator {
        description
            "Selection relators allow endpoint groups to select
             contracts based on their name or on their qualities.";
        uses relator;

        leaf name {
            description "A name for the selector";
            type gbp-common:selector-name;
            mandatory true;
        }
    }

    grouping consumer-selection-relator {
        description
            "A selection relator for matching contracts to meet
             endpoint group requirements.  See consumer-named-selector
             and consumer-target-selector for more details.";
        uses selection-relator;
        uses has-requirements;
    }

    grouping provider-selection-relator {
        description
            "A selection relator for matching contracts to meet
             endpoint group requirements.  See provider-named-selector
             and provider-named-selector for more details.";
        uses selection-relator;
        uses has-capabilities;
    }

    grouping named-selector {
        description
            "A named selector selects a contract based on the name of
             the contract.  Once the contract is selected, the
             requirements and capabilities are used to select specific
             subjects within that contract.  Named selectors are the
             simplest way to select a contract.  If you need a more
             advanced selector, see the target selector.

             There are two kinds of named selector: consumer named
             selectors and provider named selectors.  Consumer named
             selectors select contracts to meet requirements for the
             endpoint group, and provider named selectors select
             contracts to provide capabilities for the endpoint group.";

        leaf-list contract {
            description "Specific contracts to select.";
            type leafref {
                path "/tenants/tenant/contract/id";
            }
        }
    }

    grouping target-selector {
        description
            "Target selectors select contracts for the endpoint group.
             First, the quality matchers are used to select the
             contracts.  Then, the requirements and capabilities are
             used to select specific subjects within that contract.
             Target selectors are an advanced method for selecting
             contracts; for a simpler method, see the named selector.

             There are two kinds of target selectors: consumer target
             selectors and provider target selectors.  Consumer target
             selectors select contracts to meet requirements for the
             endpoint group, and provider target selectors select
             contracts to provide capabilities to other endpoint
             groups.";

        list quality-matcher {
            description
                "A quality matcher is used in a target selector to
                 match against the qualities in a contract target.
                 You can specify a list of qualities to match against.
                 You can choose whether all qualities listed must
                 match or if a match can be made with any of the
                 qualities.";

            key "name";
            leaf name {
                description "A unique name for the quality matcher";
                type gbp-common:quality-matcher-name;
                mandatory true;
            }

            uses matcher;

            list matcher-quality {
                description
                    "A matcher quality is a quality with a target name
                     field used in quality matchers.  The name of the
                     matcher quality matches against qualities in
                     contract targets.";

                key name;
                uses quality-base;

                leaf target-namespace {
                    description
                        "The name of the target to match.  This allows
                         us to specify that we want to match only
                         qualities scoped to a particular target name.

                         This parameter is optional; if not specified,
                         use an inherited target name if it exists, or
                         match against any target name.";

                    type gbp-common:target-name;
                }
            }
        }
    }

    // ******************
    // Contract groupings
    // ******************

    grouping has-direction {
        description "Object that have a directionality.";
        leaf direction {
            default bidirectional;
            type enumeration {
                enum in {
                    description
                        "Applies to traffic into provider endpoint group";
                }
                enum out {
                    description
                        "Applies to traffic out of provider endpoint group";
                }
                enum bidirectional {
                    description
                        "Applies to traffic in both directions";
                }
            }
        }
    }

    grouping subject-feature-instance {
        description
            "Specific instances of subject features with
             parameters filled in.";
        list parameter-value {
            key "name";
            leaf name {
                type gbp-common:parameter-name;
                mandatory true;
            }
            leaf string-value {
                type string;
            }
            leaf int-value {
                type int64;
            }
            container range-value {
                leaf min {
                    type int64;
                    mandatory true;
                }
                leaf max {
                    type int64;
                    mandatory true;
                }
            }
        }
    }

    grouping has-order {
        description "Objects containing an order parameter";
        leaf order {
            description
                "Specify the ordering of an ordered list
                 of elements.";
            type int32 {
                range "0..max";
            }
        }
    }

    grouping has-classifier-refs {
        description "Objects containing lists of classifier references";

        list classifier-ref {
            key "name";
            description
                "A reference to classifier instance that is used to match
                 traffic traveling between the endpoint groups that
                 form the contract.";

            leaf name {
                description "A unique name for this classifier reference";
                type gbp-common:classifier-name;
                mandatory true;
            }

            leaf instance-name {
                description "The name of the classifier instance";
                type leafref {
                    path "/tenants/tenant/subject-feature-instances/classifier-instance/name";
                }
                mandatory true;
            }

            leaf connection-tracking {
                description
                    "Set up connection tracking for this classifier,
                     which allows the traffic in the reverse direction
                     as connections are established.  This enables
                     rules that allow connections to be initiated only
                     from one side, but once initiated the two sides
                     can communicate for that connection.";

                default normal;
                type enumeration {
                    enum normal {
                        description
                            "Match only traffic matching the classifier
                             strictly";
                    }
                    enum reflexive {
                        description
                            "Additionally match reverse traffic for
                             connections";
                    }
                }
            }

            uses has-direction;
        }
    }

    grouping has-action-refs {
        description "Objects containing lists of action references";

        list action-ref {
            description
                "A reference to an action defined in the subject
                 feature instances for the tenant.";

            key name;
            leaf name {
                description "The name of the action instance";
                type leafref {
                    path "/tenants/tenant/subject-feature-instances/action-instance/name";
                }
                mandatory true;
            }
            uses has-order;
        }
    }

    grouping subject-feature-definition {
        description
            "Base type for subject feature definitions.";

        leaf description {
            description "A user-readable description";
            type gbp-common:description;
        }

        list parameter {
            description
                "A parameter for the feature that can be
                 passed in.";
            key "name";
            leaf name {
                description "A user-visible name for the parameter";
                type gbp-common:parameter-name;
                mandatory true;
            }
            leaf description {
                description
                    "A user-visible description of the meaning of
                     the parameter.";
                type gbp-common:description;
            }
            leaf type {
                description "The type of the parameter";
                default string;
                type enumeration {
                    enum string {
                        description "A string-valued parameter";
                    }
                    enum int {
                        description "An integer-valued parameter";
                    }
                    enum range {
                        description "An integer-range parameter";
                    }
                }
            }
            leaf is-required {
                description "Specify whether the parameter is
                             required for correct operation.";
                default optional;
                type enumeration {
                    enum required {
                        description "The parameter is required";
                    }
                    enum optional {
                        description "The parameter is optional";
                    }
                }
            }
        }

        leaf fallback-behavior {
            description
                "Set the behavior when the underlying infrastructure
                 is unable to support a particular feature.";
            type enumeration {
                enum strict {
                    description
                        "A fatal exception MUST be raised which will
                         render the enclosing subject inactive.";
                }
                enum allow-fallback {
                    description
                        "The infrastructure MAY fall back to using
                         a parent definition of this feature, and
                         instread raise a nonfatal exception.";
                }
            }
        }
    }

    // ********************
    // Global Configuration
    // ********************

    container subject-feature-definitions {
        description
            "Contains configuration for the set of actions and
             classifiers that can be defined for a subject.  This is
             be specific to the capabilities of the underlying
             infrastructure, so the policy model does not define the
             specific semantics.

             The definitions here provide a generic parameterized base
             that can be extended by more specific definitions.
             Extensions must apply all the semantics from their parent
             object as well as any additional semantics.  If the
             underlying infrastructure is unable to support a
             particular feature, it MUST trigger an exception that
             will render the enclosing subject inactive until the
             exception is resolved.  If the fallback-behavior
             parameter is set to 'allow-fallback', the infrastructure
             MAY instead apply the parent subject feature and instead
             raise a nonfatal exception.";

        config true;

        list classifier-definition {
            description
                "A classifier is used to match traffic traveling between
                 the endpoint groups that form the contract.
                 Classifier definitions can define parameters that
                 will need to be filled in when a particular rule
                 references it.";

            key "id";
            uses subject-feature-definition;

            leaf id {
                description "A unique ID for the classifier definition";
                type gbp-common:classifier-definition-id;
                mandatory true;
            }

            leaf name {
                description
                    "A user-visible name for the classifier definition";
                type gbp-common:classifier-name;
            }

            leaf parent {
                description
                    "Parent classifier definition from which we inherit";
                type leafref {
                    path "/subject-feature-definitions/classifier-definition/id";
                }
            }
        }

        list action-definition {
            description
                "A action to be applied to traffic across endpoint
                 groups.  Action definitions can define parameters
                 that will need to be filled in when a particular rule
                 references it.";

            key "id";
            uses subject-feature-definition;

            leaf id {
                description "A unique ID for the action";
                type gbp-common:action-definition-id;
                mandatory true;
            }

            leaf name {
                description "A user-visible name for the action";
                type gbp-common:action-name;
            }

            leaf parent {
                description
                    "Parent action definition from which we inherit";
                type leafref {
                    path "/subject-feature-definitions/action-definition/id";
                }
            }
        }
    }

    // *******
    // Tenants
    // *******

    container tenants {
        description "The list of all known tenants";

        config true;

        list tenant {
            description
                "A tenant is a domain of administration which is
                 logically separate from other tenants.  Most policy
                 is defined in the context of a particular tenant";

            key "id";
            leaf id {
                description "A unique ID for the tenant";
                mandatory true;
                type gbp-common:tenant-id;
            }
            leaf name {
                description "A user-visible name for the tenant";
                type gbp-common:name;
            }
            leaf description {
                description "A user-readable description for the tenant";
                type gbp-common:description;
            }

            // ***************
            // Network domains
            // ***************

            list l3-context {
                description
                    "A layer 3 context represents a namespace for layer 3
                     addresses.  It represents a domain inside which endpoints
                     can communicate with requiring any address translation.";

                key "id";
                uses forwarding-context;

                leaf id {
                    description
                        "A unique ID for the layer 3 context";
                    type gbp-common:l3-context-id;
                }
            }

            list l2-bridge-domain {
                description
                    "A layer 2 bridge domain represents a domain in which
                     layer 2 communication is possible when allowed by policy.";
                key "id";
                uses l2-context;

                leaf id {
                    description "A unique ID for the bridge domain";
                    type gbp-common:l2-bridge-domain-id;
                }

                leaf parent {
                    description
                        "The layer 3 context that contains this bridge domain";
                    type leafref {
                        path "/tenants/tenant/l3-context/id";
                    }
                }
            }

            list l2-flood-domain {
                description
                    "A layer 2 flood domain represents a domain in which
                     layer 2 broadcast and multicast is allowed.";
                key "id";
                uses l2-context;

                leaf id {
                    description "A unique ID for the flood domain";
                    type  gbp-common:l2-flood-domain-id;
                }

                leaf parent {
                    description
                        "The bridge domain that contains this flood domain";
                    type leafref {
                        path "/tenants/tenant/l2-bridge-domain/id";
                    }
                }
            }

            list subnet {
                description
                    "An IP subnet associated with a layer 2 or layer 3
                     context.";
                key "id";
                uses network-domain;

                leaf id {
                    description "A unique ID for the subnet";
                    type gbp-common:subnet-id;
                }

                leaf parent {
                    description
                        "The forwarding context that contains this subnet";
                    type gbp-common:context-id;
                }

                leaf ip-prefix {
                    description "The IP prefix that defines the subnet";
                    type inet:ip-prefix;
                }
                leaf virtual-router-ip {
                    description
                        "IP address to use for a virtual gateway router
                         for the subnet, if desired.";
                    type inet:ip-address;
                }
                list gateways {
                    description
                        "External gateways for subnets we serve, 
                        includes prefixes for static routing";
                    key "gateway";
                    leaf gateway {
                        type inet:ip-address;
                    }
                    list prefixes {
                        key "prefix";
                        leaf prefix {
                            type inet:ip-prefix;
                        }
                    }
                    
                }
            }

            // ***************
            // Endpoint groups
            // ***************

            list endpoint-group {
                description
                    "Endpoint groups are sets of endpoints that share a
                     common set of policies.  Endpoint groups are
                     matched to contracts using selectors, contracts
                     determine which endpoints can communicate and in
                     what way.

                     Endpoint groups have both requirements and
                     capabilities, which represent specific pieces of
                     functionality that are exposed at the boundary of
                     those groups.  Requirements represent some
                     specific functionality that is needed for the
                     endpoints in the endpoint group to function.
                     Correspondingly, capabilities are pieces of
                     functionality that the endpoints in the endpoint
                     group can provide to other endpoints.

                     Contracts can be selected through either a named
                     selector, which matches specific contracts by
                     name, or by a target selector which will match
                     contracts by matching its list of qualities to
                     the list of qualities for a target on the
                     contract.  The contract selectors choose which
                     contracts are in scope.  Note that requirements
                     and capabilities are not used when choosing which
                     contracts are in scope; these are used to
                     determine how a contract will be interpreted.

                     There are two broad category of selectors:
                     provider selectors and consumer selectors.  The
                     provider selectors allow selecting contracts that
                     allow the endpoint group to expose its
                     capabilities.  The consumer selectors allow
                     selecting contracts which allow the endpoint
                     group to meet its requirements.";

                key "id";

                leaf id {
                    mandatory true;
                    type gbp-common:endpoint-group-id;
                }

                leaf name {
                    description
                        "A user-visible name for the endpoint group";
                    type gbp-common:name;
                }
                leaf description {
                    description
                        "A human-readable description for the endpoint
                         group.";
                    type gbp-common:description;
                }
                uses has-requirements;
                uses has-capabilities;

                leaf intra-group-policy {
                    description
                        "Governs how traffic within the endpoint group
                         should be handled.";
                    default allow;
                    type enumeration {
                        enum allow {
                            description
                                "Traffic between two endpoints in the group
                                 is always allowed";
                        }
                        enum require-contract {
                            description
                                "Traffic between two endpoints in the group
                                 is allowed only when a contract exists to
                                 allow it explicitly";
                        }
                    }
                }

                list consumer-named-selector {
                    description
                        "Consumer named selectors are named selectors
                         that select contracts to meet the
                         requirements of the endpoint group.

                         The consumer named selector selects a
                         contract based on the name of the contract.
                         Once the contract is selected, the
                         requirements are used to select specific
                         subjects within that contract.";

                    key "name";
                    uses named-selector;
                    uses consumer-selection-relator;
                }

                list provider-named-selector {
                    description
                        "Provider named selectors are named selectors
                         that select contracts to provide capabilties
                         to other endpoint group.

                         The provider named selector selects a
                         contract based on the name of the contract.
                         Once the contract is selected, the capabilies
                         are used to select specific subjects within
                         that contract.";

                    key "name";
                    uses named-selector;
                    uses provider-selection-relator;
                }

                list consumer-target-selector {
                    description
                        "Consumer target selectors are target selectors
                         that select contracts to meet the requirements
                         of the endpoint group.

                         The consumer target selector selects a
                         contract using the quality matchers to match
                         against the qualities specified on the
                         contract targets.  Once the contract is
                         selected, the requirements are used to select
                         specific subjects within that contract.";

                    key "name";
                    uses target-selector;
                    uses consumer-selection-relator;
                }

                list provider-target-selector {
                    description
                        "Provider target selectors are target selectors
                         that select contracts to provide capabilties
                         to other endpoint group.

                         The provider target selector selects a
                         contract using the quality matchers to match
                         against the qualities specified on the
                         contract targets.  Once the contract is
                         selected, the capabilities are used to select
                         specific subjects within that contract.";

                    key "name";
                    uses target-selector;
                    uses provider-selection-relator;
                }

                leaf network-domain {
                    description
                        "The network domain associated with this endpoint
                         group.  The network domain controls which endpoints
                         are addressible by the endpoints in the group.";
                    type gbp-common:network-domain-id;
                }

                leaf parent {
                    description
                        "Parent endpoint group from which we inherit";

                    type leafref {
                        path "/tenants/tenant/endpoint-group/id";
                    }
                }
            }

            list external-implicit-group {
                description
                    ".";

                key "id";

                leaf id {
                    mandatory true;
                    type gbp-common:endpoint-group-id;
                }
                // Fields to be determined and completed before Code Freeze

            }
            // *************************
            // Subject feature instances
            // *************************

            container subject-feature-instances {
                description
                    "Contains instances of subject features.  Subject
                     feature instances reference a subject feature
                     definition but fill in the required parameters so
                     that they can be easily references elsewhere.";

                list classifier-instance {
                    description "XXX";

                    key "name";
                    leaf name {
                        description "A name for the classifier instance";
                        type gbp-common:classifier-name;
                        mandatory true;
                    }
                    leaf classifier-definition-id {
                        type leafref {
                            path "/subject-feature-definitions/classifier-definition/id";
                        }
                    }
                    uses subject-feature-instance;
                }

                list action-instance {
                    description "XXX";

                    key "name";
                    leaf name {
                        description "A name for the action instance";
                        type gbp-common:action-name;
                        mandatory true;
                    }
                    leaf action-definition-id {
                        type leafref {
                            path "/subject-feature-definitions/action-definition/id";
                        }
                    }
                    uses subject-feature-instance;
                }
            }

            // *********
            // Contracts
            // *********

            list contract {
                description
                    "Contracts contain a set of subjects that describe
                     the communication allowed between endpoints in
                     endpoint groups.  Contracts are matched to endpoint
                     groups by selectors.";

                key "id";
                leaf id {
                    description "A unique ID for the contract";
                    type gbp-common:contract-id;
                    mandatory true;
                }

                leaf description {
                    description
                        "A human-readable description for the contract.";
                    type gbp-common:description;
                }

                // *******
                // Relator
                // *******

                uses has-qualities;

                list target {
                    description
                        "Targets on a contract allow grouping sets of qualities
                         together, as well as providing a namespace for
                         the qualities that are matched.";

                    key "name";
                    leaf name {
                        description
                            "The name for this target.  This can also be used
                             by quality matchers as a namespace for qualities.";
                        type gbp-common:target-name;
                        mandatory true;
                    }

                    uses relator;
                    uses has-qualities;
                }

                // ********************
                // Clauses and subjects
                // ********************

                list subject {
                    description
                        "Subjects define rules to allow traffic to flow
                         between endpoints in different endpoint
                         groups.  No communication is allowed unless a
                         subject allows that communication.

                         After a contract has been selected, clauses
                         in that contract match against the
                         requirements, capabilities, and conditions
                         that apply to the endpoints or endpoint
                         groups that are participating in the
                         contract.  Clauses that match each point to a
                         subject which then becomes active.

                         An active subject can then apply its rules to
                         the traffic between the endpoints.";

                    key "name";
                    leaf name {
                        description "A name for the subject";
                        type gbp-common:subject-name;
                        mandatory true;
                    }

                    list rule {
                        description
                            "A rule is applied to traffic between
                             endpoints in different endpoint groups.
                             Rules match against the traffic using
                             classifiers, and then apply actions to
                             the traffic for matching rules.

                             Rules are applied in order according to
                             their order parameter.  Only the first
                             matching rule will apply.  When multiple
                             subjects are active, the order on each
                             subject will determine which subjects are
                             applied first, and all their rules will
                             take effect before the rules of any
                             subjects with a higher order value.  When
                             subjects have the same order value, then
                             they will apply in lexicographic order by
                             subject name.";

                        key "name";
                        leaf name {
                            description "A name for the rule";
                            type gbp-common:rule-name;
                            mandatory true;
                        }

                        uses has-classifier-refs;
                        uses has-action-refs;
                        uses has-order;
                    }

                    uses has-order;
                }

                list clause {
                    description
                        "Clauses are used to determine which subjects are
                         active once a contract is selected using the
                         contract selectors.

                         Clauses are activated by matching against
                         requirements on the consumer endpoint group,
                         capabilities on the provider endpoint group, and
                         conditions on the individual endpoints in the
                         endpoint group.";
                    key "name";
                    leaf name {
                        type gbp-common:clause-name;
                        mandatory true;
                    }
                    // ********
                    // Matchers
                    // ********

                    container consumer-matchers {
                        description
                            "Matchers that apply to the consumer endpoint
                             group.";

                        // GIC mutually OR'd within role
                        choice group-identification-constraints {
                            description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";

                            case group-name-constraint-case {
                                list group-name-constraint {
                                    key endpoint-group-name;
                                    leaf endpoint-group-name {
                                        type gbp-common:name;
                                    }
                                }
                            }
                            case group-requirement-constraint-case {
                                list requirement-matcher {
                                    description
                                        "Match against requirements in the consumer
                                         endpoint group.";

                                    key "name";
                                    leaf name {
                                        description
                                            "A name for the requirement matcher";
                                        type gbp-common:requirement-matcher-name;
                                        mandatory true;
                                    }

                                    uses matcher;
                                    list matcher-requirement {
                                        description
                                            "A matcher requirement is a
                                             requirement with a selector name
                                             field used in requirement
                                             matchers.  The name of the
                                             matcher requirement matches
                                             against requirements in endpoint
                                             groups.";

                                        key name;
                                        uses requirement-base;

                                        leaf selector-namespace {
                                            description
                                                "The name of the selector to
                                                 match.  This allows us to
                                                 specify that we want to match
                                                 only requirements scoped to a
                                                 particular selector name.

                                                 This parameter is optional;
                                                 if not specified, use an
                                                 inherited selector namespace
                                                 if it exists, or match
                                                 against any selector name.";

                                            type gbp-common:selector-name;
                                        }
                                    }
                                }
                            }

                            case group-any-case {
                                container group-any {

                                    description
                                        "A presence container stating that, if this exists,
                                        the role matcher will match on any group.";
                                    presence "This matches any group";
                                }
                            }
                        }



                        uses has-condition-matchers;

                        uses has-endpoint-identification-constraints;
                    }

                    container provider-matchers {
                        description
                            "Matchers that apply to the provider endpoint
                             group";

                        // GIC mutually OR'd within role
                        choice group-identification-constraints {
                            description "Returns Groups which match, MUTALLY OR within role. Must be Either/Or";

                            case group-name-constraint-case {
                                list group-name-constraint {
                                    key endpoint-group-name;
                                    leaf endpoint-group-name {
                                        type gbp-common:name;
                                    }
                                }
                            }
                            case group-capability-constraint-case {
                                list capability-matcher {
                                    description
                                        "Match against capabilities in the provider
                                         endpoint group.";

                                    key "name";
                                    leaf name {
                                        description
                                            "A name for the capability matcher";
                                        type gbp-common:capability-matcher-name;
                                        mandatory true;
                                    }

                                    uses matcher;

                                    list matcher-capability {
                                        description
                                            "A matcher capability is a
                                             capability with a selector
                                             name field used in capability
                                             mat  chers.  The name of the
                                             matcher capability matches
                                             against capabilities in
                                             endpoint groups.";

                                        key name;
                                        uses capability-base;

                                        leaf selector-namespace {
                                            description
                                                "The name of the selector to
                                                 match.  This allows us to
                                                 specify that we want to match
                                                 only capabilities scoped to a
                                                 particular selector name.

                                                 This parameter is optional;
                                                 if not specified, use an
                                                 inherited selector namespace
                                                 if it exists, or match
                                                 against any selector name.";

                                            type gbp-common:selector-name;
                                        }
                                    }
                                }
                            }
                            case group-any-case {
                                container group-any {
                                    presence "any";
                                }
                            }
                        }

                        uses has-condition-matchers;

                        uses has-endpoint-identification-constraints;
                    }

                    container any-matchers {
                        description
                            "Matchers that apply to either provider endpoint group or consumer endpoint group.";
                        // TODO fill this out, may need additional groupings so as to not confuse capability or requirement.
                   }

                    // ******************
                    // Subject References
                    // ******************

                    leaf-list subject-refs {
                        description
                            "The subjects that will be activated if this
                             clause matches.";

                        type leafref {
                            path "/tenants/tenant/contract/subject/name";
                        }
                    }
                }

                // ***********
                // Inheritance
                // ***********

                leaf parent {
                    description "Parent contract from which we inherit";

                    type leafref {
                        path "/tenants/tenant/contract/id";
                    }
                }
            }

            list contract-ref {
                description
                    "Contract references allow forming contracts
                     between endpoint groups in different tenants.
                     Once the contract reference is created, it is
                     then possible to match against the contract using
                     selectors as though it were a local tenant.

                     Endpoint groups in the local tenant can serve
                     only as consumers of the contract.  Once the
                     contract is matched, consumer matchers will apply
                     to requirements and conditions in the local
                     tenant, and provider matchers will apply against
                     capabilities and conditions in the referenced
                     tenant.";

                key contract-id;

                leaf tenant-id {
                    description
                        "The tenant ID of the tenant containing the
                         contract.";
                    type leafref {
                        path "/tenants/tenant/id";
                    }
                }
                leaf contract-id {
                    description "The contract ID of the contract.";

                    type leafref {
                        path "/tenants/tenant/contract/id";
                    }
                }
            }
        }
    }
}