Eclipse Community Forums: Eclipse Titan » TTCN-3 and JSON encoding part 1

Help

Home

Home » Eclipse Projects » Eclipse Titan » TTCN-3 and JSON encoding part 1(Schemas and instances)

Show: Today's Messages :: Show Polls :: Message Navigator

TTCN-3 and JSON encoding part 1 [message #1726428]

Sun, 13 March 2016 13:31

Elemer Lelik

Messages: 1120
Registered: January 2015

Senior Member

For reasons that will become apparent soon, I will introduce JSON encoding principles for TTCN-3 by referring to XML schemas.
XML schemas are the conceptual equivalent of TTCN-3 type definitions: they describe information structures based on which instances of such structures can be derived, such instances can be validated against etc.
In case of XML schemas instances are often referred to as documents, in TTCN-3 these can be variables, templates or constants.
As the two abstractions are not exactly equivalent, some structural information in XML schemas (XSD files) can be translated directly into TTCN-3 structures, but some information can be retained only in form of additional encoding information,
the intention being that from the TTCN-3 structures and encoding information we generate an XML instance that validates against the schema used as starting point. Ultimately, as the result of conversion, we will be able to communicate with an SUT using XML-based messages: we can decode such messages and verify them with TTCN-3s powerful template matching mechanism, and also encode TTCN-3 variables, templates etc. into well-formed (syntactically sound) and valid( verifiable against the schema) XML.
All elements of the above-described conversion are well-known and standardized: XML schemas by W3C, mapping to TTCN-3 by ETSI ( see Part 9: Using XML schema with TTCN-3 ).

However , for JSON , which is a data interchange format similar to XML, situation is not that simple: JSON is widely popular, but the idea of a JSON schema is rejected by the greater part of JSON users. Although the JSON schema exists, and it is technically sound, it is represented by an expired IETF draft only (http://json-schema.org/, http://tools.ietf.org/html/draft-zyp-json-schema-04). On the other hand, for all practical purposes, JSON schema is an efficient and elegant way of sharing structural information about messages used on an API, in similarity with the XML schema.
Whatever I have said above about XML to TTCN-3 mapping applies to JSON as well, with one difference: JSON representation is arguably simpler( less overhead, better readability) than XML.

JSON-TTCN mapping can go both ways: we can share API information of a Titan interface in which case we will need TTCN-3 to JSON mapping, or we can share API information of an SUT with Titan, in which case we need to convert a JSON schema to TTCN-3 (the same goes for XML by the way; however exposing a Titan interface in XML did not seem a practical idea and it was never implemented). This practically means that we can convert a JSON schema to TTCN-3 types (plus encoding instructions wherever necessary) , or we can convert TTCN-3 types (and possibly encoding instructions) into JSON schema.

Invoking external functions from Titan is usually possible via the C API, which can be used to call Python, C/C++, Java etc. functions. The opposite direction (e.g. calling Titan functions from Python) is not so straightforward though, as Titan does not have an API to support this. A language agnostic JSON based interface is a possible answer. Such an interface can also be used to create hybrid (TTCN-3/Java or TTCN-3/Python) architectures. An example of hybrid architecture could be a JavaScript GUI fronting a Titan execution engine.

If we approach the above from a testing point of view, JSON schema to TTCN-3 mapping should look more useful, but due to the reluctance of JSON users to use schema, and due to the simplicity of JSON messages, we did not yet implement that direction: it's a rather simple mental exercise to find the TTCN-3 type equivalent that can describe JSON messages; however, we are working on a conversion tool (similar to the xsd2ttcn converter part of the Titan package) that should be out soon.

Therefore here we are going to talk about the TTCN-3 to JSON schema direction only, which has been implemented as part of the compiler
and it is described in detail in the ch 4.26.4 Converting TTCN-3 and ASN.1 types to a JSON schema of the reference guide.
As in JSON schema there is no support for include or import, multiple TTCN-3 (or ASN.1 ) files will result in a single (possibly quite large) JSON schema. Each TTCN-3/ASN.1 type declaration will contribute with a segment to this schema. TTCN-3 types (but not ASN.1 types) can be decorated with additional instructions that will affect the result.
The compiler option --ttcn2json shall be used for the conversion, followed by JSON schema generator specific options and the list of TTCN-3 and ASN.1 file names. The conversion can be restricted to types which are marked as possible subjects of JSON encoding, either on the type declaration itself or on the module containing the type. ASN.1 types cannot be restricted and will always be converted.
The JSON schema will be generated according to the rules of the IETF draft v4.
Whenever needed, metainformation is generated and added to the schema to retain structural information present in TTCN-3 but lost in schema without this.

As an example, the following TTCN-3 module:

module MyModule {
 
type record ProtocolResponse 
{
integer    sessionId,
integer    resultCode 

}

type charstring ProtocolRequest;


external function f_enc(in ProtocolRequest req) return octetstring
with { extension "prototype(convert) encode(JSON)" }
external function f_dec(in octetstring ostr) return ProtocolResponse
with { extension "prototype(convert) decode(JSON)" }
} 
with {
encode "JSON"
}

will result the JSON schema below:

{
   "$schema":"http://json-schema.org/draft-04/schema#",
   "definitions":{
      "MyModule":{
         "ProtocolRequest":{
            "type":"string",
            "subType":"charstring"
         },
         "ProtocolResponse":{
            "type":"object",
            "subType":"record",
            "properties":{
               "sessionId":{
                  "type":"integer"
               },
               "resultCode":{
                  "type":"integer"
               }
            },
            "additionalProperties":false,
            "fieldOrder":[
               "sessionId",
               "resultCode"
            ],
            "required":[
               "sessionId",
               "resultCode"
            ]
         }
      }
   },
   "anyOf":[
      {
         "$ref":"#/definitions/MyModule/ProtocolResponse",
         "decoding":{
            "prototype":[
               "convert",
               "f_dec",
               "ostr"
            ]
         }
      },
      {
         "$ref":"#/definitions/MyModule/ProtocolRequest",
         "encoding":{
            "prototype":[
               "convert",
               "f_enc",
               "req"
            ]
         }
      }
   ]
}

This could be used as a description of a simple messaging interface between Titan and an external component;
documenting the interface would largely mean sharing the above schema.

Next , we will look into generating JSON instances based on TTCN-3 types (encoding)
and the opposite, decoding JSON instances into TTCN-3 variables.

Best regards

Elemer

[Updated on: Sat, 19 March 2016 15:45]

Report message to a moderator