From 2fbf4dea7bc02ccf0adaf742fbb5b24a2765410f Mon Sep 17 00:00:00 2001 From: rwilton Date: Tue, 17 Dec 2019 14:33:29 +0000 Subject: [PATCH] Further worth on the structure based on last weeks discussions and further thoughts --- .../tmp/ietf-schema-selection.yang | 205 +++++++++++------- ...e.yang => ietf-yang-package-instance.yang} | 23 +- .../tmp/ietf-yang-package-types.yang | 32 ++- .../ietf-yang-structure-ext@2019-03-07.yang | 204 +++++++++++++++++ yang-ver-selection/tmp/ietf-yl-packages.yang | 121 ++++++----- 5 files changed, 425 insertions(+), 160 deletions(-) rename yang-ver-selection/tmp/{ietf-yang-package.yang => ietf-yang-package-instance.yang} (82%) create mode 100644 yang-ver-selection/tmp/ietf-yang-structure-ext@2019-03-07.yang diff --git a/yang-ver-selection/tmp/ietf-schema-selection.yang b/yang-ver-selection/tmp/ietf-schema-selection.yang index 1df2480..7a08c27 100644 --- a/yang-ver-selection/tmp/ietf-schema-selection.yang +++ b/yang-ver-selection/tmp/ietf-schema-selection.yang @@ -4,11 +4,6 @@ module ietf-schema-selection { "urn:ietf:params:xml:ns:yang:ietf-schema-selection"; prefix "ver-sel"; - import ietf-inet-types { - prefix inet; - reference "RFC 6991: Common YANG Data Types."; - } - import ietf-datastores { prefix ds; reference @@ -20,11 +15,6 @@ module ietf-schema-selection { reference "RFC 8525: YANG Library"; } - import ietf-yang-package-types { - prefix pkg; - reference "RFC XXXX: YANG Packages"; - } - import ietf-yl-packages { prefix yl-pkg; reference "RFC XXXX: YANG Packages"; @@ -94,11 +84,11 @@ module ietf-schema-selection { allowing them to be configured."; } - feature "custom-package" { + feature "custom-schema" { if-feature "default-schema or secondary-schema"; description "Feature to choose whether clients may configurable custom - packages definitions."; + schema definitions."; } container schema-selection { @@ -111,7 +101,7 @@ module ietf-schema-selection { leaf default-schema { if-feature "default-schema"; type leafref { - path "/schema-selection/selectable-package/identifier"; + path "/schema-selection/schema/name"; require-instance false; } description @@ -121,33 +111,38 @@ module ietf-schema-selection { select a schema during capability negotiation, or if the standard RESTCONF (or NMDA datastore URLs) are used. - If not configured, the operational state must"; + This schema also represents the datastore schema that is used + to persist configuration for all conventional configuration + datastores. + + If not configured, the operational state indicates the + default schema used by this device."; } leaf-list secondary-schema { if-feature "secondary-schema"; type leafref { - path "/schema-selection/selectable-package/identifier"; + path "/schema-selection/schema/name"; require-instance false; } description "Specifies the secondary schema used by this device, that can be selected by clients (either through NETCONF capability - negotiation or RESTCONF schema specific path."; + negotiation or RESTCONF schema specific path)."; } - list custom-package { - if-feature "custom-package"; - key "identifier"; + list custom-schema { + if-feature "custom-schema"; + key "name"; description - "Defines a custom selectable package constructed from - compatible selectable-packages."; + "Defines a custom selectable schema constructed from + compatible schema"; - leaf identifier { - type "pkg:pkg-identifier"; + leaf name { + type "string"; description - "Name of selectable schema, and package instance. + "Name of custom schema. Format can either be the form of a YANG identifer, or '@'. @@ -163,42 +158,43 @@ module ietf-schema-selection { "The description associated with this custom package."; } - leaf-list included-package { + leaf-list included-schema { type leafref { - path "/schema-selection/selectable-package/identifier"; + path "/schema-selection/schema/name"; require-instance false; } + description + "Lists the schema that are combined together into a single + selectable schema (i.e. via a union operation on each + datastore schema package)."; } } - - list selectable-package { + list schema { + key "name"; config false; - key "identifier"; - leaf identifier { - type leafref { - path "/yanglib:yang-library/yl-pkg:package/yl-pkg:identifier"; - } - description - "Identifies a specific revision of a package that MAY be - selected as a schema or as part of a schema. + description + "All available pan-datastore schema that can be used in schema + version selection."; + + leaf name { + type string; - Format is '@', using the package name - and revision label (revision date, revision label or - YANG semver). + description + "Name of the schema. - Packages MUST represent the pan-datastore device schema - (XXX, define + add reference)."; + Do we restrict what is allowed, specifically, do we allow + '@'"; } - + list datastores { key "datastore"; description "The list of datastores supported for this pan-datastore - package, along with the package schema associated with that - datastore."; + selectable-package, along with the package schema + associated with that datastore."; leaf datastore { type ds:datastore-ref; @@ -210,51 +206,108 @@ module ietf-schema-selection { (NMDA)"; } - /* - * XXX, Change identifier for package to be "name@rev-label"? - * - * Note, support for multiple packages per datastore has - * been removed (to keep the model simple). - */ + container package { + description + "YANG package associated with this datastore schema"; + + leaf name { + type leafref { + path "/yanglib:yang-library/yl-pkg:package/yl-pkg:name"; + } + description + "The name of the YANG package this schema relates to"; + } + + leaf version { + type leafref { + path '/yanglib:yang-library/' + + 'yl-pkg:package[yl-pkg:name = current()/../name]/' + + 'yl-pkg:version'; + } + + description + "The version of the YANG package this schema relates + to"; + } + + leaf checksum { + type leafref { + path '/yanglib:yang-library/' + + 'yl-pkg:package[yl-pkg:name = current()/../name]' + + '[yl-pkg:version = current()/../version] ' + + '/yl-pkg:checksum'; + } + + description + "The checksum of the references package."; + } + } + } + + container default-schema-selectable { + if-feature "default-schema"; + presence + "This schema MAY be selected as the device default + schema."; + description + "Defines compatibility if this schema can be selected as a + primary schema."; - leaf package { + leaf-list compatible-secondary-schema { type leafref { - path "/yanglib:yang-library/yl-pkg:package/yl-pkg:identifier"; + path "/schema-selection/schema/name"; } description - "The name of the YANG package this schema relates to"; + "Lists other schema that MAY be selected as secondary + schema is this schema is selected as a default-schema."; } } - leaf-list required-package { - type leafref { - path "/schema-selection/selectable-package/identifier"; - } + container secondary-schema-selectable { + if-feature "secondary-schema"; + presence + "This schema MAY be selected as a secondary schema, + selected for a particular session."; description - "Lists the available-pkgs that MUST be combined with this - package into a single 'selectable schema'. + "Defines compatibility if this schema can be selected as a + secondary schema."; - E.g., a package that represents an incomplete schema would - have to be combined into other packages to represent a - schema."; - } + leaf-list compatible-default-schema { + type leafref { + path "/schema-selection/schema/name"; + } + description + "Lists other schema that MAY be selected as the default + schema at ths same time as this schema is selected as a + secondary-schema."; + } - leaf-list combinable-package { - type leafref { - path "/schema-selection/selectable-package/identifier"; + leaf-list compatible-secondary-schema { + type leafref { + path "/schema-selection/schema/name"; + } + description + "Lists other schema that MAY be selected as other secondary + schema is this schema is selected as a secondary-schema."; } - description - "Lists the available-pkgs that MAY be combined with this - package into a single 'selectable schema'."; } - - leaf-list compatible-package { - type leafref { - path "/schema-selection/selectable-package/identifier"; - } + + container custom-schema-selectable { + if-feature "custom-schema"; + presence + "This schema MAY be selected as part of a custom schema."; description - "Lists the available-pkgs that MAY be selected for other - 'selectable schema' entries."; + "Defines compatibility if this schema can be combined as + part of a custom schema."; + + leaf-list combinable-schema { + type leafref { + path "/schema-selection/schema/name"; + } + description + "Lists the schema that MAY be combined with this + schema into a single custom schema'."; + } } } } diff --git a/yang-ver-selection/tmp/ietf-yang-package.yang b/yang-ver-selection/tmp/ietf-yang-package-instance.yang similarity index 82% rename from yang-ver-selection/tmp/ietf-yang-package.yang rename to yang-ver-selection/tmp/ietf-yang-package-instance.yang index 00be341..179d252 100644 --- a/yang-ver-selection/tmp/ietf-yang-package.yang +++ b/yang-ver-selection/tmp/ietf-yang-package-instance.yang @@ -1,7 +1,7 @@ -module ietf-yang-package { +module ietf-yang-package-instance { yang-version 1.1; - namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package"; - prefix pkg; + namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance"; + prefix pkg-inst; import ietf-yang-revisions { prefix rev; @@ -68,8 +68,8 @@ module ietf-yang-package { // and remove this note. // RFC Ed.: replace XXXX with actual RFC number and remove this // note. - revision 2019-09-11 { - rev:revision-label 0.1.0; + revision 2019-12-16 { + rev:revision-label 0.2.0; description "Initial revision"; reference @@ -81,16 +81,11 @@ module ietf-yang-package { * Top-level structure */ - //sx:structure package { - container package { + sx:structure package { description - "Defines a YANG package. + "Defines a YANG package for use on a YANG instance data + document."; - Intended to be used to specify YANG package within an instance - data document."; - - uses pkg-types:yang-pkg-full-identification-leafs; - uses pkg-types:yang-pkg-common-leafs; - uses pkg-types:yang-pkg-module-leafs; + uses pkg-types:yang-pkg-instance; } } diff --git a/yang-ver-selection/tmp/ietf-yang-package-types.yang b/yang-ver-selection/tmp/ietf-yang-package-types.yang index 13952de..ea8568a 100644 --- a/yang-ver-selection/tmp/ietf-yang-package-types.yang +++ b/yang-ver-selection/tmp/ietf-yang-package-types.yang @@ -61,8 +61,8 @@ module ietf-yang-package-types { // and remove this note. // RFC Ed.: replace XXXX with actual RFC number and remove this // note. - revision 2019-09-11 { - rev:revision-label 0.1.0; + revision 2019-12-16 { + rev:revision-label 0.2.0; description "Initial revision"; reference @@ -209,20 +209,6 @@ module ietf-yang-package-types { description "Allows for a reference for the package"; } - leaf-list location { - type inet:uri; - description - "Contains a URL that represents where an instance data file - for this YANG package can be found. - - This leaf will only be present if there is a URL - available for retrieval of the schema for this entry. - - If multiple locations are provided, then the first location - in the leaf-list MUST be the definitive location that - uniquely identifies this package"; - } - leaf complete { type boolean; default true; @@ -291,7 +277,7 @@ module ietf-yang-package-types { } list included-package { - key "identifer"; + key "name version"; description "An entry in this list represents a package that is included as part of the package definition, or an indirectly included @@ -318,7 +304,7 @@ module ietf-yang-package-types { reference "XXX"; - uses yang-pkg-compact-identification-leaf; + uses yang-pkg-full-identification-leafs; leaf-list replaces-version { type pkg-version; @@ -564,4 +550,14 @@ module ietf-yang-package-types { } } } + + grouping yang-pkg-instance { + description + "Specifies the data node for a full YANG package instance + represented either on a server or a YANG instance data + document."; + uses yang-pkg-full-identification-leafs; + uses yang-pkg-common-leafs; + uses yang-pkg-module-leafs; + } } diff --git a/yang-ver-selection/tmp/ietf-yang-structure-ext@2019-03-07.yang b/yang-ver-selection/tmp/ietf-yang-structure-ext@2019-03-07.yang new file mode 100644 index 0000000..1ca7a89 --- /dev/null +++ b/yang-ver-selection/tmp/ietf-yang-structure-ext@2019-03-07.yang @@ -0,0 +1,204 @@ +module ietf-yang-structure-ext { + yang-version 1.1; + namespace "urn:ietf:params:xml:ns:yang:ietf-yang-structure-ext"; + prefix sx; + + organization + "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; + contact + "WG Web: + WG List: + + Author: Andy Bierman + + + Author: Martin Bjorklund + + + Author: Kent Watsen + "; + description + "This module contains conceptual YANG specifications for defining + abstract data structures. + + 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) 2019 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 Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info)."; + + // RFC Ed.: update the date below with the date of RFC publication + // and remove this note. + + revision 2019-03-07 { + description + "Initial revision."; + // RFC Ed.: replace XXXX with RFC number and remove this note + reference + "RFC XXXX: YANG Structure Extensions."; + } + + extension structure { + argument name { + yin-element true; + } + description + "This extension is used to specify a YANG data structure that + represents conceptual data defined in YANG. It is intended to + describe hierarchical data independent of protocol context or + specific message encoding format. Data definition statements + within a 'structure' extension statement specify the generic + syntax for the specific YANG data structure, whose name is the + argument of the 'structure' extension statement. + + Note that this extension does not define a media-type. A + specification using this extension MUST specify the message + encoding rules, including the content media type, if + applicable. + + The mandatory 'name' parameter value identifies the YANG data + structure that is being defined. + + This extension is only valid as a top-level statement, i.e., + given as a sub-statement to 'module' or 'submodule'. + The sub-statements of this extension MUST follow the ABNF + rules below, where the rules are defined in RFC 7950: + + *must-stmt + [status-stmt] + [description-stmt] + [reference-stmt] + *(typedef-stmt / grouping-stmt) + *data-def-stmt + + A YANG data structure defined with this extension statement is + encoded in the same way as an 'anydata' statement. This means + that the name of the structure is encoded as a 'container', + with the instantiated child statements encoded as child nodes + to this node. + + The module name and namespace value for the YANG module using + the extension statement is assigned to each of the data + definition statements resulting from the YANG data structure. + + The XPath document element is the extension statement itself, + such that the child nodes of the document element are + represented by the data-def-stmt sub-statements within this + extension. This conceptual document is the context for the + following YANG statements: + + - must-stmt + - when-stmt + - path-stmt + - min-elements-stmt + - max-elements-stmt + - mandatory-stmt + - unique-stmt + - ordered-by + - instance-identifier data type + + The following data-def-stmt sub-statements are constrained + when used within a 'structure' extension statement. + + - The list-stmt is not required to have a key-stmt defined. + - The config-stmt is ignored if present. + "; + } + + extension augment-structure { + argument path { + yin-element true; + } + description + "This extension is used to specify an augmentation to YANG data + structure defined with the 'structure' statement. It is + intended to describe hierarchical data independent of protocol + context or specific message encoding format. + + This statement has almost the same structure as the + 'augment-stmt'. Data definition statements within this + statement specify the semantics and generic syntax for the + additional data to be added to the specific YANG data + structure, identified by the 'path' argument. + + The mandatory 'path' parameter value identifies the YANG + conceptual data node that is being augmented, represented as + an absolute-schema-nodeid string, where the first node in the + absolute-schema-nodeid string identifies the YANG data + structure to augment, and the rest of the nodes in the string + identifies the node within the YANG structure to augment. + + This extension is only valid as a top-level statement, i.e., + given as a sub-statement to 'module' or 'submodule'. + + The sub-statements of this extension MUST follow the ABNF + rules below, where the rules are defined in RFC 7950: + + [status-stmt] + [description-stmt] + [reference-stmt] + 1*(data-def-stmt / case-stmt) + + The module name and namespace value for the YANG module using + the extension statement is assigned to instance document data + conforming to the data definition statements within this + extension. + + The XPath document element is the augmented extension + statement itself, such that the child nodes of the document + element are represented by the data-def-stmt sub-statements + within the augmented 'structure' statement. + + The context node of the 'augment-structure' statement is + derived in the same way as the 'augment' statement, as defined + in section 6.4.1 of [RFC7950]. This conceptual node is + considered the context node for the following YANG statements: + + - must-stmt + - when-stmt + - path-stmt + - min-elements-stmt + - max-elements-stmt + - mandatory-stmt + - unique-stmt + - ordered-by + - instance-identifier data type + + The following data-def-stmt sub-statements are constrained + when used within an 'augment-structure' extension statement. + + - The list-stmt is not required to have a key-stmt defined. + - The config-stmt is ignored if present. + + Example: + + module foo { + import ietf-yang-structure-ext { prefix sx; } + + sx:structure foo-data { + container foo-con { } + } + } + + module bar { + import ietf-yang-structure-ext { prefix sx; } + import foo { prefix foo; } + + sx:augment-structure /foo:foo-data/foo:foo-con { + leaf add-leaf1 { type int32; } + leaf add-leaf2 { type string; } + } + } + "; + } +} diff --git a/yang-ver-selection/tmp/ietf-yl-packages.yang b/yang-ver-selection/tmp/ietf-yl-packages.yang index 36323e4..5f81a12 100644 --- a/yang-ver-selection/tmp/ietf-yl-packages.yang +++ b/yang-ver-selection/tmp/ietf-yl-packages.yang @@ -15,7 +15,12 @@ module ietf-yl-packages { import ietf-yang-library { prefix yanglib; - reference "RFC 7895bis: YANG Library"; + reference "RFC 8525: YANG Library"; + } + + import ietf-inet-types { + prefix inet; + reference "RFC 6991: Common YANG Data Types."; } organization @@ -71,67 +76,79 @@ module ietf-yl-packages { augment "/yanglib:yang-library" { description "Add YANG package definitions into YANG library"; - + list package { - key "identifier"; - config "false"; + key "name version"; description - "Defines the packages available on this server."; - - uses pkg-types:yang-pkg-compact-identification-leaf; - uses pkg-types:yang-pkg-common-leafs; - uses pkg-types:yang-pkg-module-leafs; + "YANG package instance"; + + uses pkg-types:yang-pkg-instance; + + leaf-list location { + type inet:uri; + description + "Contains a URL that represents where an instance data file + for this YANG package can be found. + + This leaf will only be present if there is a URL available + for retrieval of the schema for this entry. + + If multiple locations are provided, then the first location + in the leaf-list MUST be the definitive location that + uniquely identifies this package"; + } + + leaf checksum { + type pkg-types:sha-256-hash; + description + "The checksum of the package this schema relates to, + calculated on the 'YANG instance data file' package + definition. + + This leaf MAY be omitted if the referenced package is + locally scoped without an associated checksum."; + } } } augment "/yanglib:yang-library/yanglib:schema" { description "Allow datastore schema to be related to a YANG package"; - + container package { - leaf identifier { - type leafref { - path "/yanglib:yang-library/package/identifier"; - } - description - "The name of the package this schema relates to. - - The referenced package MUST represent a referentially - complete schema"; - } - - leaf checksum { - type pkg-types:sha-256-hash; - description - "The checksum of the package this schema relates to, - calculated on the 'YANG instance data file' package - definition. - - This leaf MAY be omitted if the referenced package is - locally scoped without an associated checksum."; - } - - leaf-list supported-optional-feature { - type pkg-types:scoped-feature; - description - "Lists all optional module features that are also - supported by the server when implementing the package. - - This list SHOULD exclude any features in the - 'mandatory-feature' list for the package, or any included - package. - - The full set of features supported by the server for this - schema is the union of this list and all - 'mandatory-feature' lists for the package and all - included packages. This is equivalent to the information - provided via the 'feature' leaf list in YANG library. - - Features are identified using - ':'"; - } - + leaf name { + type leafref { + path "/yanglib:yang-library/package/name"; + } + description + "The name of the package this schema relates to. + + The referenced package MUST represent a referentially + complete schema"; + } + + leaf version { + type leafref { + path '/yanglib:yang-library/' + + 'package[name = current()/../name]/version'; + } + + description + "The package version number this schema relates to."; + } + + leaf checksum { + type leafref { + path '/yanglib:yang-library/' + + 'package[name = current()/../name]' + + '[version = current()/../version]/checksum'; + } + + description + "The checksum of the referenced package."; + } + description "Describes which package the schema directly relates to, if any.";