File formats
WORK IN PROGRESS
please do not refer to this document until it is completed.
UniversalSerializer has three file formats (binary, xml and json) sharing the same structure:
- The file formats version 2.0 and 3.0 are slightly different.
The format 1.0 is totally different and is supported only in the DLL version 1. - The stream is saved as UTF-8.
- The stream is multiplexed: it interlaces two virtual sub-streams that are saved in one ordinary Stream.
- The stream 0 (zero) contains the type descriptors.
- The stream 1 (one) contains the data: the structure values and the class instances.
- The stream is structured as a tree.
That is independent from the virtual streams.
In fact, every serialization - Serialize() - add a tree to the main stream. - The type descriptors are saved at the last moment: just before this type of data is serialized for the first time.
They are serialized the same as any value, except this serialization is written in the stream 0. - Every type has an identifier: an integer number.
- The "primitive" types have a predefined identifier.
They are the same as in the System.TypeCode enumeration. - A limited set of types from UniversalSerializer have a predefined identifier.
They are numbered from 25 (Twenty-five). - The described types, specific to a particular stream, are numbered from:
- 35 (thirty-five) in the file format 2.0.
- 45 (forty-five) in the file format 3.0.
- At any moment, a class instance can be serialized.
When deserialized, this value is added to the instance list. Its identifier depends on its order in this list. - To save space, the obvious information are not serialized to the stream.
- The type of a value is not specified when it is the type of the field/collection-item.
- As said, the identifier of a class instance is deducted from its order in the class instance list.
- When entering the type stream sequence, the type SerializationTypeDescriptorCollection is attended.
The codes that structure the stream:
Code | binary | xml | json | details |
Collection | 7 | <c> | "c": | Entering a collection of items. |
Default value | 5 | <f> | "f": | A default value, in place of a serialized value. The actual value depends on the declaring type. |
Dictionary | 8 | <d> | "d": | Entering a dictionary of pairs. |
End | 20 | <end/> | "end": | Specifies the end of a serialization sequence. |
Instances stream | 1 | <s1> | "s1": | Entering the virtual sub-stream 1: the instance stream. |
Null value | 4 | <z> | "z": | A null value, in place of an instance identifier. It can specify an empty collection too. |
Primitive value | 2 | <p> | "p": | A value. Its type is "primitive" as it belongs to TypeCode. |
Reference | 3 | <r> | "r": | A reference to a class instance. |
Serialization sequence | implicit | <data> | implicit | Every time Serialize() is called, this sequence/tree-root is added to the main stream. |
Sub-branch | 6 | <b> | "b": | Entering a sub-branch of the tree. |
Types stream | 0 | <s0> | "s0": | Entering the virtual sub-stream 0: the type descriptor stream. |
The properties/attributes of the structural codes:
Property | Apply to codes | binary | xml | json | details |
Type identifier | Sub-branch | 16 | <b t="30"> | "t": | Specifies what type applies to the value. This identifier is an integer number. |
Length | Sub-branch, collections and dictionaries | 32 | <b l="1"> | "l": | The total number of items in the collection, dictionary or sub-branch. |
Instance identifier | Reference | deducted | <r i="1"/> | "i": | Gives a number as an instance identifier. |
Name | no | n="TheName" | "n": | Name ("debugging" only). | |
Type name | no | typeName="TheType" | typeName | The type name ("debugging" only). |
The predefined types:
Identifier | Category | Type |
0 | not a type | |
1 | Primitive | System.Object |
2 | Primitive | unused (DBNull in TypeCode) |
3 | Primitive | System.Boolean |
4 | Primitive | System.Char |
5 | Primitive | System.SByte |
6 | Primitive | System.Byte |
7 | Primitive | System.Int16 |
8 | Primitive | System.UInt16 |
9 | Primitive | System.Int32 |
10 | Primitive | System.UInt32 |
11 | Primitive | System.Int64 |
12 | Primitive | System.UInt64 |
13 | Primitive | System.Single |
14 | Primitive | System.Double |
15 | Primitive | System.Decimal |
16 | Primitive | System.DateTime |
17 | Primitive | unused (removed from TypeCode in the past) |
18 | Primitive | System.String |
25 | Internal | System.Int32[] |
26 | Internal | System.String[] |
27 | Internal | UniversalSerializerLib3.SerializationTypeDescriptor |
28 | Internal | UniversalSerializerLib3.SerializationTypeDescriptorCollection |
29 | Internal | UniversalSerializerLib3.StreamFormat3.AssemblyIdentifier |
30 | Internal | UniversalSerializerLib3.StreamFormat3.AssemblyIdentifier[] |
31 | Internal | UniversalSerializerLib3.StreamFormat3.Header |