Transformer Developer Guide

Transformer Developer Guide

Welcome to the Transformer developer guide. The document shows you how to define the translation hints with YANG extensions and write special translation codes using APIs in the Transformer framework. If you are brand new to Translib/Transformer, start with the HLD

Transformer provides an underlying building block for developers to translate data from YANG to ABNF/Redis schema and vice versa, using YANG extensions along the YANG paths. At run time, the YANG extensions are mapped to an in-memory Transformer Spec that provides two-way mapping between YANG and ABNF/Redis schema for Transformer to perform data translation while processing SET/GET operations.

In case that SONiC YANG modules are used by NBI applications, the Transformer performs 1:1 mapping between a YANG object and a SONiC DB object without a need to write special translation codes.

If you use the openconfig YANGs for NBI applications, you may need special handling to translate data between YANG and ABNF schema. In such case, you can annotate YANG extensions and write callbacks to perform translations where required.

In either case, the default application - common-app.go - generically handles both SET and GET requests with data translated by Transformer. Please refer to the appendix - sequence diagram that shows interactions within Translib.  

1. Generate the annotation template file

The goyang package is extended to generate the template annotation file for any input yang files. A new output format type "annotate" can be used to generate the template annotation file.

Add $(SONIC_MGMT_FRAMEWORK)/gopkgs/bin to the PATH to run the goyang binary.

goyang --format=annotate --path=/path/to/yang/models openconfig-acl.yang > openconfig-acl-annot.yang

Sample output: module openconfig-acl-annot {

yang-version "1"

namespace "http://openconfig.net/yang/annotation";
prefix "oc-acl-annot"

import openconfig-packet-match { prefix oc-pkt-match }
import openconfig-interfaces { prefix oc-if }
import openconfig-yang-types { prefix oc-yang }
import openconfig-extensions { prefix oc-ext }

deviation oc-acl:openconfig-acl {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl/oc-acl:state {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl/oc-acl:state/oc-acl:counter-capability {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl/oc-acl:acl-sets {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl/oc-acl:acl-sets/oc-acl:acl-set {
  deviate add {
  }
}

deviation oc-acl:openconfig-acl/oc-acl:acl/oc-acl:acl-sets/oc-acl:acl-set/oc-acl:type {
  deviate add {
  }
}

2. Annotate YANG extensions to define translation hints

The translation hints can be defined as YANG extensions to support simple table/field name mapping or more complex data translation by overloading the default methods.

Extensions	Usage
sonic-ext:table-name [string]	Map a YANG container/list to TABLE name
sonic-ext:field-name [string]	Map a YANG leafy to FIELD name
sonic-ext:key-delimiter [string]	Override the default delimiter, “|”
sonic-ext:key-transformer [function]	Overloading default method for key generation
sonic-ext:field-transformer [function]	Overloading default method for field generation
sonic-ext:subtree-transformer [function]	Overloading default method for the current subtree, including all descendant nodes
sonic-ext:get-transformer [function]	Overloading default method to access data hosted in different DB – APPL_DB, COUNTER_DB etc.

e.g.

deviation /oc-acl:acl/oc-acl:acl-sets/oc-acl:acl-set {
      deviate add {
        sonic-ext:table-name "ACL_TABLE";
        sonic-ext:key-delimiter "_";
      }
    }

deviation /oc-acl:acl/oc-acl:acl-sets/oc-acl:acl-set/oc-acl:acl-entries/oc-acl:acl-entry/oc-acl:actions/oc-acl:config/oc-acl:forwarding-action {
      deviate add {
        sonic-ext:field-name "PACKET_ACTION";
      }
    }

deviation /oc-acl:acl/oc-acl:interfaces {
      deviate add {
        sonic-ext:subtree-transformer "acl_port_bindings_xfmr";
      }
    }