RFC 5935

Expressing SNMP SMI Datatypes in XML Schema Definition Language

📅 published August 2010, from ietf

RFC 5935: Expressing SNMP SMI Datatypes in XML Schema Definition Language 🎀

okay bestie, here's the title block tea ☕

  • RFC number: 5935 🦋
  • Stream: Internet Engineering Task Force (IETF) ✨
  • Authors: M. Ellison (Ellison Software Consulting) and B. Natale (MITRE) 👩‍💻
  • Category: Standards Track 👑
  • ISSN: 2070-1721
  • Date: August 2010 📅
  • Obsoletes / Updates: nothing listed. The header has no line for either, so this RFC doesn't obsolete or update anything 🙅‍♀️

Abstract 🌸

So this memo sets the official IETF way to write SMI base datatypes (the building blocks of SNMP management info) in XML Schema Definition (XSD) language 💖. The big goal is XML docs that stay as faithful to the SMI as possible, with XSD doing the validating ✨.

Status of This Memo 🧚

This is an Internet Standards Track document 🌈.

It's an IETF product, so it reflects the consensus of the whole IETF community 🫶. It got public review, and the Internet Engineering Steering Group (IESG) approved it for publication. More on Internet Standards is in Section 2 of RFC 5741 📚.

Want the current status, any errata, or a way to send feedback? Check http://www.rfc-editor.org/info/rfc5935 💅.

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. 💜

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the publication date. Read these carefully, because they spell out your rights and restrictions for this document 📜. Code Components pulled from this document gotta include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come without warranty, as the Simplified BSD License describes 🎀.

Table of Contents 🍓

1. Introduction ....................................................2
2. Conventions .....................................................4
3. Requirements ....................................................4
4. XSD for SMI Base Datatypes ......................................5
5. Rationale .......................................................8
   5.1. Numeric Datatypes ..........................................8
   5.2. OctetString ................................................9
   5.3. Opaque ....................................................10
   5.4. IpAddress .................................................10
   5.5. ObjectIdentifier ..........................................10
6. Security Considerations ........................................11
7. IANA Considerations ............................................11
   7.1. SMI Base Datatypes Namespace Registration .................12
   7.2. SMI Base Datatypes Schema Registration ....................12
8. Acknowledgements ...............................................12
9. References .....................................................13
   9.1. Normative References ......................................13
   9.2. Informative References ....................................13

1. Introduction 🧚

Okay so there are SO many reasons to express the management info that SMI MIB modules describe in XML [XML] 🤩. Folks outside the traditional IETF network management crowd want this, and folks inside it do too. XML-based management apps might want the juicy data models MIB modules offer. Other XML apps might want to reach MIB instrumentation through gateways to SNMP agents 🔥. Both get a major glow-up from the standard mapping of SMI datatypes to XML datatypes via XSD [XMLSchema], [XSDDatatypes] 💅.

MIB modules use SMIv2 [RFC2578] to describe their data models 📚. Legacy MIB modules used SMIv1 [RFC1155], ngl. MIB data sent in variable bindings ("varbinds") inside protocol data units (PDUs) of SNMP messages uses the primitive, base datatypes the SMI defines 🦋.

The SMI lets you make derivative datatypes called "textual conventions" ("TCs") [RFC2579] 💜. A TC has a unique name, a syntax that either refines or is a base SMI datatype, and fairly precise application-level semantics. TCs help apps handle MIB data correctly, make MIB modules easier for humans to read, and support good renderings of MIB data ✨.

Values in varbinds for objects defined with TC syntax are always encoded as the base SMI datatype under that TC syntax 🙈. So the XSD mappings in this memo cover values for TC-defined objects and base SMI-syntax objects. Using the translation of TC into base SMI datatypes, any MIB module that uses TCs can be mapped into XSD with these mappings 💖. For example, IP addresses (IPv4 and IPv6) defined with the InetAddress TC (per [RFC4001]) are encoded using the base SMI datatype under the InetAddress TC syntax, not the IpAddress base datatype 🌸.

Lots of independent schemes for expressing SMI datatypes in XSD already exist 🍓. They overlap a lot, especially for numeric SMI datatypes. But they differ enough, especially for non-numeric ones, that you don't get uniform expression or general interoperability 😭.

