ETSI ES 201 873-11 V4.9.1 (2021-06)
Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; Part 11: Using JSON with TTCN-3
Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; Part 11: Using JSON with TTCN-3
RES/MTS-201873-11 v4.9.1
Metode za preskušanje in specificiranje (MTS) - 3. različica zapisa preskušanja in krmiljenja preskusov - 11. del: Uporaba JSON v TTCN-3
General Information
Standards Content (Sample)
Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
ETSI STANDARD
Methods for Testing and Specification (MTS);
The Testing and Test Control Notation version 3;
Part 11: Using JSON with TTCN-3
2 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
Reference
RES/MTS-201873-11 v4.9.1
Keywords
JSON, language, testing, TTCN-3
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88
Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2021.
All rights reserved.
DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.
3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and
of the oneM2M Partners. ®
GSM and the GSM logo are trademarks registered and owned by the GSM Association.
ETSI
3 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 6
3 Definition of terms, symbols and abbreviations . 7
3.1 Terms . 7
3.2 Symbols . 7
3.3 Abbreviations . 7
4 Introduction . 8
5 Conformance and compatibility . 8
6 Using TTCN-3 as JSON Schema . 9
6.1 Approach . 9
6.2 Validation of JSON Values . 9
6.3 Name conversion rules . 9
6.4 Mapping of JSON Values . 10
6.4.1 JSON Numbers . 10
6.4.2 JSON Strings . 11
6.4.3 JSON Arrays . 12
6.4.4 JSON Objects. 13
6.4.5 JSON Literals. 15
7 Using JSON to exchange data between TTCN-3 and other systems . 16
7.1 General rules . 16
7.2 JSON representations of TTCN-3 values . 17
7.2.1 Character strings . 17
7.2.2 Binary Strings . 17
7.2.3 Integer . 17
7.2.4 Float . 18
7.2.5 Boolean . 18
7.2.6 Enumerated . 18
7.2.7 Verdicttype . 19
7.2.8 Record and set . 19
7.2.9 Record of, set of and arrays . 20
7.2.10 Union and anytype . 21
7.2.11 Object Identifiers . 22
8 JSON representations of TTCN-3 values based on ASN.1 types . 22
8.1 General rules . 22
8.2 Character strings . 23
8.3 Binary strings . 23
8.4 BOOLEAN . 23
8.5 ENUMERATED . 23
8.6 REAL . 23
8.7 INTEGER . 23
8.8 OBJID . 23
8.9 NULL . 23
8.10 SEQUENCE and SET . 24
8.11 SEQUENCE OF and SET OF . 24
8.12 CHOICE and Open Types . 24
Annex A (normative): TTCN-3 module JSON . 25
ETSI
4 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
Annex B (normative): Encoding instructions . 27
B.1 General . 27
B.2 The JSON encode attribute . 27
B.3 Encoding instructions . 27
B.3.1 General rules . 27
B.3.2 JSON type identification . 28
B.3.3 Normalizing JSON Values . 28
B.3.4 Name as . 28
B.3.5 Number of fraction digits . 29
B.3.6 Use the Minus sign . 30
B.3.7 Escape as . 30
B.3.8 Omit as null . 31
B.3.9 Default . 31
B.3.10 As value . 32
B.3.11 No Type . 33
B.3.12 Use order . 33
B.3.13 Error behaviour . 33
Annex C (informative): Bibliography . 35
History . 36
ETSI
5 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (https://ipr.etsi.org/).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
Foreword
This final draft ETSI Standard (ES) has been produced by ETSI Technical Committee Methods for Testing and
Specification (MTS), and is now submitted for the ETSI standards Membership Approval Procedure.
The present document is part 11 of a multi-part deliverable. Full details of the entire series can be found in part 1 [1].
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
6 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
1 Scope
The present document specifies the rules to define schemas for JSON data structures in TTCN-3, to enable testing of
JSON-based systems, interfaces and protocols, and the conversion rules between TTCN-3 [1] and JSON [2] to enable
exchanging TTCN-3 data in JSON format between different systems.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference/.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] ETSI ES 201 873-1: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 1: TTCN-3 Core Language". ®
[2] IETF RFC 7159: "The JavaScript Object Notation (JSON) Data Interchange Format".
NOTE: Available at http://www.rfc-editor.org/rfc/rfc7159.txt.
[3] ISO/IEC 10646:2017: "Information technology -- Universal Coded Character Set (UCS)".
NOTE: Available at https://www.iso.org/standard/69119.html.
TM
[4] IEEE 754 : "IEEE Standard for Floating-Point Arithmetic".
[5] ETSI ES 201 873-7: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 7: Using ASN.1 with TTCN-3".
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area. ®
draft-handrews-json-schema-validation-00: "JSON Schema Validation: A Vocabulary for
[i.1] IETF
Structural Validation of JSON".
NOTE: Available at https://datatracker.ietf.org/doc/draft-handrews-json-schema. ®
[i.2] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 1: Structures".
NOTE: Available at http://www.w3.org/TR/xmlschema11-1.
ETSI
7 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03) ®
[i.3] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/xmlschema11-2.
[i.4] ETSI ES 201 873-8: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 8: The IDL to TTCN-3 Mapping".
[i.5] ETSI ES 201 873-9: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 9: Using XML schema with TTCN-3".
[i.6] ETSI ES 202 781: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Configuration and Deployment Support".
[i.7] ETSI ES 202 782: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance and Real Time Testing".
[i.8] ETSI ES 202 784: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Advanced Parameterization".
[i.9] ETSI ES 202 785: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Behaviour Types".
[i.10] ETSI ES 202 786: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Support of interfaces with continuous signals".
[i.11] ETSI ES 202 789: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Extended TRI".
[i.12] ETSI ES 203 022: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language extension: Advanced Matching".
[i.13] ETSI ES 203 790: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Object-Oriented Features".
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the terms and definitions given in ETSI ES 201 873-1 [1] apply.
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ASN.1 Abstract Syntax Notation One
IO ASN.1 Information Object
JSON JavaScript Object Notation
SUT System Under Test
TTCN-3 Testing and Test Control Notation version 3
UCS Universal Coded Character Set
USI UCS Sequence Identifier
UTF-8 Unicode Transformation Format-8
XML eXtensible Markup Language
XSD XML Schema Definition
ETSI
8 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
4 Introduction
An increasing number of distributed applications use the JSON to exchange data for various purposes like data bases
queries or updates or event telecommunications operations such as provisioning. The JSON specification [2] defines the
syntax and encoding for JSON types and defined literals, but no semantics is defined. JSON does not have a schema
specification, like the XML Schema Definition Language used for XML documents (see [i.2] and [i.3]).
NOTE: Though an IETF draft proposal exists for JSON structural validation (see [i.1]), it has not reached the
RFC status.
The core language of TTCN-3 is defined in ETSI ES 201 873-1 [1] and provides a full text-based syntax, static
semantics and operational semantics. Other parts of the ETSI ES 201 873 series are defining its use with other
specification languages like ASN.1 [5], IDL [i.4], or XSD [i.5] as shown in figure 1, while other documents as ETSI
ES 202 781 [i.6], ETSI ES 202 782 [i.7], ETSI ES 202 784 [i.8], ETSI ES 202 785 [i.9], ETSI ES 202 786 [i.10],
ETSI ES 202 789 [i.11], ETSI ES 203 022 [i.12] and ETSI ES 203 790 [i.13] specify language extensions and thus can
define additional rules to the JSON/TTCN-3 mapping defined in the present document.
Configuration Advanced OO
Advanced Behavior Performance Continuous TTCN-3
…
and deploy-
Matching Features
Parameteri- Types and Real signals Packages
ment support
zation Time Testing
ASN.1 types
and values
IDL types
TTCN-3
XML types
Core
TTCN-3 User
Language
JSON types
& values
The shaded boxes are not
defined in this document
Other types &
values
Figure 1: User's view of the core language and its packages
In the context of TTCN-3, JSON can be used for different purposes:
1) TTCN-3 can be used as a JSON Schema definition language that allows generating JSON values from
TTCN-3 and consuming and evaluating received JSON values, i.e. enables testing of JSON-based interfaces
and protocols.
2) To exchange type and data information between the TTCN-3 test system and systems written in other
languages like Java, C, C++, Python, etc. In this way TTCN-3 test systems can be used as a subsystem of a
more complex test system; for example, the TTCN-3 system receiving contents of messages to be sent to an
SUT, encode and send a message, receive and process the response and report the result to the other system.
Consequently, there is a need to specify mappings between JSON and TTCN-3 for the above purposes.
5 Conformance and compatibility
For an implementation claiming to support the use of TTCN-3 as a JSON schema language, all features specified in
clause 6 of the present document shall be implemented consistently with the requirements given in clause 6 and
Annex B of the present document and in ETSI ES 201 873-1 [1].
ETSI
9 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
For an implementation claiming to support the exchange of TTCN-3-based data between systems, and not supporting
using ASN.1 with TTCN-3, all features specified in clause 7 of the present document, with the exception of the
mapping of the objid type in clause 7.2.11 shall be implemented consistently with the requirements given in clause 7
and Annex B of the present document and in ETSI ES 201 873-1 [1]. Implementations claiming the support of using
ASN.1 with TTCN-3, shall in addition support features in clause 7.2.11 and clause 8 of the present document.
The language mappings presented in the present document is compatible to:
• ETSI ES 201 873-1 [1], version 4.9.1.
If later versions of those parts are available and should be used instead, the compatibility of the rules presented in the
present document shall be checked individually.
6 Using TTCN-3 as JSON Schema
6.1 Approach
JSON [2] defines a limited set of JSON types and literal values. The clauses below define the TTCN-3 types that can be
used to specify a Schema for any JSON interface specification. The TTCN-3 types defined in the clauses below will
allow to use the same set of values as JSON permits. Annex A provides a TTCN-3 module containing all TTCN-3
definitions specified in these clauses. The JSON module in Annex A shall either explicitly be present in TTCN-3 test
suites or TTCN-3 tools shall support these types implicitly. This is left as a tool implementation option.
JSON in many cases allows different encoding options for the same value. These may be controlled by the JSON
encoding instructions specified in Annex B. JSON encoding instructions may be added to TTCN-3 types and fields by
using TTCN-3 variant attributes (see ETSI ES 201 873-1 [1], clause 27.5).
6.2 Validation of JSON Values
For further study.
6.3 Name conversion rules
The current version of the JSON specification [2] uses names to identify JSON object members only. The present
document defines JSON to TTCN-3 name conversion rules that shall be used when using TTCN-3 to specify a schema for
a JSON interface (see for example clause 6.4.4). When the JSON and the TTCN-3 names differ after applying the rules in
this clause, the "name as …" encoding instruction shall be used to identify the exact JSON name. To ensure compatibility
with future versions and automatic conversions, the rules specified in this clause should always be applied.
JSON names can be identical to TTCN-3 reserved words, can contain characters not allowed in TTCN-3 identifiers or
allowed to be identical, when the corresponding TTCN-3 names are required to be unique, in which case the JSON
names shall be processed by the rules below to obtain the corresponding TTCN-3 identifiers.
The following character substitutions shall be applied, in order that each character string being mapped to a TTCN-3
name, where each substitution (except the first) shall be applied to the result of the previous transformation:
a) any character except "A" to "Z" (Latin Capital Letter A to Latin Capital Letter Z), "a" to "z" (Latin Small
Letter A to Latin Small Letter Z), "0" to "9" (Digit Zero to Digit Nine), and "_" (Low Line) shall be removed;
b) a sequence of two or more "_" (Low Line) characters shall be replaced with a single "_" (Low Line);
c) "_" (Low Line) characters occurring at the beginning or at the end of the name shall be removed;
d) if a character string starts with a digit (Digit Zero to Digit Nine), it shall be prefixed with an "x" (Latin Small
Letter X) character;
e) if a character string is empty, it shall be replaced by "x" (Latin Small Letter X);
ETSI
10 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
f) if the TTCN-3 name being generated is identical to a previously generated TTCN-3 identifier in the same
scope, then a postfix shall be appended to the character string generated by the above rules. If a field name of a
TTCN-3 structured type is clashing with a type's name used in the same structured type, the field's name shall
be postfixed. The postfix shall consist of a "_" (Low Line) followed by an integer. This integer shall be the
least positive integer such that the new identifier is different from the identifier of any previously generated
identifier in the same scope (i.e. the first postfix applied by this mechanism is "_1"). TTCN-3 names that are
one of the TTCN-3 keywords (see clause A.1.5 of ETSI ES 201 873-1 [1]) or names of predefined functions
(see clause 16.1.2 of ETSI ES 201 873-1 [1]) after applying the postfix to clashing names, shall be suffixed by
a single "_" (Low Line) character.
6.4 Mapping of JSON Values
6.4.1 JSON Numbers
JSON numbers are represented as base 10 decimal digits containing a mandatory integer component that can be
prefixed with an optional minus sign, and can be followed by a fraction part, an exponent part or both. Leading zeros
are not allowed. JSON does not distinguish numbers based on their value sets like integers and reals, like other
languages do. No special values (as –infinity, infinity or NaN) are allowed.
In the general case, JSON numbers shall be mapped by using the following TTCN-3 type:
type float Number (!-infinity . !infinity) with {
variant "JSON:number"
}
When the JSON interface specification requires a number to conform to the IEEE 754 [4] floating-point number
specification, the IEEE 754 floats useful types of clause E.2.1.4 of ETSI ES 201 873-1 [1] can be used in the context of
JSON encoding, in which case, by default, the given useful type will constrain the value set and the encoding of the
JSON value according to this clause. The JSON encoding instructions in this case can be applied to fields of IEEE 754
useful types.
By default, i.e. without any encoding instruction applied, the form of the JSON representation of JSON.Number is a
tool implementation option (i.e. the number of fraction digits, using the exponent part, etc.)
To make defining JSON Schemas in TTCN-3 easier, the present document, in addition to the generic mapping of JSON
numbers, also specifies a TTCN-3 type that may be used where the interface specification allows only numbers without
the fraction and the exponent parts:
type integer Integer (-infinity . infinity) with {
variant "JSON:integer"
}
Attempts to decode a JSON number value with either a fraction or an exponent part or both into this JSON.Integer
type shall cause a decoding failure.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific instructions
shall be applicable to types and fields of JSON.Number and the IEEE 754 useful types:
• fractionDigits see clause B.3.5
• useMinus see clause B.3.6
NOTE: The beginning character of the exponent part can be both "e" and "E". This is not controlled by any of the
encoding instructions but left as a tool implementation option.
and to types and fields of JSON.Integer types:
• useMinus see clause B.3.6
ETSI
11 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
6.4.2 JSON Strings
A JSON string is a sequence of zero or more Unicode characters, enclosed in a pair of quotation mark characters (""",
char(U22)). Any characters may be escaped by the escape sequence: "\u", where represents four
hexadecimal digits, but the icharacters: quotation mark (""", char(U22)), reverse solidus ("\", char(U5C)) and all
C0 control characters (char(U0) through char(U1F)) shall be escaped.
Alternatively, the short, two-character escape sequences defined in table 1 can be used to escape some of the characters.
Table 1: Short character escape sequences
Character's name Character code Short escape
sequence
char(U22)
quotation mark \"
char(U5C)
reverse solidus \\
char(U2F)
solidus \/
char(U8) \b
backspace
form feed char(UC) \f
char(UA)
line feed \n
char(UD)
carriage return \r
char(U9)
horizontal tab \t
By default, it is a tool implementation option which form of escaping is used, which may be overridden by the "escape
as …" encoding instruction.
NOTE 1: Note that the JSON module in Annex A defines useful TTCN-3 constants for the characters listed above.
The following TTCN-3 type shall be used to map JSON strings to TTCN-3:
type universal charstring String with {
variant "JSON:string"
}
NOTE 2: Though Unicode and ISO/IEC 10646 [3] do not necessarily contain the same set of characters at all points
in time, JSON strings are expressed using the TTCN-3 universal charstring type.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific encoding
instructions are applicable to JSON.String types:
• escape as … see clause B.3.7
EXAMPLE: String encoding examples
If:
const JSON.String c_string1 := with {variant "escape as short"};
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\\cd" 2261625C5C636422
"ab/cd" "ab\/d" 2261625C2F636422
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037
cu_ht & "cd" 5C74636422
If:
const JSON.String c_string1 := with {variant "escape as usi"};
ETSI
12 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\u005Ccd" 2261625C75303035
"ab/cd" "ab\u002Fcd" 2261625C7530303246636422 Escaped solidus character
(escaping solidus is
optional in JSON)
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\u0009c 2261625C7530303037
cs_ht & "cd" d" 5C7530303039636422
If:
const JSON.String c_string1 := with {variant "escape as transparent"};
then
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\cd" 2261625C636422 Note that the resulting
sequence is an invalid
JSON encoding
"ab/cd" "ab/cd" 2261622F636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037 Note that the BELL and HT
cs_ht & "cd" 5C74636422 C0 control characters are
escaped by the encoder
6.4.3 JSON Arrays
JSON arrays can contain a sequence of zero or more JSON values, i.e. the array members may be of different JSON
"types".
The following TTCN-3 type shall be used to map JSON arrays to TTCN-3:
type record of JSON.Values Array with {
variant "JSON:array"
},
Where:
type union Values {
JSON.String str,
JSON.Integer int,
JSON.Number num,
JSON.Object object,
JSON.StrArray strArray,
JSON.IntArray intArray,
JSON.NumArray numArray,
JSON.BoolArray boolArray,
JSON.ObjectArray objArray,
JSON.Array array,
JSON.Bool bool,
JSON.Null null_
} with {
variant "asValue"
}
To make specifying JSON Schemas easier for values, when according to the interface specification a specific array can
contain a sequence of values of the same JSON "type", also the TTCN-3 types below are specified:
NOTE: Use the below subsidiary types with due precaution. The syntax of TTCN-3 values based on the below
helper type differs from the syntax of a JSON.Array value. Therefore, changes in an array description
in a JSON interface specification can require changing the TTCN-3 code as well.
type record of JSON.String StrArray with {
variant "JSON:array"
}
ETSI
13 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
type record of JSON.Number NumArray with {
variant "JSON:array"
}
type record of JSON.Integer IntArray with {
variant "JSON:array"
}
type record of JSON.Boolean BoolArray with {
variant "JSON:array"
}
type record of JSON.Object ObjArray with {
variant "JSON:array"
}
Where JSON.Object is:
type record Object {
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object"
}
And:
type record ObjectMember {
JSON.String name, // shall contain an object member's name
JSON.Types value_ // shall contain an object member's value
} with {
variant "JSON:objectMember"
}
There is no type-specific encoding instruction defined for JSON.Array, JSON.StrArray, JSON.NumArray,
JSON.IntArray, JSON.BoolArray, JSON.ObjArray, in addition to the generic ones like "normalize" and
"name as …". In addition to the generic encoding instructions, the JSON.Types type uses the following instruction:
• asValue see clause B.3.10.
EXAMPLE: TTCN-3 Schema for a JSON array
Provided a JSON interface specification, allows a list of arbitrary JSON values e.g. as the value part of an object
member. Its TTCN-3 schemata will be:
type JSON.Array MyValue;
And e.g. the TTCN-3 value:
const MyValue c_myValue := {
{ str := "abcd" },
{ num := 1.0 },
{ int := 42 },
{ intArray := { 1, 2, 3, 4, 5, 6 },
{ null_ := null_ }
};
will be encoded in JSON e.g. as (character sequence):
["abcd", 1e0, 42, [ 1, 2, 3, 4, 5, 6 ], null ]
Note that as no additional instruction is specified for the "num" element, its encoding is a tool option.
6.4.4 JSON Objects
JSON object values consist of unordered sequences of zero or more object members, where each object member is
constructed of a name-value pair. The JSON specification IETF RFC 7159 [2] does not require uniqueness of object
member names within a JSON object.
ETSI
14 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
JSON object specifications should be translated to TTCN-3 record-s. The name of the record shall be the product of
applying clause 6.3 to the name of the object being translated, if this is specified, or be an arbitrary valid TTCN-3
identifier otherwise. The name of the type shall not be "Object", if this is the name of the JSON object being
translated, the postfixing rules specified in item f) of clause 6.3 shall be applied to it.
Each member of the object being converted shall generate a record field, where the name of the field shall be the
product of applying clause 6.3 to the name of the object member, but it shall not be "order": if this would be the name
of the TTCN-3 field, the postfixing rules specified in item f) of clause 6.3 shall be applied to it, as if it was preceded by
a field named order. The type of the field shall be a type defined in clause 6 of the present document, corresponding
to the JSON type (or literal values allowed) of the object member. If the object member can carry values of different
JSON types (or literals), the type of the field shall be a union of the TTCN-3 types required to represent all possible
values of the object member being translated, where the union field names shall be the names of the field's type with
lower cased first character.
Following this translation an optional TTCN-3 record of JSON.String field named order may be inserted
as the first field of the record, and an optional field named memberList of the type record length
(1.infinity) of JSON.ObjectMember shall be inserted as the last field of the record.
Possible name clashes caused by inserting the memberList field shall be resolved according to item f) of clause 6.3
with the exception that the additionally inserted field memberList shall be handled as if it was the first field of the
record (i.e. if an object member with the name "memberList" exists, the object member's name shall be postfixed).
Finally the "JSON:object" and if the order field is present the "useOrder" encoding instructions shall be attached to
the generated record type. Any other encoding instructions may be attached to the record fields, as necessary for a
correct translation.
The memberList field allows inserting any extra object members in instance definitions, and converters shall encode
each ObjectMember as member of the JSON object being produced. At JSON to TTCN-3 conversion JSON object
members, which cannot be decoded into any other field being produced from the member's name, shall be decoded as
element of the memberList field.
Use of the order field is specified in clause B.3.12.
NOTE: Note that attaching the optional "implicit omit" attribute to TTCN-3 values and templates implementing
object instances will allow skipping unused order and memberList fields in the instance definitions.
EXAMPLE: TTCN-3 Schema for a JSON object
Suppose that the specification defines a JSON object that shall carry the location information "Latitude",
"Longitude", which are floating point numbers and may carry the "Precision" and "Address" information, where
precision is to be provided as a number and the address is another JSON object containing the city, street and
house number information, where city and street are JSON strings, house number is an integer value.
The schema of this specification can be described in TTCN-3 e.g. as:
module MyObjectSchema {
import from JSON all;
type record Coordinates {
record of JSON.String order optional,
JSON.Number Latitude,
JSON.Number Longitude,
JSON.Number Precision optional,
Address Address_1 optional,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
variant "useOrder"
variant(Address_1) "name as 'Address'";
}
type record Address {
record of JSON.String order optional,
JSON.String city,
JSON.String street,
JSON.Integer house_no_,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
ETSI
15 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
variant "useOrder";
variant (house_no_) "name as 'house no.' "
}
} with { encode "JSON" }
And the TTCN-3 templates:
template Coordinates t_coordinates := {
Latitude := 51.523704,
Longitude := -0.158553,
Address_1 := t_address
} with { optional "implicit omit" }
template Address t_address := {
order := {"house_no_","subno","street","city"},
city := "London",
street := "Baker",
house_no_ := 221,
memberList := {{"subno",{str:="B"}}}
}
will be encoded in JSON as:
{"Latitude":51.523704,"Longitude":-0.158553,"Address":
{"house no.":221,"subno":"B","street":"Baker","city":"London"}}
There is no type-specific encoding instruction defined for JSON.Object, in addition to the generic ones like
"normalize" and "name as …".
6.4.5 JSON Literals
JSON specifies three literal values: true, false and null. These are mapped to the TTCN-3 types:
//When only the true and false literals are allowed
type boolean Bool with { variant "JSON:literal" }
//When only the null literal is allowed
type enumerated Null { null_ } with { variant "JSON:literal" }
NOTE: In the case if a JSON value could contain all three defined JSON literals, the user can define a union type
of the above types.
There is no type-specific encoding instruction defined for the above types mapping JSON literals, in addition to the
generic ones like "normalize" and "name as …".
EXAMPLE:
The TTCN-3 value:
const JSON.Bool c_true := true;
will be transformed to JSON e.g. as:
true
(its UTF-8 serialization is 74727565).
ETSI
16 Final draft ETSI ES 201 873-11 V4.9.1 (2021-03)
7 Using JSON to exchange data between TTCN-3 and
other systems
7.1 General rules
Clause 7 of the present document specifies converting abstract TTCN-3 values into their JSON representation (see
IETF RFC 7159 [2]) and converting JSON data into values of abstract TTCN-3 types. Clause 7 of the present document
covers the conversion rules for the different TTCN-3 data types, while the encoding instructions, influencing the
conversion are detailed in Annex B.
By default all instances of top-level TTCN-3 types are represented by a "wrapper" JSON object with a single object
member, where the name of the object member shall be:
• the name of a built-in TTCN-3 type, except for anytype-s;
• the qualified name of the built-in TTCN-3 type anytype; or
• the qualified name of a user-defined TTCN-3 type (in case of a type alias, the name of the alias type shall be
used);
• and the value of the object member is the JSON representation of the value of the given instance. The name of
t
...
ETSI STANDARD
Methods for Testing and Specification (MTS);
The Testing and Test Control Notation version 3;
Part 11: Using JSON with TTCN-3
2 ETSI ES 201 873-11 V4.9.1 (2021-06)
Reference
RES/MTS-201873-11 v4.9.1
Keywords
JSON, language, testing, TTCN-3
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - APE 7112B
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° w061004871
Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Notice of disclaimer & limitation of liability
The information provided in the present deliverable is directed solely to professionals who have the appropriate degree of
experience to understand and interpret its content in accordance with generally accepted engineering or
other professional standard and applicable regulations.
No recommendation as to products and services or vendors is made or should be implied.
No representation or warranty is made that this deliverable is technically accurate or sufficient or conforms to any law
and/or governmental rule and/or regulation and further, no representation or warranty is made of merchantability or fitness
for any particular purpose or against infringement of intellectual property rights.
In no event shall ETSI be held liable for loss of profits or any other incidental or consequential damages.
Any software contained in this deliverable is provided "AS IS" with no warranties, express or implied, including but not
limited to, the warranties of merchantability, fitness for a particular purpose and non-infringement of intellectual property
rights and ETSI shall not be held liable in any event for any damages whatsoever (including, without limitation, damages
for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use
of or inability to use the software.
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and
microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2021.
All rights reserved.
ETSI
3 ETSI ES 201 873-11 V4.9.1 (2021-06)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 6
3 Definition of terms, symbols and abbreviations . 7
3.1 Terms . 7
3.2 Symbols . 7
3.3 Abbreviations . 7
4 Introduction . 8
5 Conformance and compatibility . 8
6 Using TTCN-3 as JSON Schema . 9
6.1 Approach . 9
6.2 Validation of JSON Values . 9
6.3 Name conversion rules . 9
6.4 Mapping of JSON Values . 10
6.4.1 JSON Numbers . 10
6.4.2 JSON Strings . 11
6.4.3 JSON Arrays . 12
6.4.4 JSON Objects. 13
6.4.5 JSON Literals. 15
7 Using JSON to exchange data between TTCN-3 and other systems . 16
7.1 General rules . 16
7.2 JSON representations of TTCN-3 values . 17
7.2.1 Character strings . 17
7.2.2 Binary Strings . 17
7.2.3 Integer . 17
7.2.4 Float . 18
7.2.5 Boolean . 18
7.2.6 Enumerated . 18
7.2.7 Verdicttype . 19
7.2.8 Record and set . 19
7.2.9 Record of, set of and arrays . 20
7.2.10 Union and anytype . 21
7.2.11 Object Identifiers . 22
8 JSON representations of TTCN-3 values based on ASN.1 types . 22
8.1 General rules . 22
8.2 Character strings . 23
8.3 Binary strings . 23
8.4 BOOLEAN . 23
8.5 ENUMERATED . 23
8.6 REAL . 23
8.7 INTEGER . 23
8.8 OBJID . 23
8.9 NULL . 23
8.10 SEQUENCE and SET . 24
8.11 SEQUENCE OF and SET OF . 24
8.12 CHOICE and Open Types . 24
Annex A (normative): TTCN-3 module JSON . 25
ETSI
4 ETSI ES 201 873-11 V4.9.1 (2021-06)
Annex B (normative): Encoding instructions . 27
B.1 General . 27
B.2 The JSON encode attribute . 27
B.3 Encoding instructions . 27
B.3.1 General rules . 27
B.3.2 JSON type identification . 28
B.3.3 Normalizing JSON Values . 28
B.3.4 Name as . 28
B.3.5 Number of fraction digits . 29
B.3.6 Use the Minus sign . 30
B.3.7 Escape as . 30
B.3.8 Omit as null . 31
B.3.9 Default . 31
B.3.10 As value . 32
B.3.11 No Type . 33
B.3.12 Use order . 33
B.3.13 Error behaviour . 33
Annex C (informative): Bibliography . 35
History . 36
ETSI
5 ETSI ES 201 873-11 V4.9.1 (2021-06)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The declarations
pertaining to these essential IPRs, if any, are publicly available for ETSI members and non-members, and can be
found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to
ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the
ETSI Web server (https://ipr.etsi.org/).
Pursuant to the ETSI Directives including the ETSI IPR Policy, no investigation regarding the essentiality of IPRs,
including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not
referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become,
essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its
Members. 3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and of the 3GPP
Organizational Partners. oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and of the ®
oneM2M Partners. GSM and the GSM logo are trademarks registered and owned by the GSM Association.
Foreword
This ETSI Standard (ES) has been produced by ETSI Technical Committee Methods for Testing and Specification
(MTS).
The present document is part 11 of a multi-part deliverable. Full details of the entire series can be found in part 1 [1].
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
6 ETSI ES 201 873-11 V4.9.1 (2021-06)
1 Scope
The present document specifies the rules to define schemas for JSON data structures in TTCN-3, to enable testing of
JSON-based systems, interfaces and protocols, and the conversion rules between TTCN-3 [1] and JSON [2] to enable
exchanging TTCN-3 data in JSON format between different systems.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference/.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] ETSI ES 201 873-1: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 1: TTCN-3 Core Language". ®
[2] IETF RFC 7159: "The JavaScript Object Notation (JSON) Data Interchange Format".
NOTE: Available at http://www.rfc-editor.org/rfc/rfc7159.txt.
[3] ISO/IEC 10646:2017: "Information technology -- Universal Coded Character Set (UCS)".
NOTE: Available at https://www.iso.org/standard/69119.html.
™
[4] IEEE 754 : "IEEE Standard for Floating-Point Arithmetic".
[5] ETSI ES 201 873-7: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 7: Using ASN.1 with TTCN-3".
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area. ®
draft-handrews-json-schema-validation-00: "JSON Schema Validation: A Vocabulary for
[i.1] IETF
Structural Validation of JSON".
NOTE: Available at https://datatracker.ietf.org/doc/draft-handrews-json-schema. ®
[i.2] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 1: Structures".
NOTE: Available at http://www.w3.org/TR/xmlschema11-1.
ETSI
7 ETSI ES 201 873-11 V4.9.1 (2021-06) ®
[i.3] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/xmlschema11-2.
[i.4] ETSI ES 201 873-8: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 8: The IDL to TTCN-3 Mapping".
[i.5] ETSI ES 201 873-9: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 9: Using XML schema with TTCN-3".
[i.6] ETSI ES 202 781: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Configuration and Deployment Support".
[i.7] ETSI ES 202 782: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance and Real Time Testing".
[i.8] ETSI ES 202 784: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Advanced Parameterization".
[i.9] ETSI ES 202 785: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Behaviour Types".
[i.10] ETSI ES 202 786: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Support of interfaces with continuous signals".
[i.11] ETSI ES 202 789: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Extended TRI".
[i.12] ETSI ES 203 022: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language extension: Advanced Matching".
[i.13] ETSI ES 203 790: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Object-Oriented Features".
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the terms and definitions given in ETSI ES 201 873-1 [1] apply.
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ASN.1 Abstract Syntax Notation One
IO ASN.1 Information Object
JSON JavaScript Object Notation
SUT System Under Test
TTCN-3 Testing and Test Control Notation version 3
UCS Universal Coded Character Set
USI UCS Sequence Identifier
UTF-8 Unicode Transformation Format-8
XML eXtensible Markup Language
XSD XML Schema Definition
ETSI
8 ETSI ES 201 873-11 V4.9.1 (2021-06)
4 Introduction
An increasing number of distributed applications use the JSON to exchange data for various purposes like data bases
queries or updates or event telecommunications operations such as provisioning. The JSON specification [2] defines the
syntax and encoding for JSON types and defined literals, but no semantics is defined. JSON does not have a schema
specification, like the XML Schema Definition Language used for XML documents (see [i.2] and [i.3]).
NOTE: Though an IETF draft proposal exists for JSON structural validation (see [i.1]), it has not reached the
RFC status.
The core language of TTCN-3 is defined in ETSI ES 201 873-1 [1] and provides a full text-based syntax, static
semantics and operational semantics. Other parts of the ETSI ES 201 873 series are defining its use with other
specification languages like ASN.1 [5], IDL [i.4], or XSD [i.5] as shown in figure 1, while other documents as ETSI
ES 202 781 [i.6], ETSI ES 202 782 [i.7], ETSI ES 202 784 [i.8], ETSI ES 202 785 [i.9], ETSI ES 202 786 [i.10],
ETSI ES 202 789 [i.11], ETSI ES 203 022 [i.12] and ETSI ES 203 790 [i.13] specify language extensions and thus can
define additional rules to the JSON/TTCN-3 mapping defined in the present document.
Configuration Advanced OO
Advanced Behavior Performance Continuous TTCN-3
…
and deploy-
Matching Features
Parameteri- Types and Real signals Packages
ment support
zation Time Testing
ASN.1 types
and values
IDL types
TTCN-3
XML types
Core
TTCN-3 User
Language
JSON types
& values
The shaded boxes are not
defined in this document
Other types &
values
Figure 1: User's view of the core language and its packages
In the context of TTCN-3, JSON can be used for different purposes:
1) TTCN-3 can be used as a JSON Schema definition language that allows generating JSON values from
TTCN-3 and consuming and evaluating received JSON values, i.e. enables testing of JSON-based interfaces
and protocols.
2) To exchange type and data information between the TTCN-3 test system and systems written in other
languages like Java, C, C++, Python, etc. In this way TTCN-3 test systems can be used as a subsystem of a
more complex test system; for example, the TTCN-3 system receiving contents of messages to be sent to an
SUT, encode and send a message, receive and process the response and report the result to the other system.
Consequently, there is a need to specify mappings between JSON and TTCN-3 for the above purposes.
5 Conformance and compatibility
For an implementation claiming to support the use of TTCN-3 as a JSON schema language, all features specified in
clause 6 of the present document shall be implemented consistently with the requirements given in clause 6 and
Annex B of the present document and in ETSI ES 201 873-1 [1].
ETSI
9 ETSI ES 201 873-11 V4.9.1 (2021-06)
For an implementation claiming to support the exchange of TTCN-3-based data between systems, and not supporting
using ASN.1 with TTCN-3, all features specified in clause 7 of the present document, with the exception of the
mapping of the objid type in clause 7.2.11 shall be implemented consistently with the requirements given in clause 7
and Annex B of the present document and in ETSI ES 201 873-1 [1]. Implementations claiming the support of using
ASN.1 with TTCN-3, shall in addition support features in clause 7.2.11 and clause 8 of the present document.
The language mappings presented in the present document is compatible to:
• ETSI ES 201 873-1 [1], version 4.9.1.
If later versions of those parts are available and should be used instead, the compatibility of the rules presented in the
present document shall be checked individually.
6 Using TTCN-3 as JSON Schema
6.1 Approach
JSON [2] defines a limited set of JSON types and literal values. The clauses below define the TTCN-3 types that can be
used to specify a Schema for any JSON interface specification. The TTCN-3 types defined in the clauses below will
allow to use the same set of values as JSON permits. Annex A provides a TTCN-3 module containing all TTCN-3
definitions specified in these clauses. The JSON module in Annex A shall either explicitly be present in TTCN-3 test
suites or TTCN-3 tools shall support these types implicitly. This is left as a tool implementation option.
JSON in many cases allows different encoding options for the same value. These may be controlled by the JSON
encoding instructions specified in Annex B. JSON encoding instructions may be added to TTCN-3 types and fields by
using TTCN-3 variant attributes (see ETSI ES 201 873-1 [1], clause 27.5).
6.2 Validation of JSON Values
For further study.
6.3 Name conversion rules
The current version of the JSON specification [2] uses names to identify JSON object members only. The present
document defines JSON to TTCN-3 name conversion rules that shall be used when using TTCN-3 to specify a schema for
a JSON interface (see for example clause 6.4.4). When the JSON and the TTCN-3 names differ after applying the rules in
this clause, the "name as …" encoding instruction shall be used to identify the exact JSON name. To ensure compatibility
with future versions and automatic conversions, the rules specified in this clause should always be applied.
JSON names can be identical to TTCN-3 reserved words, can contain characters not allowed in TTCN-3 identifiers or
allowed to be identical, when the corresponding TTCN-3 names are required to be unique, in which case the JSON
names shall be processed by the rules below to obtain the corresponding TTCN-3 identifiers.
The following character substitutions shall be applied, in order that each character string being mapped to a TTCN-3
name, where each substitution (except the first) shall be applied to the result of the previous transformation:
a) any character except "A" to "Z" (Latin Capital Letter A to Latin Capital Letter Z), "a" to "z" (Latin Small
Letter A to Latin Small Letter Z), "0" to "9" (Digit Zero to Digit Nine), and "_" (Low Line) shall be removed;
b) a sequence of two or more "_" (Low Line) characters shall be replaced with a single "_" (Low Line);
c) "_" (Low Line) characters occurring at the beginning or at the end of the name shall be removed;
d) if a character string starts with a digit (Digit Zero to Digit Nine), it shall be prefixed with an "x" (Latin Small
Letter X) character;
e) if a character string is empty, it shall be replaced by "x" (Latin Small Letter X);
ETSI
10 ETSI ES 201 873-11 V4.9.1 (2021-06)
f) if the TTCN-3 name being generated is identical to a previously generated TTCN-3 identifier in the same
scope, then a postfix shall be appended to the character string generated by the above rules. If a field name of a
TTCN-3 structured type is clashing with a type's name used in the same structured type, the field's name shall
be postfixed. The postfix shall consist of a "_" (Low Line) followed by an integer. This integer shall be the
least positive integer such that the new identifier is different from the identifier of any previously generated
identifier in the same scope (i.e. the first postfix applied by this mechanism is "_1"). TTCN-3 names that are
one of the TTCN-3 keywords (see clause A.1.5 of ETSI ES 201 873-1 [1]) or names of predefined functions
(see clause 16.1.2 of ETSI ES 201 873-1 [1]) after applying the postfix to clashing names, shall be suffixed by
a single "_" (Low Line) character.
6.4 Mapping of JSON Values
6.4.1 JSON Numbers
JSON numbers are represented as base 10 decimal digits containing a mandatory integer component that can be
prefixed with an optional minus sign, and can be followed by a fraction part, an exponent part or both. Leading zeros
are not allowed. JSON does not distinguish numbers based on their value sets like integers and reals, like other
languages do. No special values (as –infinity, infinity or NaN) are allowed.
In the general case, JSON numbers shall be mapped by using the following TTCN-3 type:
type float Number (!-infinity . !infinity) with {
variant "JSON:number"
}
When the JSON interface specification requires a number to conform to the IEEE 754 [4] floating-point number
specification, the IEEE 754 floats useful types of clause E.2.1.4 of ETSI ES 201 873-1 [1] can be used in the context of
JSON encoding, in which case, by default, the given useful type will constrain the value set and the encoding of the
JSON value according to this clause. The JSON encoding instructions in this case can be applied to fields of IEEE 754
useful types.
By default, i.e. without any encoding instruction applied, the form of the JSON representation of JSON.Number is a
tool implementation option (i.e. the number of fraction digits, using the exponent part, etc.)
To make defining JSON Schemas in TTCN-3 easier, the present document, in addition to the generic mapping of JSON
numbers, also specifies a TTCN-3 type that may be used where the interface specification allows only numbers without
the fraction and the exponent parts:
type integer Integer (-infinity . infinity) with {
variant "JSON:integer"
}
Attempts to decode a JSON number value with either a fraction or an exponent part or both into this JSON.Integer
type shall cause a decoding failure.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific instructions
shall be applicable to types and fields of JSON.Number and the IEEE 754 useful types:
• fractionDigits see clause B.3.5
• useMinus see clause B.3.6
NOTE: The beginning character of the exponent part can be both "e" and "E". This is not controlled by any of the
encoding instructions but left as a tool implementation option.
and to types and fields of JSON.Integer types:
• useMinus see clause B.3.6
ETSI
11 ETSI ES 201 873-11 V4.9.1 (2021-06)
6.4.2 JSON Strings
A JSON string is a sequence of zero or more Unicode characters, enclosed in a pair of quotation mark characters (""",
char(U22)). Any characters may be escaped by the escape sequence: "\u", where represents four
hexadecimal digits, but the icharacters: quotation mark (""", char(U22)), reverse solidus ("\", char(U5C)) and all
C0 control characters (char(U0) through char(U1F)) shall be escaped.
Alternatively, the short, two-character escape sequences defined in table 1 can be used to escape some of the characters.
Table 1: Short character escape sequences
Character's name Character code Short escape
sequence
char(U22)
quotation mark \"
char(U5C)
reverse solidus \\
char(U2F)
solidus \/
char(U8) \b
backspace
form feed char(UC) \f
char(UA)
line feed \n
char(UD)
carriage return \r
char(U9)
horizontal tab \t
By default, it is a tool implementation option which form of escaping is used, which may be overridden by the "escape
as …" encoding instruction.
NOTE 1: Note that the JSON module in Annex A defines useful TTCN-3 constants for the characters listed above.
The following TTCN-3 type shall be used to map JSON strings to TTCN-3:
type universal charstring String with {
variant "JSON:string"
}
NOTE 2: Though Unicode and ISO/IEC 10646 [3] do not necessarily contain the same set of characters at all points
in time, JSON strings are expressed using the TTCN-3 universal charstring type.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific encoding
instructions are applicable to JSON.String types:
• escape as … see clause B.3.7
EXAMPLE: String encoding examples
If:
const JSON.String c_string1 := with {variant "escape as short"};
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\\cd" 2261625C5C636422
"ab/cd" "ab\/d" 2261625C2F636422
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037
cu_ht & "cd" 5C74636422
If:
const JSON.String c_string1 := with {variant "escape as usi"};
ETSI
12 ETSI ES 201 873-11 V4.9.1 (2021-06)
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\u005Ccd" 2261625C75303035
"ab/cd" "ab\u002Fcd" 2261625C7530303246636422 Escaped solidus character
(escaping solidus is
optional in JSON)
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\u0009c 2261625C7530303037
cs_ht & "cd" d" 5C7530303039636422
If:
const JSON.String c_string1 := with {variant "escape as transparent"};
then
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\cd" 2261625C636422 Note that the resulting
sequence is an invalid
JSON encoding
"ab/cd" "ab/cd" 2261622F636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037 Note that the BELL and HT
cs_ht & "cd" 5C74636422 C0 control characters are
escaped by the encoder
6.4.3 JSON Arrays
JSON arrays can contain a sequence of zero or more JSON values, i.e. the array members may be of different JSON
"types".
The following TTCN-3 type shall be used to map JSON arrays to TTCN-3:
type record of JSON.Values Array with {
variant "JSON:array"
},
Where:
type union Values {
JSON.String str,
JSON.Integer int,
JSON.Number num,
JSON.Object object,
JSON.StrArray strArray,
JSON.IntArray intArray,
JSON.NumArray numArray,
JSON.BoolArray boolArray,
JSON.ObjectArray objArray,
JSON.Array array,
JSON.Bool bool,
JSON.Null null_
} with {
variant "asValue"
}
To make specifying JSON Schemas easier for values, when according to the interface specification a specific array can
contain a sequence of values of the same JSON "type", also the TTCN-3 types below are specified:
NOTE: Use the below subsidiary types with due precaution. The syntax of TTCN-3 values based on the below
helper type differs from the syntax of a JSON.Array value. Therefore, changes in an array description
in a JSON interface specification can require changing the TTCN-3 code as well.
type record of JSON.String StrArray with {
variant "JSON:array"
}
ETSI
13 ETSI ES 201 873-11 V4.9.1 (2021-06)
type record of JSON.Number NumArray with {
variant "JSON:array"
}
type record of JSON.Integer IntArray with {
variant "JSON:array"
}
type record of JSON.Boolean BoolArray with {
variant "JSON:array"
}
type record of JSON.Object ObjArray with {
variant "JSON:array"
}
Where JSON.Object is:
type record Object {
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object"
}
And:
type record ObjectMember {
JSON.String name, // shall contain an object member's name
JSON.Types value_ // shall contain an object member's value
} with {
variant "JSON:objectMember"
}
There is no type-specific encoding instruction defined for JSON.Array, JSON.StrArray, JSON.NumArray,
JSON.IntArray, JSON.BoolArray, JSON.ObjArray, in addition to the generic ones like "normalize" and
"name as …". In addition to the generic encoding instructions, the JSON.Types type uses the following instruction:
• asValue see clause B.3.10.
EXAMPLE: TTCN-3 Schema for a JSON array
Provided a JSON interface specification, allows a list of arbitrary JSON values e.g. as the value part of an object
member. Its TTCN-3 schemata will be:
type JSON.Array MyValue;
And e.g. the TTCN-3 value:
const MyValue c_myValue := {
{ str := "abcd" },
{ num := 1.0 },
{ int := 42 },
{ intArray := { 1, 2, 3, 4, 5, 6 },
{ null_ := null_ }
};
will be encoded in JSON e.g. as (character sequence):
["abcd", 1e0, 42, [ 1, 2, 3, 4, 5, 6 ], null ]
Note that as no additional instruction is specified for the "num" element, its encoding is a tool option.
6.4.4 JSON Objects
JSON object values consist of unordered sequences of zero or more object members, where each object member is
constructed of a name-value pair. The JSON specification IETF RFC 7159 [2] does not require uniqueness of object
member names within a JSON object.
ETSI
14 ETSI ES 201 873-11 V4.9.1 (2021-06)
JSON object specifications should be translated to TTCN-3 record-s. The name of the record shall be the product of
applying clause 6.3 to the name of the object being translated, if this is specified, or be an arbitrary valid TTCN-3
identifier otherwise. The name of the type shall not be "Object", if this is the name of the JSON object being
translated, the postfixing rules specified in item f) of clause 6.3 shall be applied to it.
Each member of the object being converted shall generate a record field, where the name of the field shall be the
product of applying clause 6.3 to the name of the object member, but it shall not be "order": if this would be the name
of the TTCN-3 field, the postfixing rules specified in item f) of clause 6.3 shall be applied to it, as if it was preceded by
a field named order. The type of the field shall be a type defined in clause 6 of the present document, corresponding
to the JSON type (or literal values allowed) of the object member. If the object member can carry values of different
JSON types (or literals), the type of the field shall be a union of the TTCN-3 types required to represent all possible
values of the object member being translated, where the union field names shall be the names of the field's type with
lower cased first character.
Following this translation an optional TTCN-3 record of JSON.String field named order may be inserted
as the first field of the record, and an optional field named memberList of the type record length
(1.infinity) of JSON.ObjectMember shall be inserted as the last field of the record.
Possible name clashes caused by inserting the memberList field shall be resolved according to item f) of clause 6.3
with the exception that the additionally inserted field memberList shall be handled as if it was the first field of the
record (i.e. if an object member with the name "memberList" exists, the object member's name shall be postfixed).
Finally the "JSON:object" and if the order field is present the "useOrder" encoding instructions shall be attached to
the generated record type. Any other encoding instructions may be attached to the record fields, as necessary for a
correct translation.
The memberList field allows inserting any extra object members in instance definitions, and converters shall encode
each ObjectMember as member of the JSON object being produced. At JSON to TTCN-3 conversion JSON object
members, which cannot be decoded into any other field being produced from the member's name, shall be decoded as
element of the memberList field.
Use of the order field is specified in clause B.3.12.
NOTE: Note that attaching the optional "implicit omit" attribute to TTCN-3 values and templates implementing
object instances will allow skipping unused order and memberList fields in the instance definitions.
EXAMPLE: TTCN-3 Schema for a JSON object
Suppose that the specification defines a JSON object that shall carry the location information "Latitude",
"Longitude", which are floating point numbers and may carry the "Precision" and "Address" information, where
precision is to be provided as a number and the address is another JSON object containing the city, street and
house number information, where city and street are JSON strings, house number is an integer value.
The schema of this specification can be described in TTCN-3 e.g. as:
module MyObjectSchema {
import from JSON all;
type record Coordinates {
record of JSON.String order optional,
JSON.Number Latitude,
JSON.Number Longitude,
JSON.Number Precision optional,
Address Address_1 optional,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
variant "useOrder"
variant(Address_1) "name as 'Address'";
}
type record Address {
record of JSON.String order optional,
JSON.String city,
JSON.String street,
JSON.Integer house_no_,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
ETSI
15 ETSI ES 201 873-11 V4.9.1 (2021-06)
variant "useOrder";
variant (house_no_) "name as 'house no.' "
}
} with { encode "JSON" }
And the TTCN-3 templates:
template Coordinates t_coordinates := {
Latitude := 51.523704,
Longitude := -0.158553,
Address_1 := t_address
} with { optional "implicit omit" }
template Address t_address := {
order := {"house_no_","subno","street","city"},
city := "London",
street := "Baker",
house_no_ := 221,
memberList := {{"subno",{str:="B"}}}
}
will be encoded in JSON as:
{"Latitude":51.523704,"Longitude":-0.158553,"Address":
{"house no.":221,"subno":"B","street":"Baker","city":"London"}}
There is no type-specific encoding instruction defined for JSON.Object, in addition to the generic ones like
"normalize" and "name as …".
6.4.5 JSON Literals
JSON specifies three literal values: true, false and null. These are mapped to the TTCN-3 types:
//When only the true and false literals are allowed
type boolean Bool with { variant "JSON:literal" }
//When only the null literal is allowed
type enumerated Null { null_ } with { variant "JSON:literal" }
NOTE: In the case if a JSON value could contain all three defined JSON literals, the user can define a union type
of the above types.
There is no type-specific encoding instruction defined for the above types mapping JSON literals, in addition to the
generic ones like "normalize" and "name as …".
EXAMPLE:
The TTCN-3 value:
const JSON.Bool c_true :=
...
SLOVENSKI STANDARD
01-september-2021
Metode za preskušanje in specificiranje (MTS) - 3. različica zapisa preskušanja in
krmiljenja preskusov - 11. del: Uporaba JSON v TTCN-3
Methods for Testing and Specification (MTS) - The Testing and Test Control Notation
version 3 - Part 11: Using JSON with TTCN-3
Ta slovenski standard je istoveten z: ETSI ES 201 873-11 V4.9.1 (2021-06)
ICS:
33.040.01 Telekomunikacijski sistemi na Telecommunication systems
splošno in general
35.060 Jeziki, ki se uporabljajo v Languages used in
informacijski tehniki in information technology
tehnologiji
2003-01.Slovenski inštitut za standardizacijo. Razmnoževanje celote ali delov tega standarda ni dovoljeno.
ETSI STANDARD
Methods for Testing and Specification (MTS);
The Testing and Test Control Notation version 3;
Part 11: Using JSON with TTCN-3
2 ETSI ES 201 873-11 V4.9.1 (2021-06)
Reference
RES/MTS-201873-11 v4.9.1
Keywords
JSON, language, testing, TTCN-3
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE
Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16
Siret N° 348 623 562 00017 - APE 7112B
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° w061004871
Important notice
The present document can be downloaded from:
http://www.etsi.org/standards-search
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
https://portal.etsi.org/TB/ETSIDeliverableStatus.aspx
If you find errors in the present document, please send your comment to one of the following services:
https://portal.etsi.org/People/CommiteeSupportStaff.aspx
Notice of disclaimer & limitation of liability
The information provided in the present deliverable is directed solely to professionals who have the appropriate degree of
experience to understand and interpret its content in accordance with generally accepted engineering or
other professional standard and applicable regulations.
No recommendation as to products and services or vendors is made or should be implied.
No representation or warranty is made that this deliverable is technically accurate or sufficient or conforms to any law
and/or governmental rule and/or regulation and further, no representation or warranty is made of merchantability or fitness
for any particular purpose or against infringement of intellectual property rights.
In no event shall ETSI be held liable for loss of profits or any other incidental or consequential damages.
Any software contained in this deliverable is provided "AS IS" with no warranties, express or implied, including but not
limited to, the warranties of merchantability, fitness for a particular purpose and non-infringement of intellectual property
rights and ETSI shall not be held liable in any event for any damages whatsoever (including, without limitation, damages
for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use
of or inability to use the software.
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and
microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2021.
All rights reserved.
ETSI
3 ETSI ES 201 873-11 V4.9.1 (2021-06)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 6
3 Definition of terms, symbols and abbreviations . 7
3.1 Terms . 7
3.2 Symbols . 7
3.3 Abbreviations . 7
4 Introduction . 8
5 Conformance and compatibility . 8
6 Using TTCN-3 as JSON Schema . 9
6.1 Approach . 9
6.2 Validation of JSON Values . 9
6.3 Name conversion rules . 9
6.4 Mapping of JSON Values . 10
6.4.1 JSON Numbers . 10
6.4.2 JSON Strings . 11
6.4.3 JSON Arrays . 12
6.4.4 JSON Objects. 13
6.4.5 JSON Literals. 15
7 Using JSON to exchange data between TTCN-3 and other systems . 16
7.1 General rules . 16
7.2 JSON representations of TTCN-3 values . 17
7.2.1 Character strings . 17
7.2.2 Binary Strings . 17
7.2.3 Integer . 17
7.2.4 Float . 18
7.2.5 Boolean . 18
7.2.6 Enumerated . 18
7.2.7 Verdicttype . 19
7.2.8 Record and set . 19
7.2.9 Record of, set of and arrays . 20
7.2.10 Union and anytype . 21
7.2.11 Object Identifiers . 22
8 JSON representations of TTCN-3 values based on ASN.1 types . 22
8.1 General rules . 22
8.2 Character strings . 23
8.3 Binary strings . 23
8.4 BOOLEAN . 23
8.5 ENUMERATED . 23
8.6 REAL . 23
8.7 INTEGER . 23
8.8 OBJID . 23
8.9 NULL . 23
8.10 SEQUENCE and SET . 24
8.11 SEQUENCE OF and SET OF . 24
8.12 CHOICE and Open Types . 24
Annex A (normative): TTCN-3 module JSON . 25
ETSI
4 ETSI ES 201 873-11 V4.9.1 (2021-06)
Annex B (normative): Encoding instructions . 27
B.1 General . 27
B.2 The JSON encode attribute . 27
B.3 Encoding instructions . 27
B.3.1 General rules . 27
B.3.2 JSON type identification . 28
B.3.3 Normalizing JSON Values . 28
B.3.4 Name as . 28
B.3.5 Number of fraction digits . 29
B.3.6 Use the Minus sign . 30
B.3.7 Escape as . 30
B.3.8 Omit as null . 31
B.3.9 Default . 31
B.3.10 As value . 32
B.3.11 No Type . 33
B.3.12 Use order . 33
B.3.13 Error behaviour . 33
Annex C (informative): Bibliography . 35
History . 36
ETSI
5 ETSI ES 201 873-11 V4.9.1 (2021-06)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The declarations
pertaining to these essential IPRs, if any, are publicly available for ETSI members and non-members, and can be
found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to
ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the
ETSI Web server (https://ipr.etsi.org/).
Pursuant to the ETSI Directives including the ETSI IPR Policy, no investigation regarding the essentiality of IPRs,
including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not
referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become,
essential to the present document.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its
Members. 3GPP™ and LTE™ are trademarks of ETSI registered for the benefit of its Members and of the 3GPP
Organizational Partners. oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and of the ®
oneM2M Partners. GSM and the GSM logo are trademarks registered and owned by the GSM Association.
Foreword
This ETSI Standard (ES) has been produced by ETSI Technical Committee Methods for Testing and Specification
(MTS).
The present document is part 11 of a multi-part deliverable. Full details of the entire series can be found in part 1 [1].
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
6 ETSI ES 201 873-11 V4.9.1 (2021-06)
1 Scope
The present document specifies the rules to define schemas for JSON data structures in TTCN-3, to enable testing of
JSON-based systems, interfaces and protocols, and the conversion rules between TTCN-3 [1] and JSON [2] to enable
exchanging TTCN-3 data in JSON format between different systems.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
https://docbox.etsi.org/Reference/.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] ETSI ES 201 873-1: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 1: TTCN-3 Core Language". ®
[2] IETF RFC 7159: "The JavaScript Object Notation (JSON) Data Interchange Format".
NOTE: Available at http://www.rfc-editor.org/rfc/rfc7159.txt.
[3] ISO/IEC 10646:2017: "Information technology -- Universal Coded Character Set (UCS)".
NOTE: Available at https://www.iso.org/standard/69119.html.
™
[4] IEEE 754 : "IEEE Standard for Floating-Point Arithmetic".
[5] ETSI ES 201 873-7: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 7: Using ASN.1 with TTCN-3".
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area. ®
draft-handrews-json-schema-validation-00: "JSON Schema Validation: A Vocabulary for
[i.1] IETF
Structural Validation of JSON".
NOTE: Available at https://datatracker.ietf.org/doc/draft-handrews-json-schema. ®
[i.2] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 1: Structures".
NOTE: Available at http://www.w3.org/TR/xmlschema11-1.
ETSI
7 ETSI ES 201 873-11 V4.9.1 (2021-06) ®
[i.3] World Wide Web Consortium W3C Recommendation: "W3C XML Schema Definition
Language (XSD) 1.1 Part 2: Datatypes".
NOTE: Available at http://www.w3.org/TR/xmlschema11-2.
[i.4] ETSI ES 201 873-8: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 8: The IDL to TTCN-3 Mapping".
[i.5] ETSI ES 201 873-9: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; Part 9: Using XML schema with TTCN-3".
[i.6] ETSI ES 202 781: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Configuration and Deployment Support".
[i.7] ETSI ES 202 782: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance and Real Time Testing".
[i.8] ETSI ES 202 784: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Advanced Parameterization".
[i.9] ETSI ES 202 785: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Behaviour Types".
[i.10] ETSI ES 202 786: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Support of interfaces with continuous signals".
[i.11] ETSI ES 202 789: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Extended TRI".
[i.12] ETSI ES 203 022: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language extension: Advanced Matching".
[i.13] ETSI ES 203 790: "Methods for Testing and Specification (MTS); The Testing and Test Control
Notation version 3; TTCN-3 Language Extensions: Object-Oriented Features".
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the terms and definitions given in ETSI ES 201 873-1 [1] apply.
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the following abbreviations apply:
ASN.1 Abstract Syntax Notation One
IO ASN.1 Information Object
JSON JavaScript Object Notation
SUT System Under Test
TTCN-3 Testing and Test Control Notation version 3
UCS Universal Coded Character Set
USI UCS Sequence Identifier
UTF-8 Unicode Transformation Format-8
XML eXtensible Markup Language
XSD XML Schema Definition
ETSI
8 ETSI ES 201 873-11 V4.9.1 (2021-06)
4 Introduction
An increasing number of distributed applications use the JSON to exchange data for various purposes like data bases
queries or updates or event telecommunications operations such as provisioning. The JSON specification [2] defines the
syntax and encoding for JSON types and defined literals, but no semantics is defined. JSON does not have a schema
specification, like the XML Schema Definition Language used for XML documents (see [i.2] and [i.3]).
NOTE: Though an IETF draft proposal exists for JSON structural validation (see [i.1]), it has not reached the
RFC status.
The core language of TTCN-3 is defined in ETSI ES 201 873-1 [1] and provides a full text-based syntax, static
semantics and operational semantics. Other parts of the ETSI ES 201 873 series are defining its use with other
specification languages like ASN.1 [5], IDL [i.4], or XSD [i.5] as shown in figure 1, while other documents as ETSI
ES 202 781 [i.6], ETSI ES 202 782 [i.7], ETSI ES 202 784 [i.8], ETSI ES 202 785 [i.9], ETSI ES 202 786 [i.10],
ETSI ES 202 789 [i.11], ETSI ES 203 022 [i.12] and ETSI ES 203 790 [i.13] specify language extensions and thus can
define additional rules to the JSON/TTCN-3 mapping defined in the present document.
Configuration Advanced OO
Advanced Behavior Performance Continuous TTCN-3
…
and deploy-
Matching Features
Parameteri- Types and Real signals Packages
ment support
zation Time Testing
ASN.1 types
and values
IDL types
TTCN-3
XML types
Core
TTCN-3 User
Language
JSON types
& values
The shaded boxes are not
defined in this document
Other types &
values
Figure 1: User's view of the core language and its packages
In the context of TTCN-3, JSON can be used for different purposes:
1) TTCN-3 can be used as a JSON Schema definition language that allows generating JSON values from
TTCN-3 and consuming and evaluating received JSON values, i.e. enables testing of JSON-based interfaces
and protocols.
2) To exchange type and data information between the TTCN-3 test system and systems written in other
languages like Java, C, C++, Python, etc. In this way TTCN-3 test systems can be used as a subsystem of a
more complex test system; for example, the TTCN-3 system receiving contents of messages to be sent to an
SUT, encode and send a message, receive and process the response and report the result to the other system.
Consequently, there is a need to specify mappings between JSON and TTCN-3 for the above purposes.
5 Conformance and compatibility
For an implementation claiming to support the use of TTCN-3 as a JSON schema language, all features specified in
clause 6 of the present document shall be implemented consistently with the requirements given in clause 6 and
Annex B of the present document and in ETSI ES 201 873-1 [1].
ETSI
9 ETSI ES 201 873-11 V4.9.1 (2021-06)
For an implementation claiming to support the exchange of TTCN-3-based data between systems, and not supporting
using ASN.1 with TTCN-3, all features specified in clause 7 of the present document, with the exception of the
mapping of the objid type in clause 7.2.11 shall be implemented consistently with the requirements given in clause 7
and Annex B of the present document and in ETSI ES 201 873-1 [1]. Implementations claiming the support of using
ASN.1 with TTCN-3, shall in addition support features in clause 7.2.11 and clause 8 of the present document.
The language mappings presented in the present document is compatible to:
• ETSI ES 201 873-1 [1], version 4.9.1.
If later versions of those parts are available and should be used instead, the compatibility of the rules presented in the
present document shall be checked individually.
6 Using TTCN-3 as JSON Schema
6.1 Approach
JSON [2] defines a limited set of JSON types and literal values. The clauses below define the TTCN-3 types that can be
used to specify a Schema for any JSON interface specification. The TTCN-3 types defined in the clauses below will
allow to use the same set of values as JSON permits. Annex A provides a TTCN-3 module containing all TTCN-3
definitions specified in these clauses. The JSON module in Annex A shall either explicitly be present in TTCN-3 test
suites or TTCN-3 tools shall support these types implicitly. This is left as a tool implementation option.
JSON in many cases allows different encoding options for the same value. These may be controlled by the JSON
encoding instructions specified in Annex B. JSON encoding instructions may be added to TTCN-3 types and fields by
using TTCN-3 variant attributes (see ETSI ES 201 873-1 [1], clause 27.5).
6.2 Validation of JSON Values
For further study.
6.3 Name conversion rules
The current version of the JSON specification [2] uses names to identify JSON object members only. The present
document defines JSON to TTCN-3 name conversion rules that shall be used when using TTCN-3 to specify a schema for
a JSON interface (see for example clause 6.4.4). When the JSON and the TTCN-3 names differ after applying the rules in
this clause, the "name as …" encoding instruction shall be used to identify the exact JSON name. To ensure compatibility
with future versions and automatic conversions, the rules specified in this clause should always be applied.
JSON names can be identical to TTCN-3 reserved words, can contain characters not allowed in TTCN-3 identifiers or
allowed to be identical, when the corresponding TTCN-3 names are required to be unique, in which case the JSON
names shall be processed by the rules below to obtain the corresponding TTCN-3 identifiers.
The following character substitutions shall be applied, in order that each character string being mapped to a TTCN-3
name, where each substitution (except the first) shall be applied to the result of the previous transformation:
a) any character except "A" to "Z" (Latin Capital Letter A to Latin Capital Letter Z), "a" to "z" (Latin Small
Letter A to Latin Small Letter Z), "0" to "9" (Digit Zero to Digit Nine), and "_" (Low Line) shall be removed;
b) a sequence of two or more "_" (Low Line) characters shall be replaced with a single "_" (Low Line);
c) "_" (Low Line) characters occurring at the beginning or at the end of the name shall be removed;
d) if a character string starts with a digit (Digit Zero to Digit Nine), it shall be prefixed with an "x" (Latin Small
Letter X) character;
e) if a character string is empty, it shall be replaced by "x" (Latin Small Letter X);
ETSI
10 ETSI ES 201 873-11 V4.9.1 (2021-06)
f) if the TTCN-3 name being generated is identical to a previously generated TTCN-3 identifier in the same
scope, then a postfix shall be appended to the character string generated by the above rules. If a field name of a
TTCN-3 structured type is clashing with a type's name used in the same structured type, the field's name shall
be postfixed. The postfix shall consist of a "_" (Low Line) followed by an integer. This integer shall be the
least positive integer such that the new identifier is different from the identifier of any previously generated
identifier in the same scope (i.e. the first postfix applied by this mechanism is "_1"). TTCN-3 names that are
one of the TTCN-3 keywords (see clause A.1.5 of ETSI ES 201 873-1 [1]) or names of predefined functions
(see clause 16.1.2 of ETSI ES 201 873-1 [1]) after applying the postfix to clashing names, shall be suffixed by
a single "_" (Low Line) character.
6.4 Mapping of JSON Values
6.4.1 JSON Numbers
JSON numbers are represented as base 10 decimal digits containing a mandatory integer component that can be
prefixed with an optional minus sign, and can be followed by a fraction part, an exponent part or both. Leading zeros
are not allowed. JSON does not distinguish numbers based on their value sets like integers and reals, like other
languages do. No special values (as –infinity, infinity or NaN) are allowed.
In the general case, JSON numbers shall be mapped by using the following TTCN-3 type:
type float Number (!-infinity . !infinity) with {
variant "JSON:number"
}
When the JSON interface specification requires a number to conform to the IEEE 754 [4] floating-point number
specification, the IEEE 754 floats useful types of clause E.2.1.4 of ETSI ES 201 873-1 [1] can be used in the context of
JSON encoding, in which case, by default, the given useful type will constrain the value set and the encoding of the
JSON value according to this clause. The JSON encoding instructions in this case can be applied to fields of IEEE 754
useful types.
By default, i.e. without any encoding instruction applied, the form of the JSON representation of JSON.Number is a
tool implementation option (i.e. the number of fraction digits, using the exponent part, etc.)
To make defining JSON Schemas in TTCN-3 easier, the present document, in addition to the generic mapping of JSON
numbers, also specifies a TTCN-3 type that may be used where the interface specification allows only numbers without
the fraction and the exponent parts:
type integer Integer (-infinity . infinity) with {
variant "JSON:integer"
}
Attempts to decode a JSON number value with either a fraction or an exponent part or both into this JSON.Integer
type shall cause a decoding failure.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific instructions
shall be applicable to types and fields of JSON.Number and the IEEE 754 useful types:
• fractionDigits see clause B.3.5
• useMinus see clause B.3.6
NOTE: The beginning character of the exponent part can be both "e" and "E". This is not controlled by any of the
encoding instructions but left as a tool implementation option.
and to types and fields of JSON.Integer types:
• useMinus see clause B.3.6
ETSI
11 ETSI ES 201 873-11 V4.9.1 (2021-06)
6.4.2 JSON Strings
A JSON string is a sequence of zero or more Unicode characters, enclosed in a pair of quotation mark characters (""",
char(U22)). Any characters may be escaped by the escape sequence: "\u", where represents four
hexadecimal digits, but the icharacters: quotation mark (""", char(U22)), reverse solidus ("\", char(U5C)) and all
C0 control characters (char(U0) through char(U1F)) shall be escaped.
Alternatively, the short, two-character escape sequences defined in table 1 can be used to escape some of the characters.
Table 1: Short character escape sequences
Character's name Character code Short escape
sequence
char(U22)
quotation mark \"
char(U5C)
reverse solidus \\
char(U2F)
solidus \/
char(U8) \b
backspace
form feed char(UC) \f
char(UA)
line feed \n
char(UD)
carriage return \r
char(U9)
horizontal tab \t
By default, it is a tool implementation option which form of escaping is used, which may be overridden by the "escape
as …" encoding instruction.
NOTE 1: Note that the JSON module in Annex A defines useful TTCN-3 constants for the characters listed above.
The following TTCN-3 type shall be used to map JSON strings to TTCN-3:
type universal charstring String with {
variant "JSON:string"
}
NOTE 2: Though Unicode and ISO/IEC 10646 [3] do not necessarily contain the same set of characters at all points
in time, JSON strings are expressed using the TTCN-3 universal charstring type.
In addition to the generic encoding instructions like "normalize" and "name as …", the following specific encoding
instructions are applicable to JSON.String types:
• escape as … see clause B.3.7
EXAMPLE: String encoding examples
If:
const JSON.String c_string1 := with {variant "escape as short"};
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\\cd" 2261625C5C636422
"ab/cd" "ab\/d" 2261625C2F636422
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037
cu_ht & "cd" 5C74636422
If:
const JSON.String c_string1 := with {variant "escape as usi"};
ETSI
12 ETSI ES 201 873-11 V4.9.1 (2021-06)
then:
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\u005Ccd" 2261625C75303035
"ab/cd" "ab\u002Fcd" 2261625C7530303246636422 Escaped solidus character
(escaping solidus is
optional in JSON)
"ab" & char(U7) & "ab\u0007cd" 2261625C75303030
"cd" 37636422
"ab" & char(U7) & "ab\u0007\u0009c 2261625C7530303037
cs_ht & "cd" d" 5C7530303039636422
If:
const JSON.String c_string1 := with {variant "escape as transparent"};
then
JSON character UTF-8 serialization of the Note
sequence JSON value
"abcd" "abcd" 226162636422
"ab\cd" "ab\cd" 2261625C636422 Note that the resulting
sequence is an invalid
JSON encoding
"ab/cd" "ab/cd" 2261622F636422
"ab" & char(U7) & "ab\u0007\tcd" 2261625C7530303037 Note that the BELL and HT
cs_ht & "cd" 5C74636422 C0 control characters are
escaped by the encoder
6.4.3 JSON Arrays
JSON arrays can contain a sequence of zero or more JSON values, i.e. the array members may be of different JSON
"types".
The following TTCN-3 type shall be used to map JSON arrays to TTCN-3:
type record of JSON.Values Array with {
variant "JSON:array"
},
Where:
type union Values {
JSON.String str,
JSON.Integer int,
JSON.Number num,
JSON.Object object,
JSON.StrArray strArray,
JSON.IntArray intArray,
JSON.NumArray numArray,
JSON.BoolArray boolArray,
JSON.ObjectArray objArray,
JSON.Array array,
JSON.Bool bool,
JSON.Null null_
} with {
variant "asValue"
}
To make specifying JSON Schemas easier for values, when according to the interface specification a specific array can
contain a sequence of values of the same JSON "type", also the TTCN-3 types below are specified:
NOTE: Use the below subsidiary types with due precaution. The syntax of TTCN-3 values based on the below
helper type differs from the syntax of a JSON.Array value. Therefore, changes in an array description
in a JSON interface specification can require changing the TTCN-3 code as well.
type record of JSON.String StrArray with {
variant "JSON:array"
}
ETSI
13 ETSI ES 201 873-11 V4.9.1 (2021-06)
type record of JSON.Number NumArray with {
variant "JSON:array"
}
type record of JSON.Integer IntArray with {
variant "JSON:array"
}
type record of JSON.Boolean BoolArray with {
variant "JSON:array"
}
type record of JSON.Object ObjArray with {
variant "JSON:array"
}
Where JSON.Object is:
type record Object {
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object"
}
And:
type record ObjectMember {
JSON.String name, // shall contain an object member's name
JSON.Types value_ // shall contain an object member's value
} with {
variant "JSON:objectMember"
}
There is no type-specific encoding instruction defined for JSON.Array, JSON.StrArray, JSON.NumArray,
JSON.IntArray, JSON.BoolArray, JSON.ObjArray, in addition to the generic ones like "normalize" and
"name as …". In addition to the generic encoding instructions, the JSON.Types type uses the following instruction:
• asValue see clause B.3.10.
EXAMPLE: TTCN-3 Schema for a JSON array
Provided a JSON interface specification, allows a list of arbitrary JSON values e.g. as the value part of an object
member. Its TTCN-3 schemata will be:
type JSON.Array MyValue;
And e.g. the TTCN-3 value:
const MyValue c_myValue := {
{ str := "abcd" },
{ num := 1.0 },
{ int := 42 },
{ intArray := { 1, 2, 3, 4, 5, 6 },
{ null_ := null_ }
};
will be encoded in JSON e.g. as (character sequence):
["abcd", 1e0, 42, [ 1, 2, 3, 4, 5, 6 ], null ]
Note that as no additional instruction is specified for the "num" element, its encoding is a tool option.
6.4.4 JSON Objects
JSON object values consist of unordered sequences of zero or more object members, where each object member is
constructed of a name-value pair. The JSON specification IETF RFC 7159 [2] does not require uniqueness of object
member names within a JSON object.
ETSI
14 ETSI ES 201 873-11 V4.9.1 (2021-06)
JSON object specifications should be translated to TTCN-3 record-s. The name of the record shall be the product of
applying clause 6.3 to the name of the object being translated, if this is specified, or be an arbitrary valid TTCN-3
identifier otherwise. The name of the type shall not be "Object", if this is the name of the JSON object being
translated, the postfixing rules specified in item f) of clause 6.3 shall be applied to it.
Each member of the object being converted shall generate a record field, where the name of the field shall be the
product of applying clause 6.3 to the name of the object member, but it shall not be "order": if this would be the name
of the TTCN-3 field, the postfixing rules specified in item f) of clause 6.3 shall be applied to it, as if it was preceded by
a field named order. The type of the field shall be a type defined in clause 6 of the present document, corresponding
to the JSON type (or literal values allowed) of the object member. If the object member can carry values of different
JSON types (or literals), the type of the field shall be a union of the TTCN-3 types required to represent all possible
values of the object member being translated, where the union field names shall be the names of the field's type with
lower cased first character.
Following this translation an optional TTCN-3 record of JSON.String field named order may be inserted
as the first field of the record, and an optional field named memberList of the type record length
(1.infinity) of JSON.ObjectMember shall be inserted as the last field of the record.
Possible name clashes caused by inserting the memberList field shall be resolved according to item f) of clause 6.3
with the exception that the additionally inserted field memberList shall be handled as if it was the first field of the
record (i.e. if an object member with the name "memberList" exists, the object member's name shall be postfixed).
Finally the "JSON:object" and if the order field is present the "useOrder" encoding instructions shall be attached to
the generated record type. Any other encoding instructions may be attached to the record fields, as necessary for a
correct translation.
The memberList field allows inserting any extra object members in instance definitions, and converters shall encode
each ObjectMember as member of the JSON object being produced. At JSON to TTCN-3 conversion JSON object
members, which cannot be decoded into any other field being produced from the member's name, shall be decoded as
element of the memberList field.
Use of the order field is specified in clause B.3.12.
NOTE: Note that attaching the optional "implicit omit" attribute to TTCN-3 values and templates implementing
object instances will allow skipping unused order and memberList fields in the instance definitions.
EXAMPLE: TTCN-3 Schema for a JSON object
Suppose that the specification defines a JSON object that shall carry the location information "Latitude",
"Longitude", which are floating point numbers and may carry the "Precision" and "Address" information, where
precision is to be provided as a number and the address is another JSON object containing the city, street and
house number information, where city and street are JSON strings, house number is an integer value.
The schema of this specification can be described in TTCN-3 e.g. as:
module MyObjectSchema {
import from JSON all;
type record Coordinates {
record of JSON.String order optional,
JSON.Number Latitude,
JSON.Number Longitude,
JSON.Number Precision optional,
Address Address_1 optional,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
variant "useOrder"
variant(Address_1) "name as 'Address'";
}
type record Address {
record of JSON.String order optional,
JSON.String city,
JSON.String street,
JSON.Integer house_no_,
record length (1.infinity) of JSON.ObjectMember memberList optional
} with {
variant "JSON:object";
ETSI
15 ETSI ES 201 873-11 V4.9.1 (2021-06)
variant "useOrder";
variant (house_no_) "name as 'house no.' "
}
} with { encod
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.
Loading comments...