IBM InfoSphere Streams Version 4.1.1

XML document format

SPL standard and specialized toolkits > com.ibm.streams.teda 1.0.2 > com.ibm.streams.teda.encoder.binary > ASN1Encode > XML document format

The ASN1Encode operator as well as the asn1-data-from-xml command line tool transform XML documents that fit to the provided ASN.1 specification. The following rules describe how to create valid XML documents for different ASN.1 grammar constructs.

The rule descriptions use the following ASN.1 grammar to provide examples.

MyModule DEFINITIONS IMPLICIT TAGS ::= 
BEGIN

Sample ::= SEQUENCE
{
	orders [0] SEQUENCE OF Order OPTIONAL,
	...
}

Order ::= SEQUENCE
{
	size    [0] PaperSize DEFAULT "a4",
	count   [1] INTEGER (0..100) DEFAULT 1,
	color   [2] Color DEFAULT "white",
	ordered [3] GeneralizedTime,
	...
}

PaperSize ::= ENUMERATED
{
	a0 (0),
	a1 (1),
	a2 (2),
	a3 (3),
	a4 (4),
	a5 (5)
} 

Color ::= ENUMERATED
{
	black (0),
	white (1),
	red (2),
	green (3),
	yellow (4)
}

END

Provide valid XML

Use an XML editor to create valid XML documents, or use, for example, the xmllint command line tool to verify the validity.

If you want to create an XML DTD that corresponds to the ASN.1 grammar specification, you can use the following command (replace the your-ASN.1-grammar-file-or-files with your space-separated list of ASN.1 grammar specification files):

$STREAMS_INSTALL/toolkits/com.ibm.streams.teda/impl/tools/asn1c -X -S $STREAMS_INSTALL/toolkits/com.ibm.streams.teda/impl/data/parser.binary.asn1/skeletons your-ASN.1-grammar-file-or-files

You can use the created XML DTD together with the XML editor or, for example, with the xmllint command.

Use ASN.1 field and type names only

The XML decoder supports only field or type names that are defined in the ASN.1 grammar file, for example, Sample, orders, Order, size, ordered, and a5:

<Sample>
	<orders>
		<Order>
			<ordered>20131224100000Z</ordered>
		</Order>
		<Order>
			<size><a5/></size>
			<ordered>20131224103000Z</ordered>
		</Order>
	</orders>
</Sample>

Provide XML tags for mandatory ASN.1 elements

Required ASN.1 elements (tags that are neither OPTIONAL nor DEFAULT) require an XML tag.

In the following example, the ordered field is mandatory:

Order ::= SEQUENCE
{
	size    [0] PaperSize DEFAULT "a4",
	count   [1] INTEGER (0..100) DEFAULT 1,
	color   [2] Color DEFAULT "white",
	ordered [3] GeneralizedTime,
	...
}

An XML document that does not have this tag cannot be converted, for example:

<Sample>
	<orders>
		<Order>
			<count>20</count>
			<color><red/></color>
		</Order>
	</orders>
</Sample>

Use valid values for primitive types

Values for primitive types must be either text or XML tags, depending on the type.

The following overview describe for each ASN.1 primitive type the supported formats and provides some examples:

  • BIT STRING

    A string with only 0 or 1 characters

    <x>0110</x>

  • BMPString

    A UTF-8 string

    <x>Hello</x>

  • BOOLEAN

    Only <true/> and <false/> are allowed.

    <x><false/></x>

  • ENUMERATED

    Any integer value or enumeration ID

    <x>1</x> <size><a5/></size>

  • GeneralizedTime

    Any time that is specified in ITU X.680 or ISO 8601 format

    <x>20001231235959.999</x> (local time) <x>20001231205959.999Z</x> (UTC time) <x>20001231235959.999+0300</x> (time shift)

  • GeneralString

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • GraphicString

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • IA5String

    Any 7-bit ASCII character string

    <x>Hello</x>

  • INTEGER

    Any integer value

    <x>1</x>

  • ISO646String

    Any UTF-8 string

    <x>Hello</x>

  • NULL

    A field that has no value

    <x/>

  • NumericString

    Any numeric (digit-only) string

    <x>9999</x>

  • ObjectDescriptor

    Any UTF-8 string

    <x>Hello</x>

  • OBJECT IDENTIFIER

    Any non-empty dot-separated list of numbers

    <x>1.2.3.4.5</x>

  • OCTET STRING

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • PrintableString

    Any UTF-8 string

    <x>Hello</x>

  • REAL

    Any real value or the special values for infinite or “not a number”

    <x>12.34</x> <x>314159e-5</x> <x><NOT-A-NUMBER/></x> <x><MINUS-INFINITY/></x> <x><PLUS-INFINITY/></x>

  • RELATIVE-OID

    Any non-empty dot-separated list of numbers

    <x>1.2.3.4.5</x>

  • T61String

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • TeletexString

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • UniversalString

    Any UTF-8 string

    <x>Hello</x>

  • UTCTime

    Any time that is specified in ITU X.680

    <x>001231235959</x> (local time) <x>001231205959Z</x> (UTC time) <x>001231235959+0300</x> (time shift)

  • UTF8String

    Any UTF-8 string

    <x>Hello</x>

  • VideotexString

    Any hex dump

    <x>3132</x> (hex values of ASCII characters 1 and 2)

  • VisibleString

    Any UTF-8 string

    <x>Hello</x>