In this memo, "fidelity" means the quality of an accurate, consistent representation of SMI data values. "faithful" means reliably reflecting the semantics of SMI data values 🔍. Both are essential to uniform expression and general interoperability in the XML representation of SMI data values 👑.

The main purpose of this memo is to define the standard expression of SMI base datatypes in XML documents that is both uniform and interoperable 🎀. This helps Internet operators, management app developers, and users tap a wider range of management tools and a greater degree of unified management 🌈. So standard expression makes management info more timely, accurate, and useful ✨.

The overall goal of this memo, and any related future memos, is to define the XSD equivalent [XSDDatatypes] of SMIv2 (STD 58). It also aims to encourage XML-based protocols to carry, and XML-based apps to use, the management info in SMIv2-compliant MIB modules 💅. A standard SMIv2-to-XML mapping through XSD validation makes it easier to reuse existing and future MIB modules and instrumentation in XML-based protocols and management apps 🫶.

Some XML management devs will find this spec is enough for them 🙌. Others may need fuller reuse of existing MIB modules, which means standard XSD documents for TCs [RFC2579] and MIB structure [RFC2578]. Memos supporting those needs are planned, but they hadn't been produced at the time of writing 🕰️.

Finally, fidelity to the SMIv2 standard (STD 58), as specified in the "Requirements" section below, is crucial to this effort 🔥. Fidelity builds on the established "rough consensus" of the precise SMIv2 data models in MIB modules. It also leans on existing instrumentation, the "running code" that implements SMIv2 data models 💜. This effort doesn't redesign SMIv2 datatypes, data structures, or textual conventions to overcome known limitations. Other efforts can pick that up 🦋.

2. Conventions 💅

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are meant to be read exactly as RFC 2119 [RFC2119] describes 📖.

3. Requirements 📋

This set of requirements exists to produce XML documents that can be validated against the XSD in this spec. Those documents should faithfully represent values carried "on-the-wire" in SNMP PDUs, as the SMI defines them 🧠.

  • R1. All SMI base datatypes MUST have a corresponding XSD datatype 💯.
  • R2. SMIv2 is the normative SMI for this document. Before mapping datatypes into XSD, legacy SMIv1 modules MUST be converted (at least logically) in accordance with Section 2.1, inclusive, of the "Coexistence" RFC [RFC3584] 🧹.
  • R3. The XSD datatype specified for a given SMI datatype MUST be able to represent all valid values for that SMI datatype 🫧.
  • R4. The XSD datatype specified for a given SMI datatype MUST represent any special encoding rules associated with that SMI datatype 🎁.
  • R5. The XSD datatype specified for a given SMI datatype MUST include any restrictions on values associated with the SMI datatype 🚧.
  • R6. The XSD datatype specified for a given SMI datatype MUST be the most logical XSD datatype, with the fewest necessary restrictions on its set of values, consistent with the foregoing requirements 👑.
  • R7. The XML output produced as a result of meeting the foregoing requirements SHOULD be the most coherent and succinct representation (i.e., avoiding superfluous "decoration") from the perspective of readability by humans 🌷.

4. XSD for SMI Base Datatypes ✨

okay so this section is where we get the XSD datatype mappings for the SMIv2 base datatypes 💖 and it's ONLY these ones: the eleven "ObjectSyntax" datatypes from RFC 2578. SMIv2 uses tag values to identify them in varbinds, and they constrain the values that travel "on-the-wire" in SNMP PDUs between management apps and agents 🫶 the full squad:

  • INTEGER, Integer32
  • Unsigned32, Gauge32
  • Counter32
  • TimeTicks
  • Counter64
  • OCTET STRING
  • Opaque
  • IpAddress
  • OBJECT IDENTIFIER

The "BITS" pseudo-type (also called a "construct" in RFC 2578) is treated as a Textual Convention and NOT a base datatype for this document, so it's not in the list 🙈

