YANG Module TagsLabN Consulting, L.L.C.chopps@chopps.orgLabN Consulting, L.L.C.lberger@labn.netVolta Networksivandean@gmail.com
This document provides for the association of tags with YANG
modules. The expectation is for such tags to be used to help
classify and organize modules. A method for defining, reading
and writing a modules tags is provided. Tags may be standardized
and assigned during module definition; assigned by
implementations; or dynamically defined and set by users. This
document provides guidance to future model writers and, as such,
this document updates .
The use of tags for classification and organization is fairly
ubiquitous not only within IETF protocols, but in the internet
itself (e.g., #hashtags). One benefit of using tags for
organization over a rigid structure is that it is more flexible
and can more easily adapt over time as technologies evolve. Tags
can be usefully standardized, but they can also serve as a
non-standardized mechanism available for users to define
themselves. This document provides a mechanism to define tags
and associate them with YANG modules in a flexible manner. In
particular, tags may be standardized as well as assigned during
module definition; assigned by implementations; or dynamically
defined and set by users.
This document defines a YANG module
which provides a list of module entries to allow for adding or
removing of tags as well as viewing the set of tags associated
with a module.
This document defines an extension statement to be used to
indicate tags that SHOULD be added by the module implementation
automatically (i.e., outside of configuration).
This document also defines an IANA registry for tag prefixes
as well as a set of globally assigned tags.
provides guidelines for
authors of YANG data models. This section updates .
During this documents progression there were requests for
example uses of module tags. The following are a few example
use cases for tags. This list is certainly not exhaustive.
One example use of tags would be to help filter different
discrete categories of YANG modules supported by a device.
E.g., if modules are suitably tagged, then an XPath query can
be used to list all of the vendor modules supported by a
device.
Tags can also be used to help coordination when multiple
semi-independent clients are interacting with the same
devices. E.g., one management client could mark that some
modules should not be used because they have not been verified
to behave correctly, so that other management clients avoid
querying the data associated with those modules.
Tag classification is useful for users searching module
repositories (e.g. YANG catalog). A query restricted to the
'ietf:routing' module tag could be used to return only the
IETF YANG modules associated with routing. Without tags, a
user would need to know the name of all the IETF routing
protocol YANG modules.
Future management protocol extensions could allow for
filtering queries of configuration or operational state on a
server based on tags. E.g., return all operational state
related to system-management.
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
when, and only when, they appear in all capitals, as shown here.
All tags begin with a prefix indicating who owns their
definition. An IANA registry is used to support standardizing
tag prefixes. Currently 3 prefixes are defined with all others
reserved. No further structure is imposed by this document on
the value following the standard prefix, and the value can
contain any yang type 'string' characters except
carriage-returns, newlines and tabs.
An IETF standard tag is a tag that has the prefix "ietf:". All
IETF standard tags are registered with IANA in a registry
defined later in this document.
A vendor tag is a tag that has the prefix "vendor:". These
tags are defined by the vendor that implements the module, and
are not standardized; however, it is RECOMMENDED that the
vendor include extra identification in the tag to avoid
collisions such as using the enterpise or organization name
follwing the "vendor:" prefix (e.g.,
vendor:example.com:vendor-defined-classifier).
A user tag is any tag that has the prefix "user:". These tags
are defined by the user/administrator and will never be
standardized.
Any tag not starting with the prefix "ietf:", "vendor:" or
"user:" is reserved for future standardization.
Tags can become associated with a module in a number of ways. Tags
may be defined and associated at module design time, at
implementation time, or via user administrative control. As the
main consumer of tags are users, users may also remove any tag, no
matter how the tag became associated with a module.
A module definition can indicate a set of tags to be added by
the module implementer. These design time tags are indicated
using the module-tag extension statement. If the module
definition will be IETF standards track, the tags MUST also be
IETF standard tags (Section 3.1). Thus, new modules can drive
the addition of new standard tags to the IANA registry, and the
IANA registry can serve as a check against duplication.
An implementation MAY include additional tags associated with a
module. These tags may be standard or vendor specific tags.
Tags of any kind can be assigned and removed with using normal
configuration mechanisms.
The tree associated with the "ietf-module-tags" module follows.
The meaning of the symbols can be found in .
It's worth noting that a different YANG module classification
document exists . That
document is classifying modules in only a logical manner and
does not define tagging or any other mechanisms. It divides YANG
modules into 2 categories (service or element) and then into one
of 3 origins: standard, vendor or user. It does provide a good
way to discuss and identify modules in general. This document
defines standard tags to support style
classification.
This section updates .
A module can indicate using module-tag extension statements a
set of tags that are to be automatically associated with it
(i.e., not added through configuration).
The module writer can use existing standard tags, or use new
tags defined in the model definition, as appropriate. For
standardized modules new tags MUST be assigned in the IANA
registry defined below, see
below.
This registry allocates tag prefixes. All YANG module tags SHOULD
begin with one of the prefixes in this registry.
The allocation policy for this registry is Specification Required
.
The initial values for this registry are as follows.
Other SDOs (standard organizations) wishing to standardize their
own set of tags could allocate a top level prefix from this
registry.
This registry allocates prefixes that have the standard prefix
"ietf:". New values should be well considered and not achievable
through a combination of already existing standard tags.
The allocation policy for this registry is IETF Review
.
The initial values for this registry are as follows.
TagDescriptionReferenceietf:rfc8199-elementA module for a network element.ietf:rfc8199-serviceA module for a network service.ietf:rfc8199-standardA module defined by a standards organization.ietf:rfc8199-vendorA module defined by a vendor.ietf:rfc8199-userA module defined by the user.ietf:hardwareA module relating to hardware (e.g., inventory).[This document]ietf:softwareA module relating to software (e.g., installed OS).[This document]ietf:qosA module for managing quality of service.[This document]ietf:protocolA module representing a protocol.[This document]ietf:system-managementA module relating to system management (e.g., a system
management protocol such as syslog, TACAC+, SNMP, netconf, ...).[This document]ietf:network-serviceA module relating to network service (e.g., a network
service protocol such as an NTP server, DNS server, DHCP server, etc).[This document]ietf:oamA module representing Operations, Administration, and
Maintenance (e.g., BFD).[This document]ietf:routingA module related to routing.[This document]ietf:signalingA module representing control plane signaling.[This document]ietf:lmpA module representing a link management protocol.[This document]
Special thanks to Robert Wilton for his help improving the
introduction and providing the example use cases.
The following is a fictional example result from a query of
the module tags list. For the sake of brevity only a few module
results are imagined.