tip: 21
title: Serialization Primitives
description: Introduce primitives to describe the binary serialization of objects.
author: Wolfgang Welz (@Wollac) 
discussions-to: https://github.com/iotaledger/tips/pull/41
status: Active
type: Standards
layer: Core
created: 2021-11-22

Summary

This document introduces the primitives and concepts that are used throughout the IOTA protocol RFCs to describe the binary serialization of objects.

Motivation

Prior to this document, each RFC contained its own section and version describing the serialization of its objects. This RFC introduces consistent serialization concepts and avoids duplication in other RFCs.

Detailed design

Schemas

Serializable objects are represented by a schema. Each schema consists of a list of fields, which each have a name and a type. The type of a field can either be a simple data type or another schema, then called subschema.

Data types

All the supported data types are described in the following table:

Name	Description
uint8	An unsigned 8-bit integer encoded in Little Endian.
uint16	An unsigned 16-bit integer encoded in Little Endian.
uint32	An unsigned 32-bit integer encoded in Little Endian.
uint64	An unsigned 64-bit integer encoded in Little Endian.
uint256	An unsigned 256 bits integer encoded in Little Endian.
ByteArray[N]	A static size byte array of N bytes.
(uint8)ByteArray	A dynamically sized byte array. A leading uint8 denotes its length in bytes.
(uint16)ByteArray	A dynamically sized byte array. A leading uint16 denotes its length in bytes.
(uint32)ByteArray	A dynamically sized byte array. A leading uint32 denotes its length in bytes.

Subschemas

In order to create complex schemas, one or multiple subschemas can be included into an outer schema. The keywords that describe the allowed combinations of such subschemas is described in the following table:

Name	Description
`oneOf`	One of the listed subschemas.
`optOneOf`	One of the listed subschemas or none.
`anyOf`	Any (one or more) of the listed subschemas.
`optAnyOf`	Any (one or more) of the listed subschemas or none.
`atMostOneOfEach`	At most one (none or one) of each of the listed subschemas.

The Tangle Improvement Proposal (TIP) Book