BEGIN

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:smi:base:1.0"
targetNamespace="urn:ietf:params:xml:ns:smi:base:1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en">

  <xs:annotation>
    <xs:documentation>
        Mapping of SMIv2 base datatypes from RFC 2578

        Contact:      Mark Ellison
        Organization: Ellison Software Consulting
        Address:      38 Salem Road
                      Atkinson, NH 03811
                      USA
        Telephone:    +1 603-362-9270
        E-Mail:       ietf@EllisonSoftware.com

        Contact:      Bob Natale
        Organization: MITRE
        Address:      300 Sentinel Drive
                      6th Floor
                      Annapolis Junction, MD 20701
                      USA
        Telephone:    +1 301-617-3008
        E-Mail:       rnatale@mitre.org

        Last Updated: 201002260000Z

        Copyright (c) 2010 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).

        This version of this XML Schema Definition (XSD)
        document is part of RFC 5935; see the RFC itself for
        full legal notices.

    </xs:documentation>

  </xs:annotation>

  <xs:simpleType name="INTEGER">
    <xs:restriction base="xs:int"/>
  </xs:simpleType>

  <xs:simpleType name="Integer32">
    <xs:restriction base="xs:int"/>
  </xs:simpleType>

  <xs:simpleType name="Unsigned32">
    <xs:restriction base="xs:unsignedInt"/>
  </xs:simpleType>

  <xs:simpleType name="Gauge32">
    <xs:restriction base="xs:unsignedInt"/>
  </xs:simpleType>

  <xs:simpleType name="Counter32">
    <xs:restriction base="xs:unsignedInt"/>
  </xs:simpleType>

  <xs:simpleType name="TimeTicks">
    <xs:restriction base="xs:unsignedInt"/>
  </xs:simpleType>

  <xs:simpleType name="Counter64">
    <xs:restriction base="xs:unsignedLong"/>
  </xs:simpleType>

  <xs:simpleType name="OctetString">
    <xs:restriction base="xs:hexBinary">
      <xs:maxLength value="65535"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="Opaque">
    <xs:restriction base="xs:hexBinary"/>
  </xs:simpleType>

  <xs:simpleType name="IpAddress">
      <xs:restriction base="xs:string">
          <xs:pattern value=
          "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}
             ([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])"/>
      </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="ObjectIdentifier">
    <xs:restriction base="xs:string">
      <xs:pattern value=
      "(([0-1](\.[1-3]?[0-9]))|
        (2\.(0|([1-9]\d*))))
        (\.(0|([1-9]\d*))){0,126}"/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

END

5. Rationale 🎀

the XSD datatypes (restrictions included) were picked because they fit the requirements from earlier in this doc, while keeping things simple AND staying faithful to the SMI. the "canonical representations" (basically the refined version of the "lexical representations") from the W3C XSD specs [XMLSchema], [XSDDatatypes] are assumed too. it's giving well-organized 💅

5.1. Numeric Datatypes

all the numeric XSD datatypes from the previous section (INTEGER, Integer32, Unsigned32, Gauge32, Counter32, TimeTicks, and Counter64) comply with the relevant requirements, and here's how:

  • they cover all valid values for the matching SMI datatypes.
  • they follow the standard encoding rules for the matching SMI datatypes.
  • they inherently match the range restrictions for the matching SMI datatypes.
  • they're the most direct XSD datatypes with those traits compared to the SMI datatypes. that's why there are no "restriction" statements (other than the "base" XSD type) needed in the XSD 🌸
  • the XML output from their canonical representation is the most direct for humans to read too (no leading "+" sign and no leading zeros) ✨

special note for app developers 🔥: if your translation from the raw ("on-the-wire") SNMP MIB data is otherwise correct, this schema gives you values that are faithful to the original. BUT Gauge32, Counter32, Counter64, and TimeTicks have special application semantics, and you need to think about those whenever you use their raw values for anything other than displaying, printing, storing, or transmitting the literal value. RFC 2578 has the full details 🙈

5.2. OctetString

this XSD datatype corresponds to the SMI "OCTET STRING" datatype 🦋

a bunch of independent schemes have mapped SMI datatypes to XSD using the XSD "string" type for "OCTET STRING", but that mapping doesn't meet the requirements in this document. the big problem is that "string" can't faithfully represent all valid values (0 thru 255) that each octet in an "OCTET STRING" can have, or at least it can't do that in a way that's easy for humans to read in the resulting XML 💀

