Menu

YANG Guidelines

 

YANG Guidelines

  • IETF RFC 8407:  https://tools.ietf.org/html/rfc8407
  • YANG prefixes in IEEE published YANG: YANG Prefixes | (ieee802.org)
    • Use prefixes to shorten names for YANG artefacts, module names, and prefixes.
  • Type modules
    • Introduce a separate module for typedefs/enumerations/identities only when the artifacts are needed by other YANG modules (not the module that defines the capability)
    • Default to keeping the typedefs in the module
  • The ABNF for YANG is found in RFC 7950 section 14. https://tools.ietf.org/html/rfc7950#section-14
  • YANG identifiers (which applies to all named items in YANG, for example leaf or grouping names) must start with a letter in the range of A-Z or a-z or an underscore “_”.
    • Identifiers are written in lower-kebab-case, meaning all lower case letter separated with dash “-“.
    • Identifier length must be between 1 and 64 characters in length (RFC 8407 section 4.3)
  • Well known acronyms and abbreviations are allowed (see table pulled from existing IEEE published YANG: YANG Abbreviations or Acronyms | (ieee802.org))
  • Don’t use the node type in the identifier (for example: don’t use _type for types or _list for lists)
  • Groupings
    • Do not create groupings if the group of leaf/lists are used in only one place.
  • Use enumerations when the list of options is static, use Identity when there is a need to expand the list of options.
  • Description sub-statements are required in some places and strongly suggested in others.  Also yanglint checks and reports if description sub-statement is missing.  See RFC 8407.
  • Reference sub-statement
    • Short name of the standard is acceptable (ex. IEEE Std 802.1CB-2017)
    • If referencing a top-level clause use the word Clause (ex. Clause 8 of IEEE Std 802.1AB-2016), if not referencing a top-level clause don’t use the work Clause (ex. 8.5.2.3 of IEEE Std 802.1AB-2016)
    • If using clause numbers and if they are in the same spec separate by commas (ex. 8.5.2.3, 8.5.2.4 of IEEE Std 802.1AB-2016)
    • Multiple references from different standards on separate lines with no commas
  • Type mapping: RFC 6643 – Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG Modules (ietf.org)
  • How to link .1Q amendments into .1Q:
    • Augment when you can, reference when you must.
    • The conditions for “use a reference when you must” are, either:
      • When there is a many to one mapping.
        • For example when an augmentation can be applied to multiple interfaces (interface instances that is, differences in type before augmentation not relevant) but some common configuration element/table/object is to be used by all those interfaces.
      • When there is a dynamic mapping.
        • For example when an interface augmentation needs to have data that is necessarily present elsewhere (i.e. not in the augmentation itself or in the interface being augmented) but the details of the “elsewhere” can change even if condition (a) does not apply. There may be (in this
          example) two cases:
          • The elsewhere can change because rearranging the “elsewhere” can make management easier (I have a case in the link aggregation I am thinking about). This is run time dynamic.
          • The elsewhere can change because different types of system can have a different type of “elsewhere”. This implies that the different “elsewheres” support the same “methods” (in an object oriented sense) and may be a stretch for YANG. This is link time (boot?) dynamic.
Sidebar