What Is Ion?

Quoting the official Ion documentation:

Amazon Ion is a richly-typed, self-describing, hierarchical data serialization format offering interchangeable binary and text representations. The text format (a superset of JSON) is easy to read and author, supporting rapid prototyping.

The binary representation is efficient to store, transmit, and skip-scan parse.

The rich type system provides unambiguous semantics for longterm preservation of data which can survive multiple generations of software evolution.

Ion was built to address rapid development, decoupling, and efficiency challenges faced every day while engineering large-scale, service-oriented architectures.

Some simple examples

Serialization:


<?=
ion\serialize
([
  
"key" => "value",
  
"more" => [
    
"data" => 123
  
]
]);
?>
Output:

{key:"value",more:{data:123}}

If you now think that this looks a lot like JSON, you're probably right, because Ion is a superset of JSON:


<?=
json_encode
([
  
"key" => "value",
  
"more" => [
    
"data" => 123
  
]
]);
?>
Output:

{"key":"value","more":{"data":123}}

So, all valid JSON is also valid Ion. Please refer to the official spec to learn more about this topic.

Unserialization:


<?=
var_representation
(
  
ion\unserialize('{key:"value",more:{data:123}}')
);
?>
Output:

[
  'key' => 'value',
  'more' => [
    'data' => 123,
  ],
]

If you try the same with the JSON equivalent, you'll see that it's basically valid Ion, too:


<?=
var_representation
(
  
ion\unserialize('{"key":"value","more":{"data":123}}')
);
?>
Output:

[
  'key' => 'value',
  'more' => [
    'data' => 123,
  ],
]

Multiple documents

Ion supports multiple sequences of documents within a single stream; consider the following:


<?=
var_representation
(
  
ion\unserialize('
    {"key":"value","more":{"data":123}}
    {"key":"value","more":{"data":456}}
  '
, new ion\Unserializer\Unserializer(multiSequencetrue)
  )
);
?>

Output:


[
  [
    'key' => 'value',
    'more' => [
      'data' => 123,
    ],
  ],
  [
    'key' => 'value',
    'more' => [
      'data' => 456,
    ],
  ],
]

Annotations

Any Ion value can include one or more annotation symbols denoting the semantics of the content. This can be used to:

In the text format, type annotations are denoted by a non-null symbol token and double-colons preceding any value. Multiple annotations on the same value are separated by double-colons:


int32::12                                // Suggests 32 bits as end-user type
degrees::'celsius'::100                  // You can have multiple annotaions on a value
'my.custom.type' :: { x : 12 , y : -1 }  // Gives a struct a user-defined type

{ field: some_annotation::value }        // Field's name must precede annotations of its value

jpeg :: {{ ... }}                        // Indicates the blob contains jpeg data
bool :: null.int                         // A very misleading annotation on the integer null
'' :: 1                                  // An empty annotation
null.symbol :: 1                         // ERROR: type annotation cannot be null 

Except for a small number of predefined system and PHP annotations, Ion itself neither defines nor validates such annotations; that behavior is left to applications or tools (such as schema validators).

It’s important to understand that annotations are symbol tokens, not symbol values. That means they do not have annotations themselves. In particular, the text a::c is a single value consisting of three textual tokens (a symbol, a double-colon, and another symbol); the first symbol token is an annotation on the value, and the second is the content of the value.

System Annotations


<?php

foreach (ion\Symbol\System::cases() as $e) {
  
printf("%30s:: => %s\n"$e->value$e->name);
}

/*
                          $ion:: => Ion
                      $ion_1_0:: => Ivm_1_0
             $ion_symbol_table:: => IonSymbolTable
                          name:: => Name
                       version:: => Version
                       imports:: => Imports
                       symbols:: => Symbols
                        max_id:: => MaxId
      $ion_shared_symbol_table:: => SharedSymbolTable
*/

?>

PHP Annotations

There are two handful of annotations used by PHP, which are centralized in the ion\Symbol\PHP enumeration:


<?php

foreach (ion\Symbol\PHP::cases() as $e) {
  
printf("%3s:: => %s\n"$e->value$e->name);
}

/*
  PHP:: => PHP
    R:: => Reference
    r:: => Backref
    p:: => Property
    o:: => Object
    c:: => ClassObject
    O:: => MagicObject
    C:: => CustomObject
    E:: => Enum
    S:: => Serializable
*/

?>

Next up