binary-encoding.adoc

pkl-binary Encoding

Pkl values can be encoded into a binary format called "pkl-binary". This format is a lossless serialization of the underlying Pkl values.

Pkl code can be rendered into this format using the {uri-stdlib-pklbinaryModule}[pkl:pklbinary] standard library module.

Alternatively, many language bindings also provide methods to evaluate into pkl-binary, such as the evaluateExpressionPklBinary method in org.pkl.core.Evaluator.

The binary format is uses MessagePack encoding.

Primitives

All Pkl primitives turn into their respective MessagePack primitive.

Pkl Type	MessagePack format
Int	int
Float	float
String	string
Boolean	bool
Null	nil

Note	Pkl integers are encoded into the smallest int type that the number will fit into. For example, value 8 gets encoded as MessagePack int8 format.

Non-primitives

All non-primitive values are encoded as MessagePack arrays. The first slot of the array designates the value’s type. The remaining slots have fixed meanings depending on the type. Additional slots may be added to types in future Pkl releases. Decoders must be designed to defensively discard values beyond the number of known slots for a type or provide meaningful error messages.

The array’s length is the number of slots that are filled. For example, List is encoded as an MessagePack array with two elements.

Pkl type	Slot 1	Slot 2		Slot 3		Slot 4
	code	type	description	type	description	type	description
Typed, Dynamic	0x01	str	Class name	str	Enclosing module URI	array	Array of object members
Map	0x02	map	Map of <value> to <value>
Mapping	0x03	map	Map of <value> to <value>
List	0x04	array	Array of <value>
Listing	0x05	array	Array of <value>
Set	0x06	array	Array of <value>
Duration	0x07	{uri-messagepack-float}[float64]	Duration value	str	Duration unit ("ns", "ms", etc.)
DataSize	0x08	float64	Value (float64)	str	DataSize unit ("b", "kb", etc.)
Pair	0x09	<value>	First value	<value>	Second value
IntSeq	0x0A	int	Start	int	End	int	Step
Regex	0x0B	str	Regex string representation
Class	0x0C	str	Class name	str	Module URI
TypeAlias	0x0D	str	TypeAlias name	str	Module URI
Function	0x0E
Bytes	0x0F	bin	Binary contents
Reference	0x20	<value>	Root value	array	Array of property access values
ReferenceAccess	0x21	str (when a property access) or nil (when a subscript access)	Property name	<value> or nil (when a property access)	Key value

Note

Type names have specific encoding rules: When the module URI is pkl:base: If the type name is ModuleClass, this type represents the module class of pkl:base. Otherwise, the type name corresponds to a type in pkl:base. For all other module URIs: When the type name contains #, the string after the # character corresponds to a type in that module. The string before the # is the name of the module. Otherwise, the type name is the name of the module and represents the class of the module.

Object Members

Like non-primitive values, object members are encoded as MessagePack arrays, where the first slot designates the value’s type.

Member type	Slot 1	Slot 2		Slot 3
	code	type	description	type	description
Property	0x10	str	key	<value>	property value
Entry	0x11	<value>	entry key	<value>	entry value
Element	0x12	int	index	<value>	element value