One document matched: draft-ietf-netmod-yang-usage-08.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3688 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml'>
<!ENTITY rfc3986 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY rfc4181 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4181.xml'>
<!ENTITY rfc4741 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4741.xml'>
<!ENTITY rfc5226 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml'>
<!ENTITY rfc5378 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5378.xml'>
<!ENTITY xpathspec PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xpath-19991116.xml'>
<!ENTITY yangspec PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netmod-yang.xml'>
<!ENTITY yangtypes PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netmod-yang-types.xml'>
]>
<rfc category="info"
docName="draft-ietf-netmod-yang-usage-08"
ipr="trust200811">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes"?>
<?rfc comments="no" ?>
<?rfc inline="no" ?>
<?rfc editing="no" ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="no" ?>
<?rfc compact="no"?>
<?rfc iprnotified="no"?>
<front>
<title abbrev="Guidelines for YANG Documents">
Guidelines for Authors and Reviewers of YANG Data Model Documents
</title>
<author fullname="Andy Bierman" initials="A.B."
surname="Bierman">
<organization>InterWorking Labs</organization>
<address>
<email>andyb@iwl.com</email>
</address>
</author>
<date />
<area>Management</area>
<workgroup>Internet Engineering Task Force</workgroup>
<keyword>NETMOD</keyword>
<keyword>NETCONF</keyword>
<keyword>XML</keyword>
<keyword>YANG</keyword>
<abstract>
<t>
This memo provides guidelines for authors and reviewers
of standards track specifications containing YANG
data model modules. Applicable
portions may be used as a basis for reviews of other
YANG data model documents. Recommendations and
procedures are defined, which are intended to
increase interoperability and usability
of NETCONF implementations which utilize
YANG data model modules.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
The standardization of network configuration interfaces for use
with the <xref target="RFC4741">NETCONF</xref> protocol
requires a modular set of data models, which can be reused
and extended over time.
</t>
<t>
This document defines a set of usage guidelines for
standards track documents containing
<xref target="I-D.ietf-netmod-yang">
YANG</xref> data models. It is similar to
the SMIv2 usage guidelines specification
<xref target="RFC4181"/> in intent and structure.
However, since that document was written a decade after
SMIv2 modules had been in use, it was published as a
'best current practice' (BCP). This document is
not a BCP, but rather an informational reference,
intended to promote consistency in
documents containing YANG modules.
</t>
<t>
Many YANG constructs are defined as optional to use, such as
the description statement. However, in order to
maximize interoperability of NETCONF implementations
utilizing YANG data models, it is desirable to
define a set of usage guidelines which may require
a higher level of compliance than the minimum level
defined in the YANG specification.
</t>
<t>
In addition, YANG allows constructs such as infinite length
identifiers and string values, or top-level mandatory nodes,
that a compliant server is not required to support.
Only constructs which all servers are required to support
can be used in IETF YANG modules.
</t>
<t>
This document defines usage guidelines related to
the NETCONF operations layer, and NETCONF
content layer, as defined in <xref target="RFC4741" />.
These guidelines are intended to be used by authors and
reviewers to improve the readability
and interoperability of published YANG data models.
</t>
</section>
<section title="Terminology">
<section title="Requirements Notation">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in <xref target="RFC2119"/>.
</t>
<t>
RFC 2119 language is used here to express the views of the NETMOD
working group regarding content for YANG modules. YANG modules complying
with this document will treat the RFC 2119 terminology as if it were
describing best current practices.
</t>
</section>
<section title="NETCONF Terms">
<t>
The following terms are defined in <xref target="RFC4741"/>
and are not redefined here:
<list style="symbols">
<t>capabilities</t>
<t>client</t>
<t>operation</t>
<t>server</t>
</list>
</t>
</section>
<section title="YANG Terms">
<t>
The following terms are defined in <xref target="I-D.ietf-netmod-yang"/>
and are not redefined here:
<list style="symbols">
<t>data node</t>
<t>module</t>
<t>namespace</t>
<t>submodule</t>
<t>version</t>
</list>
</t>
<t>
Note that the term 'module' may be used as a generic term for a YANG module or submodule.
When describing properties which are specific to submodules,
the term 'submodule' is used instead.
</t>
</section>
<section title="Terms">
<t>
The following terms are used throughout this document:
<list style="hanging">
<t hangText="published:">
A stable release of a module or submodule, usually contained in an RFC.
</t>
<t hangText="unpublished:">
An unstable release of a module or submodule, usually contained in
an Internet-Draft.
</t>
</list>
</t>
</section>
</section>
<section title="General Documentation Guidelines" anchor="GenGuidelines">
<t>
YANG data model modules under review are likely to be
contained in Internet-Drafts. All guidelines for
Internet-Draft authors MUST be followed. These
guidelines are available online at:
<vspace blankLines="1"/>
http://www.rfc-editor.org/rfc-editor/instructions2authors.txt
</t>
<t>
The following sections MUST be present in an Internet-Draft
containing a module:
<list style="symbols">
<t>Narrative sections</t>
<t>Definitions section</t>
<t>Security Considerations section</t>
<t>IANA Considerations section</t>
<t>References section</t>
</list>
</t>
<section anchor="IETFCOPY" title="Module Copyright">
<t>
The module description statement MUST contain a reference to
the latest approved IETF Trust Copyright statement,
which is available on-line at:
<vspace blankLines="1"/>
http://trustee.ietf.org/license-info/
</t>
<t>
Each YANG module or submodule contained within an Internet-Draft or RFC
is considered to be a code component. The strings '<CODE BEGINS>' and
'<CODE ENDS>' MUST be used to identify each code component.
</t>
<t>
The '<CODE BEGINS>' tag SHOULD be followed by a string identifying
the file name specified in section 5.2 of <xref target="I-D.ietf-netmod-yang"/>.
The following example is for the '2010-01-18' revision
of the 'ietf-foo' module:
<figure anchor="code_begins_ends">
<artwork>
<![CDATA[
<CODE BEGINS> file "ietf-foo@2010-01-18.yang"
module ietf-foo {
// ...
revision 2010-01-18 {
description "Latest revision";
reference "RFC XXXXX";
}
// ...
}
<CODE ENDS>
]]>
</artwork>
</figure>
</t>
</section>
<section title="Narrative Sections">
<t>
The narrative part MUST include an overview section that describes
the scope and field of application of the module(s) defined by the
specification and that specifies the relationship (if any) of these
modules to other standards, particularly to standards containing
other YANG modules. The narrative part SHOULD include one or more
sections to briefly describe the structure of the modules defined
in the specification.
</t>
<t>
If the module(s) defined by the specification import definitions
from other modules (except for those defined in the
<xref target="I-D.ietf-netmod-yang">YANG</xref> or
<xref target="I-D.ietf-netmod-yang-types">YANG Types</xref>
documents), or are always implemented in
conjunction with other modules, then those facts MUST be noted in
the overview section, as MUST be noted any special
interpretations of definitions in other modules.
</t>
</section>
<section title="Definitions Section">
<t>
This section contains the module(s) defined by the specification.
These modules MUST be written using the YANG syntax defined in
<xref target="I-D.ietf-netmod-yang"/>. A YIN syntax version
of the module MAY also be present in the document. There MAY
also be other types of modules present in the document,
such as SMIv2, which are not affected by these guidelines.
</t>
<t>
See <xref target="YangGuidelines"/> for guidelines on YANG usage.
</t>
</section>
<section title="Security Considerations Section">
<t>
Each specification that defines one or more modules MUST contain
a section that discusses security considerations relevant to those
modules. This section MUST be patterned after the latest approved
template (available at
http://www.ops.ietf.org/netconf/yang-security-considerations.txt).
</t>
<t>
In particular:
<list style="symbols">
<t>
Writable data nodes that could be especially
disruptive if abused MUST be explicitly listed by name and the
associated security risks MUST be explained.
</t>
<t>
Readable data nodes that contain especially sensitive
information or that raise significant privacy concerns
MUST be explicitly listed by name and the reasons for
the sensitivity/privacy concerns MUST be explained.
</t>
<t>
Operations (i.e., 'rpc' statements) which are potentially
harmful to system behavior or that raise significant
privacy concerns MUST be explicitly listed by name and
the reasons for the sensitivity/privacy concerns
MUST be explained.
</t>
</list>
</t>
</section>
<section title="IANA Considerations Section">
<t>
In order to comply with IESG policy as set forth in
http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
submitted to the IESG for publication which has action items for IANA
MUST contain an IANA Considerations section. The requirements
for this section vary depending what actions are required of the IANA.
If there are no IANA considerations applicable to the document,
then the IANA Considerations section is not required.
Refer to the guidelines in <xref target="RFC5226" /> for more details.
</t>
<section title="Documents that Create a New Name Space">
<t>
If an Internet-Draft defines a new name space that is to be
administered by the IANA, then the document MUST include an IANA
Considerations section, that specifies how the name space is to be
administered.
</t>
<t>
Specifically, if any YANG module namespace statement value contained
in the document is not already registered with IANA, then a
new YANG Namespace registry entry MUST be requested from the
IANA. The YANG specification includes the procedure
for this purpose in its IANA Considerations section.
</t>
</section>
<section title="Documents that Extend an Existing Name Space">
<t>
It is possible to extend an existing namespace using
a YANG submodule which belongs to an existing module
already administered by IANA.
In this case, the document containing the main module MUST be updated
to use the latest revision of the submodule.
</t>
</section>
</section>
<section title="Reference Sections">
<t>
For every import or include statement which appears in a
module contained
in the specification, which identifies a module in a separate document,
a corresponding normative reference to that document MUST
appear in the Normative References section. The reference MUST
correspond to the specific module version actually used within
the specification.
</t>
<t>
For every normative reference statement which appears
in a module contained
in the specification, which identifies a separate document,
a corresponding normative reference to that document SHOULD
appear in the Normative References section. The reference SHOULD
correspond to the specific document version actually used within
the specification. If the reference statement identifies an
informative reference, which identifies a separate document,
a corresponding informative reference to that document MAY
appear in the Informative References section.
</t>
</section>
<section title="Intellectual Property Section">
<t>
The proper IPR statements MUST be present in the document,
according to the most current Internet-Draft boilerplate.
Refer to the IETF Trust Legal Provision for the
exact legal text that needs to be included.
</t>
</section>
</section>
<section title="YANG Usage Guidelines" anchor="YangGuidelines">
<t>
In general, modules in IETF standards-track specifications MUST
comply with all syntactic and semantic requirements of YANG.
<xref target="I-D.ietf-netmod-yang"/>.
The guidelines in this section are intended
to supplement the YANG specification, which is
intended to define a minimum set of conformance
requirements.
</t>
<t>
In order to promote interoperability and establish
a set of practices based on previous experience,
the following sections establish usage guidelines
for specific YANG constructs.
</t>
<t>
Only guidelines which clarify or restrict the
minimum conformance requirements are included here.
</t>
<section title="Module Naming Conventions">
<t>
Modules contained in standards track documents
SHOULD be named according to the guidelines in
the IANA considerations section of <xref target="I-D.ietf-netmod-yang"/>.
</t>
<t>
A distinctive word or acronym (e.g., protocol name
or working group acronym) SHOULD be used in the
module name. If new definitions are being defined
to extend one or more existing modules, then the same
word or acronym should be reused, instead of
creating a new one.
</t>
<t>
All published module names MUST be unique.
</t>
<t>
Once a module name is published, it MUST NOT be reused,
even if the RFC containing the module is reclassified
to 'Historic' status.
</t>
</section>
<section title="Identifiers">
<t>
Identifiers for all YANG identifiers
in published modules MUST be between 1 and 64 characters in length.
These include any construct specified as an 'identifier-arg-str'
token in the ABNF in section 12 of <xref target="I-D.ietf-netmod-yang"/>.
</t>
</section>
<section title="Defaults">
<t>
In general, it is suggested that sub-statements
containing very common default values SHOULD NOT be present.
The following sub-statements are commonly used
with the default value, which would make the
module difficult to read if used everywhere they are allowed.
</t>
<texttable>
<ttcol align="left" width="20%">Statement</ttcol>
<ttcol align="left">Default Value</ttcol>
<c>config</c>
<c>true</c>
<c>mandatory</c>
<c>false</c>
<c>max-elements</c>
<c>unbounded</c>
<c>min-elements</c>
<c>0</c>
<c>ordered-by</c>
<c>system</c>
<c>status</c>
<c>current</c>
<c>yin-element</c>
<c>false</c>
</texttable>
</section>
<section title="Conditional Statements">
<t>
A module may be conceptually partitioned in several
ways, using the 'if-feature' and/or 'when' statements.
</t>
<t>
Data model designers need to carefully consider all
modularity aspects, including the use of YANG conditional
statements.
</t>
<t>
If a data definition is optional, depending on server support for
a NETCONF protocol capability, then a YANG 'feature'
statement SHOULD be defined to indicate the NETCONF capability
is supported within the data model.
</t>
</section>
<section title="XPath Usage">
<t>
This section describes guidelines for using the
XML Path Language <xref target="W3C.REC-xpath-19991116"/> (XPath)
within YANG modules.
</t>
<t>
The 'attribute' and 'namespace' axes are not supported in YANG,
and MAY be empty in a NETCONF server implementation.
</t>
<t>
The 'position' and 'last' functions MAY be used with caution.
A server is not required to maintain any particular XML document
order for system-ordered data nodes. A server is only required
to maintain the relative XML document order of all instances
of a particular user-ordered list or leaf-list.
</t>
<t>
The 'preceding', and 'following' axes SHOULD NOT be used.
These constructs rely on XML document order within a NETCONF server
configuration database, which may not be supported
consistently or produce reliable results across implementations.
Predicate expressions based on static node
properties (e.g., name, value, ancestors,
descendants) SHOULD be used instead.
</t>
<t>
The 'preceding-sibling' and 'following-sibling' axes
MAY be used, with caution. A server is not required to
maintain a persistent or deterministic XML document
order, which will affect use of these axes.
</t>
<t>
Implicit 'position' function calls within predicates
MAY be used with caution. (e.g., //chapter[42]).
Note that a NETCONF server is only required to maintain
relative document order for related instances of a
user-ordered list or leaf-list data definition (i.e.,
'ordered-by' statement set to 'user').
</t>
<t>
Data nodes which use the 'int64' and 'uint64' built-in
type MAY be used with caution, within relational expressions.
There are boundary conditions in which the translation
from the YANG 64-bit type to an XPath number can cause
incorrect results. Specifically, an XPath double precision
floating point number cannot represent very large positive
or negative 64-bit numbers because it only provides a total precision
of 53 bits.
</t>
<t>
Data modelers need to be careful not to
confuse the YANG value space and the XPath
value space. The data types are not the same in both,
and conversion between YANG and XPath data types
SHOULD be considered carefully.
</t>
<t>
Explicit XPath data type conversions MAY be used
(e.g., 'string', 'boolean', or 'number' functions),
instead of implicit XPath data type conversions.
</t>
</section>
<section title="Lifecycle Management">
<t>
The status statement MUST be present if its value
is 'deprecated' or 'obsolete'.
</t>
<t>
The module or submodule name MUST NOT be changed, once
the document containing the module or submodule is published.
</t>
<t>
The module namespace URI value MUST NOT be changed,
once the document containing the module is published.
</t>
<t>
The revision-date sub-statement within the imports
statement SHOULD be present if any
groupings are used from the external module.
</t>
<t>
The revision-date sub-statement within the include
statement SHOULD be present if any
groupings are used from the external sub-module.
</t>
<t>
If submodules are used, then the document containing the
main module MUST be updated so that the main module
revision date is equal or more recent than the revision date
of any submodule which is (directly or indirectly) included by the main module.
</t>
</section>
<section title="Module Header, Meta, and Revision Statements">
<t>
For published modules, the namespace MUST
be a globally unique
URI, as defined in <xref target="RFC3986"/>.
This value is usually assigned by the IANA.
</t>
<t>
The organization statement MUST be present.
If the module is contained in a documented
intended for standards-track status, then
the organization SHOULD be the IETF working group
chartered to write the document.
</t>
<t>
The contact statement MUST be present.
If the module is contained in a document
intended for standards-track status, then
the working group WEB and mailing information
MUST be present, and the main document author or
editor contact information SHOULD be present.
If additional authors or editors exist,
their contact information MAY be present.
In addition, the Area Director and other contact
information MAY be present.
</t>
<t>
The description statement MUST be present.
The appropriate IETF Trust Copyright text MUST be present,
as described in <xref target="IETFCOPY" />.
</t>
<t>
If the module relies on information contained
in other documents, which are not the same
documents implied by the import statements
present in the module, then these documents
MUST be identified in the reference
statement.
</t>
<t>
A revision statement MUST be present for each published
version of the module. The revision statement MUST
have a reference substatement.
It MUST identify the published document which
contains the module.
Modules are often extracted from their original
documents and it is useful for developers
and operators to know how to find the
original source document in a consistent manner.
The revision statement MAY have a description substatement.
</t>
<t>
Each new revision MUST include a revision date which
is higher than any other revision date in the module.
</t>
<t>
It is acceptable to reuse the
same revision statement within unpublished versions
(i.e., Internet-Drafts), but the revision date
MUST be updated to a higher value each time the
Internet-Draft is re-published.
</t>
</section>
<section anchor="TEMPNS" title="Namespace Assignments">
<t>
It is RECOMMENDED that only valid YANG modules are
included in documents, whether they are published yet or not.
This allows:
<list style="symbols">
<t>
the module to compile correctly instead
of generating disruptive fatal errors.
</t>
<t>
early implementors to use the modules
without picking a random value for the XML namespace.
</t>
<t>
early interoperability testing since
independent implementations will use the same
XML namespace value.
</t>
</list>
</t>
<t>
Until a URI is assigned by the IANA, a proposed namespace URI
MUST be provided for the namespace statement in a YANG module.
A value SHOULD be selected which is not likely to collide with
other YANG namespaces. Standard module names, prefixes,
and URI strings already listed in the YANG Module Registry
MUST NOT be used.
</t>
<t>
A standard namespace statement value SHOULD have the
following form:
<vspace blankLines="1"/>
<URN prefix string>:<module-name>
</t>
<t>
The following URN prefix string SHOULD be used for published
and unpublished YANG modules:
<vspace blankLines="1"/>
urn:ietf:params:xml:ns:yang:
</t>
<t>
The following example URNs would be valid temporary namespace
statement values for standards-track modules:
<list>
<t>
urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
</t>
<t>
urn:ietf:params:xml:ns:yang:ietf-netconf-state
</t>
<t>
urn:ietf:params:xml:ns:yang:ietf-netconf
</t>
</list>
</t>
<t>
Note that a different URN prefix string SHOULD be used for non-standards track
modules. The string SHOULD be selected according to the guidelines
in <xref target="I-D.ietf-netmod-yang"/>.
</t>
<t>
The following examples of non-standards
track modules are only suggestions. There are no
guidelines for this type of URN in this document:
<list>
<t>
http://example.com/ns/example-interfaces
</t>
<t>
http://example.com/ns/example-system
</t>
</list>
</t>
</section>
<section title="Top Level Data Definitions">
<t>
There SHOULD only be one top-level data node defined
in each YANG module, if any data nodes are defined at all.
</t>
<t>
The top-level data organization SHOULD be considered carefully,
in advance. Data model designers need to consider how
the functionality for a given protocol or protocol family
will grow over time.
</t>
<t>
The names and data organization SHOULD reflect persistent
information, such as the name of a protocol. The name
of the working group SHOULD NOT be used because this
may change over time.
</t>
<t>
A mandatory database data definition is defined as
a node that a client must provide for the database
to be valid. The server is not required to provide a value.
</t>
<t>
Top-level database data definitions MUST NOT be mandatory.
If a mandatory node appears at the top-level, it will
immediately cause the database to be invalid.
This can occur when the server boots or when a module
is loaded dynamically at runtime.
</t>
</section>
<section title="Data Types">
<t>
Selection of an appropriate data type (i.e., built-in
type, existing derived type, or new derived type)
is very subjective and therefore few requirements
can be specified on that subject.
</t>
<t>
Data model designers SHOULD use the most appropriate
built-in data type for the particular application.
</t>
<t>
If extensibility of enumerated values is required,
then the identityref data type SHOULD be used
instead of an enumeration or other built-in type.
</t>
<t>
For string data types, if a machine-readable pattern
can be defined for the desired semantics, then
one or more pattern statements SHOULD be present.
</t>
<t>
For string data types, if the length of the string
is required to be bounded in all implementations,
then a length statement MUST be present.
</t>
<t>
For numeric data types, if the values allowed
by the intended semantics are different than
those allowed by the unbounded intrinsic data
type (e.g., int32), then a range statement SHOULD be present.
</t>
<t>
The signed numeric data types (i.e., 'int8',
'int16', 'int32', and 'int64') SHOULD NOT be used unless
negative values are allowed for the desired semantics.
</t>
<t>
For enumeration or bits data types, the semantics for
each enum or bit SHOULD be documented. A separate
description statement (within each enum or bit
statement) SHOULD be present.
</t>
</section>
<section title="Reusable Type Definitions">
<t>
If an appropriate derived type exists in any
standard module, such as
<xref target="I-D.ietf-netmod-yang-types"/>,
then it SHOULD be used instead of defining a new derived type.
</t>
<t>
If an appropriate units identifier can be associated
with the desired semantics, then a units statement
SHOULD be present.
</t>
<t>
If an appropriate default value can be associated
with the desired semantics, then a default statement
SHOULD be present.
</t>
<t>
If a significant number of derived types are defined,
and it is anticipated that these data types will be reused
by multiple modules, then these derived types SHOULD be
contained in a separate module or submodule, to allow
easier reuse without unnecessary coupling.
</t>
<t>
The description statement MUST be present.
</t>
<t>
If the type definition semantics are defined
in an external document (other than another
YANG module indicated by an import
statement), then the reference
statement MUST be present.
</t>
</section>
<section title="Data Definitions">
<t>
The description statement MUST be present in the following
YANG statements:
<list style="symbols">
<t>anyxml</t>
<t>augment</t>
<t>choice</t>
<t>container</t>
<t>extension</t>
<t>feature</t>
<t>grouping</t>
<t>identity</t>
<t>leaf</t>
<t>leaf-list</t>
<t>list</t>
<t>notification</t>
<t>rpc</t>
<t>typedef</t>
</list>
</t>
<t>
If the data definition semantics are defined in an external document,
(other than another
YANG module indicated by an import
statement), then a reference statement MUST be present.
</t>
<t>
The 'anyxml' construct MAY be used with caution within
configuration data. This may be useful to represent
an HTML banner containing markup elements, such as <b>
and </b>.
However, this construct SHOULD NOT
be used if other YANG data node types can be used instead to
represent the desired syntax and semantics.
</t>
<t>
If there are referential integrity constraints associated
with the desired semantics that
can be represented with XPath, then one or more
must statements SHOULD be present.
</t>
<t>
For list and leaf-list data definitions, if the number of possible instances
is required to be bounded for all implementations,
then the max-elements statements SHOULD be present.
</t>
<t>
If any must or when statements are used within the
data definition, then the data definition description statement
SHOULD describe the purpose of each one.
</t>
</section>
<section title="Operation Definitions">
<t>
If the operation semantics are defined in an external document
(other than another YANG module indicated by an import
statement), then a reference statement MUST be present.
</t>
<t>
If the operation impacts system behavior in some way,
it SHOULD be mentioned in the description statement.
</t>
<t>
If the operation is potentially harmful to system
behavior in some way,
it MUST be mentioned in the Security Considerations
section of the document.
</t>
</section>
<section title="Notification Definitions">
<t>
The description statement MUST be present.
</t>
<t>
If the notification semantics are defined in an external document
(other than another YANG module indicated by an import
statement), then a reference statement MUST be present.
</t>
</section>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<t>
This document registers one URI in the IETF XML registry
<xref target="RFC3688"/>.
The following registration is requested:
<vspace blankLines="1" />
URI: urn:ietf:params:xml:ns:yang:ietf-template
<vspace blankLines="1" />
Registrant Contact: The NETMOD WG of the IETF.
<vspace blankLines="1" />
XML: N/A, the requested URI is an XML namespace.
</t>
<t>
This document requests the following assignment in the YANG Module
Names Registry for the YANG module template in <xref target="YANGMOD"/>.
</t>
<texttable>
<ttcol align="left" width="20%">Field</ttcol>
<ttcol align="left">Value</ttcol>
<c>name</c>
<c>ietf-template</c>
<c>namespace</c>
<c>urn:ietf:params:xml:ns:yang:ietf-template</c>
<c>prefix</c>
<c>temp</c>
<c>reference</c>
<c>RFCXXXX</c>
</texttable>
</section>
<section anchor="Security" title="Security Considerations">
<t>
This document defines documentation guidelines for
NETCONF content defined with the YANG data modeling
language. The guidelines for how to write a
Security Considerations section for a YANG module
are defined in the online document
<vspace blankLines="1" />
http://www.ops.ietf.org/netconf/yang-security-considerations.txt
<vspace blankLines="1" />
This document does not introduce
any new or increased security risks into
the management system.
</t>
</section>
<section title="Acknowledgments">
<t>
The structure and contents of this document are adapted from
<xref target="RFC4181">
Guidelines for MIB Documents
</xref>, by C. M. Heard.
</t>
<t>
The working group thanks Martin Bjorklund and Juergen
Schoenwaelder for their extensive reviews and contributions
to this document.
</t>
</section>
</middle>
<!-- ***** BACK MATTER ***** -->
<back>
<references title="Normative References">
&rfc2119;
&rfc3688;
&rfc3986;
&rfc4741;
&rfc5378;
&xpathspec;
&yangspec;
&yangtypes;
</references>
<references title="Informative References">
&rfc4181;
&rfc5226;
</references>
<section title="Module Review Checklist">
<t>
This section is adapted from RFC 4181.
</t>
<t>
The purpose of a YANG module review is to review
the YANG module both for technical correctness and
for adherence to IETF documentation requirements.
The following checklist may be helpful when reviewing
a draft document:
</t>
<t><list style="numbers">
<t>
I-D Boilerplate --
verify that the draft contains the required
Internet-Draft boilerplate
(see http://www.ietf.org/ietf/1id-guidelines.txt),
including the appropriate statement to permit
publication as an RFC, and that I-D boilerplate does
not contain references or section numbers.
</t>
<t>Abstract --
verify that the abstract does not contain references,
that it does not have a section number, and that its content follows
the guidelines in http://www.ietf.org/ietf/1id-guidelines.txt.
</t>
<t>
IETF Trust Copyright --
verify that the draft has the appropriate text
regarding the rights that document contributers
provide to the IETF Trust <xref target="RFC5378"/>.
Some guidelines related to this requirement
are described in <xref target="IETFCOPY" />.
The IETF Trust license policy (TLP) can be found at:
<vspace blankLines="1" />
http://trustee.ietf.org/docs/IETF-Trust-License-Policy.pdf
</t>
<t>
Security Considerations Section --
verify that the draft uses the
latest approved template from the OPS area web site
(http://www.ops.ietf.org/netconf/yang-security-considerations.txt)
and that the guidelines therein have been followed.
</t>
<t>
IANA Considerations Section --
this section must always be
present. For each module within the document, ensure that the
IANA Considerations section contains entries
for the following IANA registries:
<list style="hanging">
<t hangText="XML Namespace Registry:">
Register the YANG module namespace.
</t>
<t hangText="YANG Module Registry:">
Register the YANG module name, prefix, namespace, and RFC number,
according to the rules specified in
<xref target="I-D.ietf-netmod-yang"/>.
</t>
</list>
</t>
<t>
References --
verify that the references are properly divided
between normative and informative references, that RFC 2119 is
included as a normative reference if the terminology defined therein
is used in the document, that all references required by the
boilerplate are present, that all YANG modules containing imported
items are cited as normative references, and that all citations point
to the most current RFCs unless there is a valid reason to do
otherwise (for example, it is OK to include an informative reference
to a previous version of a specification to help explain a feature
included for backward compatibility). Be sure citations for all
imported modules are present somewhere in the document
text (outside the YANG module).
</t>
<t>
Copyright Notices --
verify that the draft contains an
abbreviated IETF Trust copyright notice in the description
statement of each
YANG module or sub-module, and that it contains the full
IETF Trust copyright
notice at the end of the document. Make sure that the correct
year is used
in all copyright dates. Use the approved text from the latest
Trust Legal Provisions (TLP) document, which can be found at:
<vspace blankLines="1"/>
http://trustee.ietf.org/license-info/
</t>
<t>
Other Issues --
check for any issues mentioned in
http://www.ietf.org/ID-Checklist.html that are not covered elsewhere.
</t>
<t>
Technical Content --
review the actual technical content for
compliance with the guidelines in this document. The use of a YANG
module compiler is recommended when checking for syntax errors.
A list of freely available tools and other information can be found at:
<vspace blankLines="1" />
http://trac.tools.ietf.org/wg/netconf/trac/wiki
<vspace blankLines="1" />
Checking for correct syntax, however, is only part of the job. It is
just as important to actually read the YANG module document
from the point of view of a potential implementor.
It is particularly important to
check that description statements are sufficiently
clear and unambiguous to allow interoperable
implementations to be created.
</t>
</list></t>
</section>
<section title="YANG Module Template" anchor="YANGMOD">
<t>
<figure anchor="yang_template">
<artwork>
<![CDATA[
<CODE BEGINS> file "ietf-template@2010-05-18.yang"
module ietf-template {
// replace this string with a unique namespace URN value
namespace
"urn:ietf:params:xml:ns:yang:ietf-template";
// replace this string, and try to pick a unique prefix
prefix "temp";
// import statements here: e.g.,
// import ietf-yang-types { prefix yang; }
// import ietf-inet-types { prefix inet; }
// identify the IETF working group if applicable
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
// update this contact statement with your info
contact
"WG Web: <http://tools.ietf.org/wg/your-wg-name/>
WG List: <mailto:your-wg-name@ietf.org>
WG Chair: your-WG-chair
<mailto:your-WG-chair@example.com>
Editor: your-name
<mailto:your-email@example.com>";
// replace the first sentence in this description statement.
// replace the copyright notice with the most recent
// version, if it has been updated since the publication
// of this document
description
"This module defines a template for other YANG modules.
Copyright (c) 2010 IETF Trust and the persons identified as
the document authors. 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).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note
reference "RFC XXXX";
// RFC Ed.: remove this note
// Note: extracted from draft-ietf-netmod-yang-usage-04.txt
// replace '2010-05-18' with the module publication date
// The format is (year-month-day)
revision "2010-05-18" {
description
"Initial version";
}
// extension statements
// feature statements
// identity statements
// typedef statements
// grouping statements
// data definition statements
// augment statements
// rpc statements
// notification statements
// DO NOT put deviation statements in a published module
}
<CODE ENDS>
]]>
</artwork>
</figure>
</t>
</section>
<section title="Change Log">
<section title="Changes from 07 to 08">
<t>
<list style="symbols">
<t>
Corrected YANG security considerations URL.
</t>
<t>
Expanded 'CODE BEGINS' example.
</t>
<t>
Added RPC operations to the security considerations
guidelines section.
</t>
<t>
Removed guideline about leading and trailing
whitespace.
</t>
</list>
</t>
</section>
<section title="Changes from 06 to 07">
<t>
<list style="symbols">
<t>
Corrected title change bug; supposed to be page header
instead.
</t>
<t>
Fixed typos added to last revision.
</t>
<t>
Added sentence to checklist to make sure text
outside module contains citations for imports.
</t>
</list>
</t>
</section>
<section title="Changes from 05 to 06">
<t>
<list style="symbols">
<t>
Several clarifications and corrections, based
on the AD review by Dan Romascanu.
</t>
</list>
</t>
</section>
<section title="Changes from 04 to 05">
<t>
<list style="symbols">
<t>
Changed 'object' terminology to 'data definition'.
</t>
<t>
Put XPath guidelines in separate section.
</t>
<t>
Clarified XPath usage for XML document order
dependencies.
</t>
<t>
Updated <CODE BEGINS> guidelines to
current conventions.
</t>
<t>
Added informative reference for IANA considerations guidelines
and XML registry.
</t>
<t>
Updated IANA Considerations section to reserve the ietf-template
module in the YANG Module Name Registry so it cannot be
reused accidently.
</t>
<t>
Many other clarifications and fixed typos found in WGLC reviews.
</t>
</list>
</t>
</section>
<section title="Changes from 03 to 04">
<t>
<list style="symbols">
<t>
Removed figure 1 to reduce duplication, just refer to 4741bis draft.
</t>
<t>
Fixed bugs and typos found in WGLC reviews.
</t>
<t>
Removed some guidelines and referring to YANG draft instead
of duplicating YANG rules here.
</t>
<t>
Changed security guidelines so they refer to the IETF Trust TLP
instead of MIB-specific references.
</t>
<t>
Change temporary namespace guidelines so the DRAFT-XX and RFC-nnnn
suffix strings are not used.
</t>
<t>
Changed some MIB boilerplate so it refers to YANG boilerplate instead.
</t>
<t>
Introduced dangling URL reference to online YANG security guidelines
<vspace blankLines="1" />
http://www.ops.ietf.org/yang-security.html
<vspace blankLines="1" />
[ed.: Text from Bert Wijnen will be completed soon and posted online,
and then this URL will be finalized.]
</t>
<t>
Moved reference for identifying the source document inside the
each revision statement.
</t>
<t>
Removed guideline about valid XPath since YANG already requires
valid XPath.
</t>
<t>
Added guideline that strings should not rely on preservation
of leading and trailing whitespace characters.
</t>
<t>
Relaxed some XPath and anyxml guidelines from SHOULD NOT or
MUST NOT to MAY use with caution.
</t>
<t>
Updated the TLP text within the example module again.
</t>
<t>
Reversed order of change log so most recent entries are first.
</t>
</list>
</t>
</section>
<section title="Changes from 02 to 03">
<t>
<list style="symbols">
<t>
Updated figure 1 to align with 4741bis draft.
</t>
<t>
Updated guidelines for import-by-revision and
include-by-revision.
</t>
<t>
Added file name to code begins convention in
ietf-template module.
</t>
</list>
</t>
</section>
<section title="Changes from 01 to 02">
<t>
<list style="symbols">
<t>
Updated figure 1 per mailing list comments.
</t>
<t>
Updated suggested organization to include the working group name.
</t>
<t>
Updated ietf-template.yang to use new organization statement value.
</t>
<t>
Updated Code Component requirements as per new TLP.
</t>
<t>
Updated ietf-template.yang to use new Code Component begin and end markers.
</t>
<t>
Updated references to the TLP in a couple sections.
</t>
<t>
Change manager/agent terminology to client/server.
</t>
</list>
</t>
</section>
<section title="Changes from 00 to 01">
<t>
<list style="symbols">
<t>
Added transport 'TLS' to figure 1.
</t>
<t>
Added note about RFC 2119 terminology.
</t>
<t>
Corrected URL for instructions to authors.
</t>
<t>
Updated namespace procedures section.
</t>
<t>
Updated guidelines on module contact, reference,
and organization statements.
</t>
<t>
Added note on use of preceding-sibling
and following-sibling axes in XPath expressions.
</t>
<t>
Added section on temporary namespace statement values.
</t>
<t>
Added section on top level database objects.
</t>
<t>
Added ietf-template.yang appendix.
</t>
</list>
</t>
</section>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:06:40 |