so the XSD datatype "hexBinary" is specified as the standard mapping for the SMI "OCTET STRING" datatype. in hexBinary, each octet is encoded as two hexadecimal digits, and the canonical representation limits the allowed hex digits to 0-9 and uppercase A-F.

the hexBinary representation of "OCTET STRING" complies with the relevant requirements:

  • it covers all valid values for the corresponding SMI datatype.
  • it complies with the standard encoding rules for the corresponding SMI datatype.
  • with the maxLength restriction set to 65535 octets, the XSD datatype matches the restrictions of the corresponding SMI datatype.
  • it's the most direct XSD datatype with those traits compared to the corresponding SMI datatype (which has to allow for any valid binary octet value).
  • the XML output from its canonical representation isn't optimal for human readability. BUT that's a consequence of the SMI datatype itself 😭 where humans need to read it more, the actual MIB objects will probably use textual conventions that limit which values show up in the OctetStrings, and that means they'll skip the hexBinary typing 🧚

5.3. Opaque

the "hexBinary" XSD datatype is the representation for the SMI "Opaque" datatype, generally for the same reasons "hexBinary" was picked for the "OctetString" datatype 💜

  • it covers all valid values for the corresponding SMI datatype.
  • it complies with the standard encoding rules for the corresponding SMI datatype.
  • there are no restriction issues when using "hexBinary" for "Opaque".
  • it's the most direct XSD datatype with those traits compared to the corresponding SMI datatype (which has to allow for any valid binary octet value).
  • the XML output from its canonical representation isn't optimal for human readability. again, that's a consequence of the SMI datatype itself. unmediated "Opaque" data is meant for apps to consume, not humans 🤖

5.4. IpAddress

the XSD "string" datatype is the natural pick for representing an IpAddress as XML output 🍓 the "pattern" restriction gives you a dotted-decimal string of four values between "0" and "255", separated by a period (".") character. the pattern also rules out leading zeros 🫶

heads up though: the SMI uses Textual Conventions (TCs) to specify an IPv6 address, so representing an IPv6 address as an XSD datatype is OUT of scope for this document 🙅‍♀️

5.5. ObjectIdentifier

this XSD datatype corresponds to the SMI "OBJECT IDENTIFIER" datatype 👑

the XSD "string" datatype is also the natural choice for representing an ObjectIdentifier as XML output, for the same reasons as the IpAddress choice. the "pattern" restriction gives you a dotted-decimal string of up to 128 elements (called "sub-ids"), and each one holds an "Unsigned32" integer value 🌈

the first two components of an "OBJECT IDENTIFIER" each have a limited range of values, as shown in the XSD pattern restriction and described in the ASN1.1/BER standard [ASN.1] 🧠

there are three values allocated for the root node, and at most 39 values for nodes under a root node value of 0 or 1 ⭐

the minimum length of an "OBJECT IDENTIFIER" is two sub-ids, and a zero-valued "OBJECT IDENTIFIER" is represented as "0.0" 💖

no explicit "minLength" restriction is needed. it would be "3" (two sub-ids plus a single separating dot), but the pattern already enforces that, so you don't need it 🎀

6. Security Considerations 🚨

security considerations for any given SMI MIB module will matter for any XSD/XML mapping of that MIB module. BUT the mapping defined in this document doesn't introduce any NEW security considerations on its own 🔒 bestie, this part is lowkey important.

if proxies or gateways get developed to carry SNMP management information from SNMP agents over to XML-based management applications through the XSD/XML mapping of MIB modules based on this spec and its planned siblings, you need to take SPECIAL care to make sure every applicable SNMP security mechanism is supported in an appropriate way. how that works is yet to be determined 😱 this is serious, so please don't skip it, periodt 💀

7. IANA Considerations 🦋

following RFC 3688 [RFC3688], the IANA XML registry got updated with these namespace and schema registrations for this document:

  • urn:ietf:params:xml:ns:smi:base:1.0
  • urn:ietf:params:xml:schema:base:1.0

7.1. SMI Base Datatypes Namespace Registration

this document registers a URI for the SMI Base Datatypes XML namespace in the IETF XML registry. following the RFC 3688 format, IANA made this registration:

URI: urn:ietf:params:xml:ns:smi:base:1.0

Registration Contact: The IESG.

XML: N/A, the requested URI is an XML namespace. 🫶

