A YANG profile for defining
Asynchronous Management Protocol
Application Data Models
RKF Engineering Solutions, LLC
1229 19th Street NWWasingtonDC20036USBSipos@rkf-eng.com
Johns Hopkins University Applied Physics Laboratory
Edward.Birrane@jhuapl.eduDelay Tolerant Networking
This document specifies a YANG profile for defining
Application Data Model (ADM) schema for the
Asynchronous Management Protocol (AMP).
The AMP has no relation to NETCONF; YANG is used here only for
its language syntax, and its module and type systems.
This profile uses YANG
as an encoding for the management schema and
makes use of the YANG module and type systems.
The fact that YANG is also used to specify data models for the
NETCONF protocol has no direct influence over this use of YANG
to specify data models for AMP.
This specification follows in the definition
of the "amp-adm" YANG module.
The amp-adm module defines only subtypes and extensions; it does not
define any actual data model elements.
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 .
An AMP application SHALL define its Application Data Model (ADM) by means
of a YANG module which imports and uses "amp-adm" module extensions.
An official Pyang tool plugin SHOULD be used
to validate the contents of an ADM YANG module.
A YANG module which defines an AMP ADM SHALL NOT be used to also define
a data model for NETCONF or any other non-AMP protocol.
It may be syntatically allowable to mix models for multiple protocols
but it decreases the intelligability of the module for either purpose.
A YANG module which defines an AMP ADM SHALL NOT contain any
"default" statements.
For each ADM-specific YANG statement which requires an OID to be
assigned to it, it is possible to use one of the
"fulloid", "suboid", or "compressoid" substatements to make that
assignment.
Not all of the OID assignment substatements are available in all
contexts, so following the allowed substatement table is important.
The types of OID assignments are:
Full OIDs can be used in any situation where an OID is needed.
Compressed OIDs can also be used in any situation where an OID is
needed, but require the use of a module-unique OID nickname ID.
Sub-OIDs can be used where the OID being assigned is relative to the
structural (module-statement-wise) parent of the assignment.
An ADM SHOULD make use of sub-OIDs where possible, both to avoid
typos possible with full OIDs and to avoid nickname assignment for
every group within the ADM.
Using sub-OIDs also guarantees that the tree structure of the ADM
module matches one-for-one with the OID tree.
This section specifies how AMP types interact with native YANG types.
All AMP data types are sub-typed from YANG native types solely
for the purpose of providing a baseline of behavior for YANG
parsers.
Any YANG module which defines an AMP ADM SHALL only use types
(or derived types) from the "amp-adm" module.
The AMP types of "BYTE", "INT", "UINT", "VAST", and "UVAST" are derived
directly from the built-in YANG type of the same numeric domain.
There is no functional difference between these types and the native
types, other than the namespace of these types.
Using AMP-specific names allows ADM module authors to keep consistent
terminology between textual specification and YANG specification.
The "SDNV" type is derived from YANG "binary" type due to its domain
being larger than any of the built-in YANG types.
The AMP types of "REAL32" and "REAL64" are derived from YANG "binary"
type because the built-in floating point type is not a clear
superset of the floating point types of
.
The "SDNV" type is derived from YANG "binary" type due to its domain
being larger than any of the built-in YANG numeric types.
The "TS" type is also derived from YANG "binary" type due to the
more complex encoding semantics of the TS type.
The "STR" type is derived from the YANG "string" type only because
they both are intended to have the semantics of human-readable text.
An ADM SHOULD NOT use the amp:STR type for any data other than text
encoded with UTF-8 (see ).
The encoding of "STR" type is wholy unrelated to any NETCONF use
of the YANG "string" type.
The "BLOB" type is derived from YANG "binary" type.
The BLOB is the simplest AMP-specific type which is encoded using
internal sub-items (the size separate from the bytes).
The "DC" and "TDC" types are also derived from YANG "binary" type
for lack of specific YANG mechanism for type decomposition.
The "MID" type is derived from YANG "binary" type due to its combined
use of bit patterns (in its header) and BER-encoded data.
The "MC" type is also derived from YANG "binary" type
for lack of specific YANG mechanism for type decomposition.
An ADM SHOULD subtype any numeric type in order to apply additional
semantic context to the numerical values
(similar to the SMIv2 CounterXX and GaugeXX ).
An ADM SHOULD make use of the YANG "units" substatement when
numeric types are used (within either a typedef or a type-use).
An ADM SHOULD subtype the BLOB type in order to identify
application-specific encoding formats.
Using plain BLOB types within an ADM is discouraged due to the
opaqueness of the
Any ADM subtype SHALL have no effect on the value encoding of AMP.
Subtypes are purely used to assist applications in managing
value semantics.
Any ADM subtype SHALL include a description substatement explaining
the purpose of the subtype.
This section specifies how AMP extension statements interact with
native YANG statements within an application YANG module.
This section contains extensions for identifying a data node within
the YANG model tree by a unique OID value.
A "fulloid" statement is used to anchor an item in the OID
tree.
The value of a fulloid is the dotted-numeric notation of the OID
value. A fulloid value must not be empty.
Any substatements which are sibling to a "fulloid" will be relative
to that OID root for the purposes of "suboid" processing.
The format of a fulloid argument is a string of period-separated
numeric components.
substatementcardinalitydescription0..1
A "suboid" statement is used to define an item's OID relative
to a sibling statement's full OID.
The value of a suboid is the dotted-numeric notation of the OID
parts under the full OID. A suboid value must not be empty.
The format of a suboid argument is the same as a fulloid argument.
The interpretation of a suboid depends upon the context of the
statement.
substatementcardinalitydescription0..1
A "nickname" statement is used to define an application-specific
numeric identifier for a full OID prefix.
The nickname is used by both the AMP agent and manager to shorten
OID encoding.
The format of a nickname argument is a single non-negative integer
value.
Each nickname is defined within the namespace of the ADM module.
substatementcardinalitydescription0..1fulloid1
A "compressoid" statement is used to define a full OID based on
a module-specific nickname (see ) as
a prefix and a suboid suffix.
The format of a compressoid argument is a nickname value
(see ) within square brackets
followed by a suboid string.
substatementcardinalitydescription0..1
The "group" statement is used to define a grouping of other items
within the ADM.
Each group is assigned an OID (see )
and used as an OID anchor for its substatements.
The order of substatements within a group is not significant.
Only the OID assignment of each item is significant.
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1group0..*primitive0..*control0..*report0..*macro0..*operator0..*
The "primitive" statement is used to define an atomic value within
an ADM.
Each primitive is assigned an OID (see )
and a type.
The primitive has different semantics from the YANG "leaf" statement
due to the lack of secondary (non-type) attributes (e.g. config/state
distinction).
All primitive objects are state; any configuration is performed
via "control" statements.
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1type1units0..1
The "control" statement is used to define an available control
within the ADM.
Each control is assigned an OID (see )
and an ordered list of parmeter and result items.
The control has different semantics from the YANG "rpc" statement
due to the difference in protocol encoding and to the asynchronous
nature of the AMP.
Each control is parameterized by some number of parameters
(see ) and some number of results
(see ).
There is no provision in an ADM for specifying alternative parameters
or alternative results (i.e. no parameters are optional).
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1parameter0..*result0..*
The "parameter" statement is used to define single expected parameter
of a "control" statement.
In the AMP each control has a fixed number of typed parameters, there
is no provision for overloaded controls which take variable numbers
of parameters.
A control parameter is an atomic value with a distinct type,
but has no distinct OID.
The parameter statement's argument is used as the parameter's name.
Within a single control, each parameter name SHALL be unique.
The parameter name is not related to any AMP encoding, so is useful
only for the sake of identifying the parameter within the ADM.
substatementcardinalitydescription0..1type1units0..1
The "result" statement is used to define single expected result
of a "control" statement.
In the AMP each control has a fixed number of typed results, there
is no provision for overloaded controls which yield variable numbers
of results.
A control result is an atomic value with a distinct type,
but has no distinct OID.
The result statement's argument is used as the result's name.
Within a single control, each result name SHALL be unique.
The result name is not related to any AMP encoding, so is useful
only for the sake of identifying the result within the ADM.
substatementcardinalitydescription0..1type1units0..1
The "report" statement is used to define the contents of an AMP
report, but does not define when any instances of the report may
be created.
Each report is assigned an OID (see )
and an ordered list of content items.
Asynchronous reporting is a distinct feature of the AMP from
other management protocols.
Each report is parameterized by some number of items which are to
be contained in corresponding report instances
(see ).
There is no provision in an ADM for specifying alternative report
contents.
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1reportitem0..*
The "reportitem" statement is used to define single expected item
within a report instance.
In the AMP each report has a fixed number of typed items, there
is no provision for overloaded reports which yield variable numbers
of items.
A reportitem is an atomic value with a distinct OID of the primitive
to be included in a report instance.
A reportitem has no type of its own.
The reportitem statement's argument is used as the item's name.
Within a single report, each reportitem name SHALL be unique.
The reportitem name is not related to any AMP encoding, so is useful
only for the sake of identifying the item within the ADM.
substatementcardinalitydescription0..1fulloid | compressoid1
The "macro" statement is used to declare an AMP macro within an ADM.
//FIXME: what value is there in the inline definition?
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1
The "operator" statement is used to define the syntax of an ADM
operator (for use in expressions).
Each operator is assigned an OID (see )
and an ordered list of operands.
Each operator is parameterized by some number of items which are to
be used as operands at statement execution time.
(see ).
substatementcardinalitydescription0..1reference0..1status0..1fulloid | suboid | compressoid1operand0..*
The "operand" statement is used to define single expected operand
within an operator statement.
In the AMP each operation has a fixed number of untyped operands.
There is no provision for overloaded operators which take
variable numbers of operands.
An operand is an atomic value with no associated OID or type.
The operand statement's argument is used as the item's name.
Within a single operator, each operand name SHALL be unique.
The operand name is not related to any AMP encoding, so is useful
only for the sake of identifying the item within the ADM.
substatementcardinalitydescription0..1
Some aspects of an ADM module require in-line instantiations of data
which will eventually be encoded in AMP format.
Rather than requiring the ADM module author to do the encoding manually,
and to allow easier inspection by an ADM module reader, each
to-be-encoded data item is represented in the ADM module by
one of the "amp:*-instance" statements.
Examples of uses for these instances are: a numeric value used in
the definition of a "literal" statement, or OID values used in
the definition of a "report" statement.
Where possible, an ADM author SHOULD supply all data instances
necessary to interpret the constant-data items within an ADM.
The "number-instance" statement is used to define single value
of one of the integer data types (BYTE, INT, UINT, VAST, UVAST, SDNV)
or one of the floating point types (REAL32, REAL64).
The number-type substatement SHALL be present unless the
number-instance is a direct substatement of a typed statement
(e.g. a literal statement).
The lexical representation of all AMP integer types SHALL conform to
the corresponding integer types .
The lexical representation of AMP floating point types SHALL conform to
the "decimal64" type of .
The binary-valued floating point domain of the AMP types SHALL
be enforced by any YANG module parser.
substatementcardinalitydescription0..1number-type0..1
The "number-type" statement is used to identify the specific
encoding type for a number-instance parent statement.
A number-type statement's argument SHALL be one of the numeric
type names:
BYTEINTUINTVASTUVASTSDNVREAL32REAL64
The number-type statement has no substatemnts.
The "string-instance" statement is used to define single text value
for the STR data type.
The string-instance argument SHALL NOT contain the UTF-8 code point
zero. Code point zero is used to terminate strings in AMP.
substatementcardinalitydescription0..1
The "BLOB-instance" statement is used to define single binary-data
value for the BLOB data type.
The BLOB-instance argument SHALL be represented by Base-64 encoded
text according to .
The length of the encoded BLOB is implicit in the BLOB-instance
representation.
substatementcardinalitydescription0..1
The "TS-instance" statement is used to define single time-stamp
value.
Although its encoding is identical to the SDNV number-instance,
the TS-instance YANG representation is different.
The TS-instance argument SHALL contain an fully qualified absolute
time represented according to .
substatementcardinalitydescription0..1
The "MID-instance" statement is used to define single MID value,
including all of the possible MID variations.
substatementcardinalitydescription0..1MID-type1MID-category1MID-issuer0..1MID-tag0..1
The "MID-issuer" statement is used to define the optional Issuer
payload of the MID value.
The presence or absense of a MID-issuer statement determines
the header and payload encoding of the MID value.
The MID-issuer argument SHALL be a positive integer value.
substatementcardinalitydescription0..1
The "MID-tag" statement is used to define the optional Tag
payload of the MID value.
The presence or absense of a MID-tag statement determines
the header and payload encoding of the MID value.
The MID-tag argument SHALL be a positive integer value.
substatementcardinalitydescription0..1
The "DC-instance" statement is used to define a list of BLOB values.
The count of values present in the DC is implicit in the
number of BLOB-instance substatements.
The order of BLOB-instance substatements SHALL correpsond with the
encoded DC value.
substatementcardinalitydescription0..1BLOB-instance0..*
The "MC-instance" statement is used to define a list of MID values.
The count of values present in the MC is implicit in the
number of MID-instance substatements.
The order of MID-instance substatements SHALL correpsond with the
encoded MC value.
substatementcardinalitydescription0..1MID-instance0..*
The "TDC-instance" statement is used to define a list of typed
data instance values.
The count of values present in the TDC is implicit in the
number of "*-instance" substatements.
The order of data instance substatements SHALL correpsond with the
encoded TDC value.
substatementcardinalitydescription0..1number-instance | string-instance | BLOB-instance | TS-instance
| MID-instance | DC-instance | TDC-instance0..*
This document registers one URI in the IETF
XML registry .
NOTE TO EDITOR: module registration is pending I-D approval.
The following registration has been made:
FieldValueURIurn:ietf:params:xml:ns:yang:amp-admRegistrant ContactThe DTN WG of the IETF.XMLN/A, the requested URI is an XML namespace.
This document registers one module name/namespace in the IETF
YANG Module Names Registry .
NOTE TO EDITOR: module registration is pending I-D approval.
The following registration has been made:
FieldValueNameamp-admNamespaceurn:ietf:params:xml:ns:yang:amp-admPrefixampReferencedraft-bsipos-dtn-amp-yang
This memo only defines a mechanism to specify an application schema, it does
not impose any limitations or requirements on the contents of that schema.
The amp-adm module defines only subtypes and extensions.
It does not define any actual data model elements, so there are no
direct security implications.
An extensible YANG validator and converter in pythonhttp://code.google.com/p/pyang/
The contents of this section is the machine-readable specification
of this YANG module.
The following YANG definition is the top-level "amp" module.
The following YANG definition includes types specific to AMP.
The following YANG definition includes extensions specific to AMP.
The following YANG definition includes extensions to define
AMP instance values.
The following YANG definition includes extensions specific to AMP.