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 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
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

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

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