7.2. SMI Base Datatypes Schema Registration ✨

okay so this one is the schema's official ID card 🪪 This document registers a URI for the SMI Base Datatypes XML schema in the IETF XML registry, and the format follows [RFC3688] (the IETF XML Registry itself). IANA made this registration:

  • URI: urn:ietf:params:xml:schema:smi:base:1.0 🎀
  • Registration Contact: The IESG.
  • XML: Section 4 of this document. 🧚

8. Acknowledgements 🫶

Shoutout to Dave Harrington, who gave strategic and technical leadership to the team that built this spec 👑 and to Yan Li, who did a ton of research into existing approaches. Those findings became the baseline for the recommendations here. Literally so much respect.

This document owes a lot to "Datatypes for Netconf Data Models" [NETCONF-DATATYPES] and to plenty of other sources (libsmi and the NETCONF mailing list discussions included) 💜 Everyone who researched and published candidate mappings of SMI datatypes to XSD gets a huge thank you.

Then there's the long list of people who joined the discussions about this topic at IETF meetings and on IETF mailing lists. They are: Ray Atarashi, Yoshifumi Atarashi, Andy Bierman, Sharon Chisholm, Avri Doria, Rob Ennes, Mehmet Ersue, David Harrington, Alfred Hines, Eliot Lear, Chris Lonvick, Faye Ly, Randy Presuhn, Juergen Schoenwaelder, Andrea Westerinen, and Bert Wijnen. The whole squad 🌈

9. References 📚

9.1. Normative References

These are the must-reads that the spec depends on:

[RFC1155]  Rose, M. and K. McCloghrie, "Structure and identification
           of management information for TCP/IP-based internets",
           STD 16, RFC 1155, May 1990.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2578]  McCloghrie, K., Ed., Perkins, D., Ed., and J.
           Schoenwaelder, Ed., "Structure of Management Information
           Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.

[RFC3584]  Frye, R., Levi, D., Routhier, S., and B. Wijnen,
           "Coexistence between Version 1, Version 2, and Version 3
           of the Internet-standard Network Management Framework",
           BCP 74, RFC 3584, August 2003.

[XML]      World Wide Web Consortium, "Extensible Markup Language
           (XML) 1.0", W3C XML, February 1998,
           <http://www.w3.org/TR/1998/REC-xml-19980210>.

[XMLSchema]
           World Wide Web Consortium, "XML Schema Part 1: Structures
           Second Edition", W3C XML Schema, October 2004,
           <http://www.w3.org/TR/xmlschema-1/>.

[XSDDatatypes]
           World Wide Web Consortium, "XML Schema Part 2: Datatypes
           Second Edition", W3C XML Schema, October 2004,
           <http://www.w3.org/TR/xmlschema-2/>.

9.2. Informative References

These are the nice-to-know extras 🌸

[ASN.1]    International Organization for Standardization,
           "Information processing systems - Open Systems
           Interconnection - Specification of Basic Encoding Rules
           for Abstract Syntax Notation One (ASN.1)", International
           Standard 8825, December 1987.

[NETCONF-DATATYPES]
           Romascanu, D., "Datatypes for Netconf Data Models", Work
           in Progress, May 2007.

[RFC2579]  McCloghrie, K., Perkins, D., and J. Schoenwaelder,
           "Textual Conventions for SMIv2", STD 58, RFC 2579,
           April 1999.

[RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
           January 2004.

[RFC4001]  Daniele, M., Haberman, B., Routhier, S., and J.
           Schoenwaelder, "Textual Conventions for Internet Network
           Addresses", RFC 4001, February 2005.

Authors' Addresses 💌

The people who wrote this, and how to reach them:

Mark Ellison
Ellison Software Consulting
38 Salem Road
Atkinson, NH  03811
USA

Phone: +1 603-362-9270
EMail: ietf@ellisonsoftware.com


Bob Natale
MITRE
300 Sentinel Drive
6th Floor
Annapolis Junction, MD  20701
USA

Phone: +1 301-617-3008
EMail: rnatale@mitre.org

That's the whole spec, bestie! 🌈✨ Two legends, Mark and Bob, wrote it, and it's literally the reason SMI datatypes look the way they do in XML 💅🦋

📦 where this page comes from