3 Quoting the [official Ion documentation](https://amzn.github.io/ion-docs/):
5 **Amazon Ion** is a [richly-typed](ion/:%20Tutorial/:1.%20Getting%20started#Rich.type.system), [self-describing](ion/:%20Tutorial/:1.%20Getting%20started#Self-describing), hierarchical data serialization format offering [interchangeable binary and text](https://amzn.github.io/ion-docs/guides/why.html#dual-format-interoperability) representations. The [text format](https://amzn.github.io/ion-docs/docs/spec.html) (a superset of [JSON](http://json.org/)) is easy to read and author, supporting rapid prototyping.
7 The [binary representation](https://amzn.github.io/ion-docs/docs/binary.html) is [efficient to store, transmit, and skip-scan parse](https://amzn.github.io/ion-docs/guides/why.html#read-optimized-binary-format).
9 The rich type system provides unambiguous semantics for longterm preservation of data which can survive multiple generations of software evolution.
11 Ion was built to address rapid development, decoupling, and efficiency challenges faced every day while engineering large-scale, service-oriented architectures.
13 ### Some simple examples
31 {key:"value",more:{data:123}}
34 If you now think that this looks a lot like JSON, you're probably right, because Ion is a superset of JSON:
50 {"key":"value","more":{"data":123}}
53 So, all valid JSON is also valid Ion. Please refer to the [official spec](https://amzn.github.io/ion-docs/docs/spec.html) to learn more about this topic.
60 ion\unserialize('{key:"value",more:{data:123}}')
76 If you try the same with the JSON equivalent, you'll see that it's basically valid Ion, too:
81 ion\unserialize('{"key":"value","more":{"data":123}}')
97 ### Multiple documents
99 Ion supports multiple sequences of documents within a single stream; consider the following:
105 {"key":"value","more":{"data":123}}
106 {"key":"value","more":{"data":456}}
107 ', new ion\Unserializer\PHP(multiSequence: true)
134 Any Ion value can include one or more annotation symbols denoting the semantics of the content. This can be used to:
136 - Annotate individual values with schema types, for validation purposes.
137 - Associate a higher-level datatype (e.g. a Java class) during serialization processes.
138 - Indicate the notation used within a `blob` or `clob` value.
139 - Apply other application semantics to a single value.
141 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:
144 int32::12 // Suggests 32 bits as end-user type
145 degrees::'celsius'::100 // You can have multiple annotaions on a value
146 'my.custom.type' :: { x : 12 , y : -1 } // Gives a struct a user-defined type
148 { field: some_annotation::value } // Field's name must precede annotations of its value
150 jpeg :: {{ ... }} // Indicates the blob contains jpeg data
151 bool :: null.int // A very misleading annotation on the integer null
152 '' :: 1 // An empty annotation
153 null.symbol :: 1 // ERROR: type annotation cannot be null
156 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).
158 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.
160 #### System Annotations
165 foreach (ion\Symbol\System::cases() as $e) {
166 printf("%30s:: => %s\n", $e->value, $e->name);
171 $ion_1_0:: => Ivm_1_0
172 $ion_symbol_table:: => IonSymbolTable
178 $ion_shared_symbol_table:: => SharedSymbolTable
186 There are two handful of annotations used by PHP, which are centralized in the ion\Symbol\PHP enumeration:
191 foreach (ion\Symbol\PHP::cases() as $e) {
192 printf("%3s:: => %s\n", $e->value, $e->name);
215 * [Standard Datatypes](ion/:%20Tutorial/:3.%20Standard%20Datatypes)