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 {
  }
}