Provide the correct child XML tags for SEQUENCE, SET, and CHOICE containers

SEQUENCE and SET are containers, which contain additional fields. Therefore, such a container has child XML tags instead of a value.

CHOICE means that only one of the specified fields can occur. With respect to XML, the style to add a child element is identical, for example:

Sample ::= CHOICE
{
	sequence     [10] Sequence,
	...
}

Sequence ::= SEQUENCE
{
	a [0] INTEGER,
	b [1] INTEGER,
	...
}

The following example shows a corresponding XML data file:

<Sample>
	<sequence>
		<a>321</a>
		<b>123</b>
	</sequence>
</Sample>

Add XML tags for the type identifiers in SEQUENCE OF or SET OF constructs

If the field has a SEQUENCE OF or SET OF declaration, the type identifier must be used for each value. For example, SEQUENCE OF INTEGER means that the type identifier is INTEGER.

Attention: Names with spaces or dashes require that these characters are replaced by underline, for example, RELATIVE-OID and BIT STRING in the ASN.1 specification correspond to RELATIVE_OID and BIT_STRING in the XML document:

Sample1 ::= SEQUENCE
{
	sequenceOfField [0] SEQUENCE OF INTEGER,
}

Sample2 ::= SEQUENCE
{
	sequenceOfField [0] SEQUENCE OF RELATIVE-OID,
}

Sample3 ::= SEQUENCE
{
	sequenceOfField [0] SEQUENCE OF BIT STRING,
}

Valid XML documents are, for example:

<Sample1>
	<sequenceOfField>
		<INTEGER>12</INTEGER>
		<INTEGER>34</INTEGER>
	</sequenceOfField>
</Sample1>

<Sample2>
	<sequenceOfField>
		<RELATIVE_OID>1.2.3.4.5</RELATIVE_OID>
		<RELATIVE_OID>1.4.16.64</RELATIVE_OID>
	</sequenceOfField>
</Sample2>

<Sample3>
	<sequenceOfField>
		<BIT_STRING>00</BIT_STRING>
		<BIT_STRING>01</BIT_STRING>
		<BIT_STRING>10</BIT_STRING>
		<BIT_STRING>11</BIT_STRING>
	</sequenceOfField>
</Sample3>

The same rules are valid for SEQUENCE and SET, for example: 

Sample ::= CHOICE
{
	sequences    [30] Sequences,
	...
}

Sequences ::= SEQUENCE OF Sequence

Sequence ::= SEQUENCE
{
	a [0] INTEGER,
	b [1] INTEGER,
	...
}

A valid XML document is, for example:

<Sample>
	<sequences>
		<Sequence>
			<a>21</a>
			<b>12</b>
		</Sequence>
		<Sequence>
			<a>321</a>
			<b>123</b>
		</Sequence>
	</sequences>
</Sample>

These rules are not valid for CHOICE because only one element can occur. Additional XML tags are not required. In the following example, the Choice XML tag is not required.

Sample ::= CHOICE
{
	choices      [31] Choices,
	...
}

Choices ::= SEQUENCE OF Choice

Choice ::= CHOICE
{
	a [0] INTEGER,
	b [1] INTEGER,
	...
}

A valid XML document is, for example:

<Sample>
	<choices>
		<a>21</a>
		<b>123</b>
	</choices>
</Sample>

Provide an underline for XML tag names where the ASN.1 names have spaces or dashes

If an ASN.1 field or type name contain spaces or dashes, these characters are replaced by an underline for the corresponding XML tag names. The same is valid for enumeration IDs. For example:

  1. The RELATIVE-OID ASN.1 type has the RELATIVE_OID XML name.
  2. The BIT STRING ASN.1 type has the BIT_STRING XML name.