CINXE.COM

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="/css/layout.css?1718759055581"> <link rel="stylesheet" href="/css/nav.css?1718759055581"> <link rel="stylesheet" href="/css/style.css?1718759055581"> <link rel="stylesheet" href="/css/prismjs@1.24-themes-prism.css"> <title>IPLD ♦ Schemas: Representation Strategies</title> </head> <body> <header> <div class="sidebar-button" onclick="document.getElementById('sidebar').classList.toggle('sidebar-open')"> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"> <path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path> </svg> </div> <a href="/" class="logo">IPLD</a> <aside id=breadcrumbs> <ul> <li><a href="/docs">docs</a></li> <li><a href="/docs/schemas">schemas</a></li> <li><a href="/docs/schemas/features">features</a></li> <li><a href="/docs/schemas/features/representation-strategies/">representation-strategies</a></li> </ul> </aside> </header> <aside id=sidebar> <nav> <ul> <li> <a href="/docs/">Docs</a><ul> <li> <a href="/docs/intro/">Intro</a><ul> <li> <a href="/docs/intro/hello-world/">Hello, World</a></li> <li> <a href="/docs/intro/primer/">The Brief Primer</a></li> <li> <a href="/docs/intro/ecosystem/">InterPlanetary Ecosystem Overview</a></li> <li> <a href="/docs/intro/community/">Finding Community</a></li></ul></li> <li> <a href="/docs/motivation/">Motivation</a><ul> <li> <a href="/docs/motivation/benefits-of-content-addressing/">Benefits of Content Addressing</a></li> <li> <a href="/docs/motivation/data-to-data-structures/">From Data to Data Structures</a></li></ul></li> <li> <a href="/docs/codecs/">Codecs</a><ul> <li> <a href="/docs/codecs/known/">Known Codecs</a><ul> <li> <a href="/docs/codecs/known/dag-cbor/">DAG-CBOR</a></li> <li> <a href="/docs/codecs/known/dag-json/">DAG-JSON</a></li> <li> <a href="/docs/codecs/known/dag-pb/">DAG-PB</a></li></ul></li></ul></li> <li> <a href="/docs/data-model/">Data Model</a><ul> <li> <a href="/docs/data-model/node/">Nodes</a></li> <li> <a href="/docs/data-model/kinds/">Kinds</a></li> <li> <a href="/docs/data-model/pathing/">Pathing</a></li> <li> <a href="/docs/data-model/traversal/">Traversal</a></li></ul></li> <li> <a href="/docs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/docs/advanced-data-layouts/intro/">Intro to ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/naming/">ADL Naming</a></li> <li> <a href="/docs/advanced-data-layouts/signalling/">Signalling ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/dynamic-loading/">Dynamic Loading</a></li> <li> <a href="/docs/advanced-data-layouts/known/">Known ADLs</a></li></ul></li> <li> <a href="/docs/schemas/">Schemas</a><ul> <li> <a href="/docs/schemas/intro/">Introduction</a><ul> <li> <a href="/docs/schemas/intro/compare/">compare</a></li> <li> <a href="/docs/schemas/intro/goals/">Goals</a></li> <li> <a href="/docs/schemas/intro/feature-summary/">Feature Summary</a></li></ul></li> <li> <a href="/docs/schemas/features/">Features</a><ul> <li> <a href="/docs/schemas/features/typekinds/">Type Kinds</a></li> <li class="active-page"> <a href="/docs/schemas/features/representation-strategies/">Representation Strategies</a></li> <li> <a href="/docs/schemas/features/links/">Links</a></li> <li> <a href="/docs/schemas/features/indicating-adls/">Using ADLs in Schemas</a></li></ul></li> <li> <a href="/docs/schemas/using/">Using Wisely</a><ul> <li> <a href="/docs/schemas/using/authoring-guide/">Authoring Guide</a></li> <li> <a href="/docs/schemas/using/migrations/">Migrations</a></li></ul></li></ul></li> <li> <a href="/docs/synthesis/">Synthesis</a><ul> <li> <a href="/docs/synthesis/gtd/">Getting Things Done</a></li> <li> <a href="/docs/synthesis/building-in-alignment/">Building in Alignment</a></li> <li> <a href="/docs/synthesis/how-ipfs-web-gateways-work/">How IPFS Web Gateways Work</a></li> <li> <a href="/docs/synthesis/encryption/">Working With Encryption</a></li></ul></li></ul></li> <li> <a href="/specs/">Specs</a><ul> <li> <a href="/specs/about/">About the Specifications</a></li> <li> <a href="/specs/codecs/">Codecs</a><ul> <li> <a href="/specs/codecs/dag-cbor/">DAG-CBOR</a><ul> <li> <a href="/specs/codecs/dag-cbor/fixtures/">DAG-CBOR Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-cbor/fixtures/cross-codec/">cross-codec</a></li></ul></li> <li> <a href="/specs/codecs/dag-cbor/spec/">Spec</a></li></ul></li> <li> <a href="/specs/codecs/dag-cosmos/">DAG-COSMOS</a><ul> <li> <a href="/specs/codecs/dag-cosmos/basic_types/">basic_types</a></li> <li> <a href="/specs/codecs/dag-cosmos/cosmos_state/">cosmos_state</a></li> <li> <a href="/specs/codecs/dag-cosmos/crypto_types/">crypto_types</a></li> <li> <a href="/specs/codecs/dag-cosmos/tendermint_chain/">tendermint_chain</a></li> <li> <a href="/specs/codecs/dag-cosmos/typed_protobuf/">typed_protobuf</a></li></ul></li> <li> <a href="/specs/codecs/dag-eth/">DAG-ETH</a><ul> <li> <a href="/specs/codecs/dag-eth/basic_types/">basic_types</a></li> <li> <a href="/specs/codecs/dag-eth/chain/">chain</a></li> <li> <a href="/specs/codecs/dag-eth/convenience_types/">convenience_types</a></li> <li> <a href="/specs/codecs/dag-eth/state/">state</a></li></ul></li> <li> <a href="/specs/codecs/dag-jose/">DAG-JOSE</a><ul> <li> <a href="/specs/codecs/dag-jose/fixtures/">fixtures</a></li> <li> <a href="/specs/codecs/dag-jose/spec/">Spec</a></li></ul></li> <li> <a href="/specs/codecs/dag-json/">DAG-JSON</a><ul> <li> <a href="/specs/codecs/dag-json/fixtures/">DAG-JSON Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-json/fixtures/cross-codec/">cross-codec</a></li></ul></li> <li> <a href="/specs/codecs/dag-json/spec/">Spec</a></li></ul></li> <li> <a href="/specs/codecs/dag-pb/">DAG-PB</a><ul> <li> <a href="/specs/codecs/dag-pb/fixtures/">DAG-PB Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-pb/fixtures/cross-codec/">cross-codec</a></li></ul></li> <li> <a href="/specs/codecs/dag-pb/spec/">Spec</a></li></ul></li></ul></li> <li> <a href="/specs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/">FBL ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/spec/">spec</a></li></ul></li> <li> <a href="/specs/advanced-data-layouts/hamt/">HAMT ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/">HashMap (HAMT) Test Fixtures</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/alice-words/">alice-words</a></li></ul></li> <li> <a href="/specs/advanced-data-layouts/hamt/spec/">spec</a></li></ul></li></ul></li> <li> <a href="/specs/schemas/">Schemas</a><ul> <li> <a href="/specs/schemas/prelude/">prelude</a></li></ul></li> <li> <a href="/specs/transport/">Transports</a><ul> <li> <a href="/specs/transport/car/">CAR</a><ul> <li> <a href="/specs/transport/car/carv1/">CARv1 Specification</a></li> <li> <a href="/specs/transport/car/carv2/">CARv2 Specification</a></li> <li> <a href="/specs/transport/car/fixture/">CAR Test Fixtures</a><ul> <li> <a href="/specs/transport/car/fixture/carv1-basic/">carv1-basic</a></li> <li> <a href="/specs/transport/car/fixture/carv2-basic/">carv2-basic</a></li></ul></li></ul></li> <li> <a href="/specs/transport/graphsync/">Graphsync</a><ul> <li> <a href="/specs/transport/graphsync/known_extensions/">known_extensions</a></li></ul></li> <li> <a href="/specs/transport/trustless-pathing/">Trustless Pathing</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/">Trustless Pathing Fixtures</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/unixfs_20m_variety/">unixfs_20m_variety</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/selectors/">Selectors</a><ul> <li> <a href="/specs/selectors/fixtures/">fixtures</a><ul> <li> <a href="/specs/selectors/fixtures/selector-fixtures-1/">selector-fixtures-1</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-adl/">selector-fixtures-adl</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-recursion/">selector-fixtures-recursion</a></li></ul></li></ul></li> <li> <a href="/specs/patch/">Patch</a><ul> <li> <a href="/specs/patch/fixtures/">IPLD Patch Test Fixtures</a><ul> <li> <a href="/specs/patch/fixtures/fixtures-1/">fixtures-1</a></li></ul></li></ul></li></ul></li> <li> <a href="/libraries/">Libraries</a><ul> <li> <a href="/libraries/golang/">Golang</a></li> <li> <a href="/libraries/javascript/">JavaScript</a></li> <li> <a href="/libraries/python/">Python</a></li> <li> <a href="/libraries/rust/">Rust</a></li></ul></li> <li> <a href="/design/">Design</a><ul> <li> <a href="/design/objectives/">Objectives</a></li> <li> <a href="/design/concepts/">Concepts</a><ul> <li> <a href="/design/concepts/type-theory-glossary/">type-theory-glossary</a></li></ul></li> <li> <a href="/design/libraries/">Libraries</a><ul> <li> <a href="/design/libraries/nodes-and-kinds/">nodes-and-kinds</a></li></ul></li> <li> <a href="/design/tricky-choices/">Tricky Choices</a><ul> <li> <a href="/design/tricky-choices/dag-pb-forms-impl-and-use/">dag-pb-forms-impl-and-use</a></li> <li> <a href="/design/tricky-choices/map-key-domain/">map-key-domain</a></li> <li> <a href="/design/tricky-choices/numeric-domain/">numeric-domain</a></li> <li> <a href="/design/tricky-choices/ordering/">ordering</a></li> <li> <a href="/design/tricky-choices/string-domain/">string-domain</a></li></ul></li> <li> <a href="/design/open-research/">Open Research</a><ul> <li> <a href="/design/open-research/ADL-autoexecution/">ADL autoexecution</a></li></ul></li></ul></li> <li> <a href="/tools/">Tools</a></li> <li> <a href="/glossary/">Glossary</a></li> <li> <a href="/media/">Media</a></li> <li> <a href="/FAQ/">FAQ</a></li></ul> </nav> </aside> <main> <div class=content> <h1>Representations of IPLD Schema Kinds</h1> <ul> <li><a href="#available-representation-strategies">Available Representation Strategies</a></li> <li><a href="#representation-strategy-reference">Representation Strategy Reference</a> <ul> <li><a href="#struct-map-representation">Struct <code>map</code> Representation</a></li> <li><a href="#struct-tuple-representation">Struct <code>tuple</code> Representation</a></li> <li><a href="#struct-stringpairs-representation">Struct <code>stringpairs</code> Representation</a></li> <li><a href="#struct-stringjoin-representation">Struct <code>stringjoin</code> Representation</a></li> <li><a href="#struct-listpairs-representation">Struct <code>listpairs</code> Representation</a></li> <li><a href="#map-map-representation">Map <code>map</code> Representation</a></li> <li><a href="#map-stringpairs-representation">Map <code>stringpairs</code> Representation</a></li> <li><a href="#map-listpairs-representation">Map <code>listpairs</code> Representation</a></li> <li><a href="#union-keyed-representation">Union <code>keyed</code> Representation</a></li> <li><a href="#union-kinded-representation">Union <code>kinded</code> Representation</a></li> <li><a href="#union-envelope-representation">Union <code>envelope</code> Representation</a></li> <li><a href="#union-inline-representation">Union <code>inline</code> Representation</a></li> <li><a href="#union-bytesprefix-representation">Union <code>bytesprefix</code> Representation</a></li> <li><a href="#enum-string-representation">Enum <code>string</code> Representation</a></li> <li><a href="#enum-int-representation">Enum <code>int</code> Representation</a></li> </ul> </li> </ul> A type at the Schema layer must be mapped onto a representation expressible within the Data Model. Each Schema type, therefore, has a "representation kind" which dictates what Data Model kind it is represented as. Each Schema type has a "representation strategy" for converting it, where required, into a "representation kind". For all Schema kinds which have direct equivalents in the Data Model (e.g. Int, String, Float), that kind is also the representation kind and there is a default representation strategy (mostly implicitly) named after that kind, i.e. a String schema kind has a String representation kind and also a <code>string</code> representation strategy that is a direct transference through the Data Model. The default representation is, broadly speaking, a no-op: a string remains a string, and a map is easy to enough to represent as a map! The Schema layer introduces additional kinds (see <a href="../typekinds/">TypeKinds</a>) that can be thought of as "perceived kinds", in that they have no direct equivalent in the Data Model but can be represented there and perceived as something different when passing through the Schema layer. Most also have default mappings. For example, A Struct maps directly to a Data Model Map, where the Struct's fields are Map keys and the Struct's field's values are the values found at the values of the Map's keys: <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { x Int y Int msg String }</code></pre> May be deserialized from a JSON map: <pre class="language-json"><code class="language-json">{ "x": 10005510, "y": -21183, "msg": "A treasure chest is found at this location" }</code></pre> By default, Enums map to String kinds where no other strategy is declared. Unions are a special case as there's no single widely agreed upon transcription pattern for unions (from before the establishment of IPLD), so these require an explicit choice. Maps, Structs, Enums and Unions all have more than one possible representation strategy. The default representation strategy for Maps, Struct and Enums is implicit and need not be stated, but we could rewrite our example above to be explicit: <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { x Int y Int msg String } representation map</code></pre> Representation strategies are identified by one primary keyword, which indicates what kind in the Data Model will be transcribed to. Some representation strategies have additional parameters, some optional and some mandatory. Such parameters, where they apply to the type as a whole, may be located inside a separate block (<code>{</code>, <code>}</code>) following the declaration of the representation strategy. Where those parameters impact specific fields of a type, they are presented inline with the field in parens (<code>(</code>, <code>)</code>) to indicate that they do not directly impact the user-facing form of the type but rather the serialized form. For example, a type declaration laden with representation parameters: <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { x Int (rename "a") y Int (rename "b" implicit "0") msg String } representation stringpairs { innerDelim "=" entryDelim "," }</code></pre> <h2 id="available-representation-strategies" tabindex="-1"><a class="header-anchor" href="#available-representation-strategies">Available Representation Strategies</a></h2> Schema kinds for which no meaningful customization is possible: Null, Boolean, Integer, Float, String, Bytes, List and Link are not included in this list. (Custom custom representation strategies for these kinds has not been ruled out and may be introduced in the future.) In addition to the representation strategies that are built-in to IPLD Schemas, <a href="/glossary/#adl">Advanced Data Layouts</a> can also be used to change the way data is perceived and persisted. Discussion of Advanced Data Layouts and their ability to provide entirely custom representation strategies of various type can be found in the page on <a href="../indicating-adls/">Indicating ADLs in IPLD Schemas</a>. The following are the representation strategies built-in to IPLD Schemas: <ul> <li>Map <ul> <li><code>map</code>: (default) transcribes to Map in the Data Model.</li> <li><code>stringpairs</code>: transcribes to String in the Data Model.</li> <li><code>listpairs</code>: transcribes to List (of Lists) in the Data Model.</li> </ul> </li> <li>Union <ul> <li><code>keyed</code>: transcribes to a single-entry Map in the Data Model.</li> <li><code>kinded</code>: transcribes to varying kinds in the Data Model, see below for details.</li> <li><code>envelope</code>: transcribes to a dual-entry Map in the Data Model.</li> <li><code>inline</code>: transcribes to a Map in the Data Model (and has additional limitations).</li> <li><code>bytesprefix</code>: transcribes to Bytes in the Data Model, only usable for unions of Bytes.</li> </ul> </li> <li>Struct <ul> <li><code>map</code>: (default) transcribes to Map in the Data Model.</li> <li><code>tuple</code>: transcribes to List in the Data Model.</li> <li><code>stringpairs</code>: transcribes to String in the Data Model.</li> <li><code>stringjoin</code>: transcribes to String in the Data Model.</li> <li><code>listpairs</code>: transcribes to List (of Lists) in the Data Model.</li> </ul> </li> <li>Enum <ul> <li><code>string</code>: (default) transcribes the enum values as String in the Data Model.</li> <li><code>int</code>: transcribes the enum values as Int in the Data Model.</li> </ul> </li> </ul> Each of these representation strategies will be explored in detail in below. <h2 id="representation-strategy-reference" tabindex="-1"><a class="header-anchor" href="#representation-strategy-reference">Representation Strategy Reference</a></h2> <h3 id="struct-map-representation" tabindex="-1"><a class="header-anchor" href="#struct-map-representation">Struct <code>map</code> Representation</a></h3> Representation Kind: Map A Data Model Map representation of Structs means that the Struct is represented as a Map, where the keys are the names of the Struct fields. This is a common and natural way to represent Structs and is therefore their default representation. As the default, this strategy is inferred in absence of any other. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String fieldTwo Bool } representation map</code></pre> In this case, <code>representation map</code> could have been elided. Some data matching the <code>Foo</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "fieldOne": "this is field one", "fieldTwo": true }</code></pre> The <code>map</code> Struct representation strategy also allows for field-specific parameters which may be specified after the fields in the main declaration. The two parameters are: <ul> <li><code>rename</code> to declare that at serialization and deserialization, this field has an alternate name in the underlying Data Model Map. This may be useful for providing verbose names at the Schema layer but compact names in the encoding, for example.</li> <li><code>implicit</code> to declare that a particular value of this field is assumed if the field is omitted from serialized form. This applies to both serialization and deserialization. A common example may be <code>implicit "false"</code> so that a Bool field need only be present in the serialized form when it is <code>true</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String (rename "one") fieldTwo Bool (rename "two" implicit "false") } representation map</code></pre> The field-specific parameters (<code>rename</code> and <code>implicit</code>) are only available for the <code>map</code> Struct representation strategy. They are technically possible in some other forms (i.e. <code>listpairs</code> and <code>stringpairs</code>) and support may be extended in the future. See <a href="../typekinds/#value-type-modifiers">Value Type Modifiers</a> for a discussion on such matters as well as the impacts on value cardinality. <h3 id="struct-tuple-representation" tabindex="-1"><a class="header-anchor" href="#struct-tuple-representation">Struct <code>tuple</code> Representation</a></h3> Representation Kind: List The <code>tuple</code> Struct representation strategy allows Structs to be packed into a compact List representation. This List representation drops the Struct field's names from the representation entirely and relies entirely on the order of elements to denote meaning. As such, it is generally a very compact way to represent data. <code>tuple</code> Struct representation strategies should be used cautiously. Since they contain little in the way of "self-describing" information, <code>tuple</code> Struct representations can make for very fragile protocols, increase the difficulty of migrations, and make serialized data incomprehensible without the schema information in hand. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String fieldTwo Bool } representation tuple</code></pre> Some data matching the <code>Foo</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">["this is field one", true]</code></pre> Notice how this is the same data as in the <code>map</code> Struct representation strategy example above; it's just much more compact than it was in the map representation (and beware: correspondingly less self-describing!). Optional or implicit fields are not possible with the <code>tuple</code> Struct representation strategy, all elements must be present. No field-specific parameters are available for the <code>tuple</code> Struct representation strategy (i.e. <code>implicit</code> and <code>rename</code> which are available for <code>map</code>). One general parameter is available: <ul> <li><code>fieldOrder</code> declares that the fields are serialized in a particular order that may be different from the order presented in the type descriptor. This option is implicitly set to the declared order but may be overridden where needed.</li> </ul> Example <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String fieldTwo Bool } representation tuple { fieldOrder ["fieldTwo", "fieldOne"] }</code></pre> Serialization of such a type in JSON may appear as: <pre class="language-json"><code class="language-json">[ true, "this is field one" ]</code></pre> <h3 id="struct-stringpairs-representation" tabindex="-1"><a class="header-anchor" href="#struct-stringpairs-representation">Struct <code>stringpairs</code> Representation</a></h3> Representation Kind: String The <code>stringpairs</code> Struct representation strategy encodes a Struct to a single String. It should be used with special caution as there are no escaping mechanisms in place to prevent incompatible data from disrupting the encoding and causing errors during decode operations. The encoding presents key / value pairs as a delimited String. e.g. <code>"k1=v1,k2=v2"</code> rather than <code>{ "k1": "v1", "k2": "v2" }</code> if the same data used a <code>map</code> Struct representation strategy. The entry delimiter and the key / value (inner) delimiter must be specified as general parameters when <code>stringpairs</code> is used, there is no default for these. In our example, the <code>entryDelim</code> would be <code>","</code> while the <code>innerDelim</code> would be <code>"="</code>. This serial representation is strictly limited: the domain of available for field names must exclude the <code>innerDelim</code> in any position and values and keys must exclude the <code>entryDelim</code> in any position. There is no facility for escaping, such as in escaped CSV. This also leads to a further restriction that this representation is only valid for Structs whose values may all be encoded to String kind in the Data Model layer. It is recommended, therefore, that its use be limited to Structs containing values with the basic data model kinds that exclude multiple values, i.e. no Maps, Lists, and therefore Structs or Unions or any other type that has a recursive representation kind. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String fieldTwo Bool } representation stringpairs { innerDelim "=" entryDelim "," }</code></pre> Some data matching the <code>Foo</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">"fieldOne=this is field one,fieldTwo=true"</code></pre> No field-specific parameters are available for the <code>stringpairs</code> Struct representation strategy (i.e. <code>implicit</code> and <code>rename</code> which are available for <code>map</code>). The two general parameters are mandatory: <ul> <li><code>innerDelim</code> declares a quoted string that is used to delimit a key from a value</li> <li><code>entryDelim</code> declares a quoted string that is used to delimit entries from each other</li> </ul> <h3 id="struct-stringjoin-representation" tabindex="-1"><a class="header-anchor" href="#struct-stringjoin-representation">Struct <code>stringjoin</code> Representation</a></h3> Representation Kind: String The <code>stringjoin</code> Struct representation strategy encodes a Struct to a single String. It should be used with special caution as there are no escaping mechanisms in place to prevent incompatible data from disrupting the encoding and causing errors during decode operations. <code>stringjoin</code> is very similar to <code>stringpairs</code> and caries many of the same notes of caution. The difference is that <code>stringjoin</code> omits the keys and relies instead on declared field order to assume the location of the field values, similar to the <code>tuple</code> representation. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Fizzlebop struct { a String b String } representation stringjoin { join ":" }</code></pre> Some data matching the <code>Fizzlebop</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">"value-of-a:value-of-b"</code></pre> Since there is no escaping mechanism, no value can contain the string used for <code>join</code> as this would disrupt decoding and result in an error. Additionally, optional or implicit fields are not possible with the <code>stringjoin</code> Struct representation strategy, all elements must be present. No field-specific parameters are available for the <code>stringjoin</code> Struct representation strategy (i.e. <code>implicit</code> and <code>rename</code> which are available for <code>map</code>). The single general parameter is mandatory: <ul> <li><code>join</code> declares a quoted string that is used to delimit field values</li> </ul> <h3 id="struct-listpairs-representation" tabindex="-1"><a class="header-anchor" href="#struct-listpairs-representation">Struct <code>listpairs</code> Representation</a></h3> Representation Kind: List The <code>listpairs</code> Struct representation strategy encodes a Struct to a List of Lists at the Data Model layer. Similar to the <code>tuple</code> representation but the keys are also included in the encoding so the serialized form is not as opaque and more self-describing than <code>tuple</code>. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Foo struct { fieldOne String fieldTwo Bool } representation listpairs</code></pre> Some data matching the <code>Foo</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">[["fieldOne", "this is field one"], ["fieldTwo", true]]</code></pre> Each entry of the parent List is a List containing exactly two entries, where the first is the exact field name and the second is the value. No field-specific parameters are available for the <code>listpairs</code> Struct representation strategy (i.e. <code>implicit</code> and <code>rename</code> which are available for <code>map</code>). <h3 id="map-map-representation" tabindex="-1"><a class="header-anchor" href="#map-map-representation">Map <code>map</code> Representation</a></h3> Representation Kind: Map Schema Maps are represented as Data Model Maps by default. Schema Maps differ from Data Model Maps in that their value types are constrained. Example <pre class="language-ipldsch"><code class="language-ipldsch">type FloatMap {String:Float}</code></pre> Some data matching the <code>FloatMap</code> Map (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "x": 0.812411, "y": 0.15, "z": 0.0 }</code></pre> No parameters are available for the <code>map</code> Map representation strategy. <h3 id="map-stringpairs-representation" tabindex="-1"><a class="header-anchor" href="#map-stringpairs-representation">Map <code>stringpairs</code> Representation</a></h3> Representation Kind: String The <code>stringpairs</code> Map representation strategy is roughly the same the <code>stringpairs</code> for Structs. It encodes a Map to a single String. It should be used with special caution as there are no escaping mechanisms in place to prevent incompatible data from disrupting the encoding and causing errors during decode operations. The encoding presents key / value pairs as a delimited String. e.g. <code>"k1=v1,k2=v2"</code> rather than <code>{ "k1": "v1", "k2": "v2" }</code> if the same data used a <code>map</code> Map representation strategy. The entry delimiter and the key / value (inner) delimiter must be specified as general parameters when <code>stringpairs</code> is used, there is no default for these. In our example, the <code>entryDelim</code> would be <code>","</code> while the <code>innerDelim</code> would be <code>"="</code>. This serial representation is strictly limited: the domain of available for keys must exclude the <code>innerDelim</code> in any position and values and keys must exclude the <code>entryDelim</code> in any position. There is no facility for escaping, such as in escaped CSV. This also leads to a further restriction that this representation is only valid for Maps whose values may all be encoded to String kind in the Data Model layer. It is recommended, therefore, that its use be limited to Maps containing values with the basic data model kinds that exclude multiple values, i.e. no Maps, Lists, and therefore Structs or Unions or any other type that has a recursive representation kind. Example A string that is similar in format to the options found in an /etc/fstab file might be defined as: <pre class="language-ipldsch"><code class="language-ipldsch">type MountOptions {String:String} representation stringpairs { innerDelim "=" entryDelim "," }</code></pre> Some data matching the <code>MountOptions</code> Struct (shown as JSON) is: <pre class="language-json"><code class="language-json">"keys=values,serialized=thusly"</code></pre> The two general parameters for the <code>stringpairs</code> Map representation strategy are mandatory: <ul> <li><code>innerDelim</code> declares a quoted string that is used to delimit a key from a value</li> <li><code>entryDelim</code> declares a quoted string that is used to delimit entries from each other</li> </ul> <h3 id="map-listpairs-representation" tabindex="-1"><a class="header-anchor" href="#map-listpairs-representation">Map <code>listpairs</code> Representation</a></h3> Representation Kind: List The <code>listpairs</code> Map representation strategy is roughly the same the <code>listpairs</code> for Structs. It encodes a Map to a List of Lists at the Data Model layer. Example <pre class="language-ipldsch"><code class="language-ipldsch">type FloatMap {String:Float} representation listpairs</code></pre> Some data matching the <code>FloatMap</code> Map (shown as JSON) is: <pre class="language-json"><code class="language-json">[["x", 0.812411], ["y", 0.15], ["z", 0.0]]</code></pre> Each entry of the parent List is a List containing exactly two entries, where the first is the key String and the second is the value. No parameters are available for the <code>listpairs</code> Map representation strategy. <h3 id="union-keyed-representation" tabindex="-1"><a class="header-anchor" href="#union-keyed-representation">Union <code>keyed</code> Representation</a></h3> Representation Kind: Map (single entry of current node) A Union using a <code>keyed</code> representation strategy determines which of the types in the Union is present by looking at the keys in the Map at the current node. Exactly one of the keys listed in the Union must be present at any such Union node for it to be valid. When using a <code>keyed</code> Union representation strategy, the Union lists the quoted keys after each constituent type. These keys must be unique strings. Example <pre class="language-ipldsch"><code class="language-ipldsch">type MyKeyedUnion union { | Foo "foo" | Bar "bar" } representation keyed type Foo struct { froz Bool } type Bar int</code></pre> Some data matching <code>MyKeyedUnion</code>, finding <code>Foo</code> present, (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "foo": { "froz": true } }</code></pre> This data would also match, as <code>Bar</code>: <pre class="language-json"><code class="language-json">{ "bar": 12 }</code></pre> No parameters are available for the <code>keyed</code> Union representation strategy. <h3 id="union-kinded-representation" tabindex="-1"><a class="header-anchor" href="#union-kinded-representation">Union <code>kinded</code> Representation</a></h3> Representation Kind: Various <code>kinded</code> Unions discriminate between constituent types of the Union by inspecting the representation kind present at the current node. Each type in the union must be associated with a unique representation kind and exactly one of these representation kinds must be present at the node for it to be a valid Union of the type in question. The <code>kinded</code> Union representation strategy doesn't introduce any kind of wrapping Map in the serialized form at all. Maps are only present if <code>map</code> is one of the kinds listed in the Union. Contrast this with other union representation strategies, all of which use at least one layer of Map in their representation (other than <code>bytesprefix</code> Unions which are a special case). Example <pre class="language-ipldsch"><code class="language-ipldsch">type MyKindedUnion union { | Foo map | Bar int } representation kinded type Foo struct { froz Bool } type Bar int</code></pre> Some data matching <code>MyKindedUnion</code>, finding <code>Foo</code> present, (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "froz": true }</code></pre> This data would also match, as <code>Bar</code>: <pre class="language-json"><code class="language-json">12</code></pre> The syntax used in the type declaration is different for <code>kinded</code> Unions in comparison to other Union representation strategies. <code>kinded</code> Unions list a representation kind, unquoted, unlike other representation strategies which list a quoted key or discriminator (other than <code>bytesprefix</code> Unions, a special case). The kind listed after each element of the Union must be a valid representation kind, that is, a kind at the Data Model layer, such as <code>string</code> and <code>map</code>. Schema kinds are not valid as they don't denote representation kinds (i.e. <code>struct</code> would not be a valid kind for a <code>kinded</code> Union). It is only possible to discriminate distinct representation kinds in a <code>kinded</code> Union, there may be at most one of each possible representation kind present in such a Union. Note that a type that has a different Schema kind to its representation kind uses the latter: <pre class="language-ipldsch"><code class="language-ipldsch">type MyKindedUnion union { | Foo map | Bar int | Bang string } representation kinded type Foo struct { froz Bool } type Bar int type Bang {String:Int} representation stringpairs { innerDelim ":" entryDelim "|" }</code></pre> In this instance, even though <code>Bang</code> presents as a user-facing Schema Map kind, it encodes to a String representation kind and is therefore listed as a <code>string</code> in the <code>kinded</code> Union. No parameters are available for the <code>kinded</code> Union representation strategy. <h3 id="union-envelope-representation" tabindex="-1"><a class="header-anchor" href="#union-envelope-representation">Union <code>envelope</code> Representation</a></h3> Representation Kind: Map (two entries of current node) An <code>envelope</code> Union representation strategy discriminates between constituent types of the Union by inspecting the value of a pre-determined discriminator key (<code>discriminantKey</code>) in a Map, while the content of the type is decoded from the value of a predetermined content key (<code>contentKey</code>). <code>envelope</code> Unions are only valid for nodes that are Maps in the Data Model layer, it requires the ability to look up two distinct keys. Each constituent type of an <code>envelope</code> Union is accompanied by a quoted string that is unique amongst the types that is used to match against the value of <code>discriminantKey</code> in the current node. Example <pre class="language-ipldsch"><code class="language-ipldsch">type MyEnvelopeUnion union { | Foo "foo" | Bar "bar" } representation envelope { discriminantKey "tag" contentKey "msg" } type Foo struct { froz Bool } type Bar int</code></pre> Some data matching <code>MyEnvelopeUnion</code>, finding <code>Foo</code> present, (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "tag": "foo", "msg": { "froz": true } }</code></pre> This data would also match, as <code>Bar</code>: <pre class="language-json"><code class="language-json">{ "tag": "bar", "msg": 12 }</code></pre> The <code>envelope</code> Union representation strategy is an "envelope" in the sense that the type is addressed within a value of the current node and the type itself is wrapped in another value of the current node, the current node being the envelope that exists only to contain and discriminate the type. <code>envelope</code> Unions are more self-describing and explicit than <code>inline</code> or <code>kinded</code> unions but are roughly comparable to <code>keyed</code> unions in that sense. Two general parameters are mandatory for the <code>envelope</code> Union representation strategy: <ul> <li><code>discriminantKey</code> defines a quoted string that is used to look up a string in the Map at the current node to match against the keys provided with each of the constituent types of the Union.</li> <li><code>contentKey</code> defines a quoted string that is used to look up a node that may decode to the type that the discriminator determines is the type of the Union.</li> </ul> <h3 id="union-inline-representation" tabindex="-1"><a class="header-anchor" href="#union-inline-representation">Union <code>inline</code> Representation</a></h3> Representation Kind: Map (only some entries of current node) The <code>inline</code> Union representation strategy decodes a Map node from the Data Model layer into one of the constituent types of the union by discriminating based on the value of a pre-determined key of that Map (<code>discriminantKey</code>). This strategy is similar to the <code>envelope</code> Union representation strategy but it does not traverse into a child node to decode the type, instead it decodes that type from the current node. Therefore, constituent type of an <code>inline</code> Union must have a Map representation kind (i.e. a Struct or a Map with default representation strategies). Each constituent type of an <code>inline</code> Union is accompanied by a quoted string that is unique amongst the types that is used to match against the value of <code>discriminantKey</code> in the current node. Example <pre class="language-ipldsch"><code class="language-ipldsch">type MyInlineUnion union { | Foo "foo" | Bar "bar" } representation inline { discriminantKey "tag" } type Foo struct { froz Bool } # Note that Bar is not an int as in our previous examples since this is not # possible with an inline Union type Bar struct { bral String }</code></pre> Some data matching <code>MyInlineUnion</code>, finding <code>Foo</code> present, (shown as JSON) is: <pre class="language-json"><code class="language-json">{ "tag": "foo", "froz": true }</code></pre> This data would also match, as <code>Bar</code>: <pre class="language-json"><code class="language-json">{ "tag": "bar", "bral": "zot" }</code></pre> Using a type that has a representation kind other than a Map with an <code>inline</code> Union would result in an error. One general parameter is mandatory for the <code>inline</code> Union representation strategy: <ul> <li><code>discriminantKey</code> defines a quoted string that is used to look up a string in the Map at the current node to match against the keys provided with each of the constituent types of the Union.</li> </ul> <h3 id="union-stringprefix-representation" tabindex="-1"><a class="header-anchor" href="#union-stringprefix-representation">Union <code>stringprefix</code> Representation</a></h3> Representation Kind: String The <code>stringprefix</code> Union representation strategy is used strictly for String representation kinds. The <code>bytesprefix</code> Union representation strategy can only be used as a Union between types that can be represented as strings (e.g. plain Strings, structs with <code>stringjoin</code> representations, maps as <code>stringpairs</code>, etc.). <pre class="language-ipldsch"><code class="language-ipldsch">type Username string type Credentials struct { credType String credToken String } representation stringjoin { join ":" } type Authorization union { | Username "user:" | Credentials "auth:" } representation stringprefix</code></pre> At the Data Model layer, strings at the <code>Authorization</code> node are prefixed with either <code>user:</code> or <code>auth:</code> and are decomposed into their matching types when represented at the Schema layer. In this case, the <code>Credentials</code> struct is further decomposed into a two-field struct by splitting the remainder of the string starting with <code>auth:</code> by the <code>:</code> characters. No parameters are available for the <code>stringprefix</code> Union representation strategy. <h3 id="union-bytesprefix-representation" tabindex="-1"><a class="header-anchor" href="#union-bytesprefix-representation">Union <code>bytesprefix</code> Representation</a></h3> Representation Kind: Bytes The <code>bytesprefix</code> Union representation strategy is used strictly for Bytes representation kinds. As there are currently no representation strategies other than the default for Bytes that encode as Bytes at the Data Model layer, the <code>bytesprefix</code> Union representation strategy can only be used as a Union between named Bytes types. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Signature union { | Secp256k1Signature "00" | Bls12_381Signature "01" } representation bytesprefix type Secp256k1Signature bytes type Bls12_381Signature bytes</code></pre> At the Data Model layer, this presents as Bytes (a byte array), where the first bytes are the discriminator (<code>0x00</code> or <code>0x01</code>) and the remainder is sliced to form either of the two types depending on the discriminator. No parameters are available for the <code>bytesprefix</code> Union representation strategy. <h3 id="enum-string-representation" tabindex="-1"><a class="header-anchor" href="#enum-string-representation">Enum <code>string</code> Representation</a></h3> Representation Kind: String By default, a Schema Enum is simply represented as a String in the data model. An Enum in a Schema simply defines the list of possible strings that could be used at that node. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Status enum { | Nope | Yep | Maybe }</code></pre> This Enum dictates that where <code>Status</code> is used, we should find one of <code>"Nope"</code>, <code>"Yep"</code> or <code>"Maybe"</code>. No other value is valid where <code>Status</code> is used. Where the serialized Strings are different to the values used for the Enum, they may be provided in parens as field-specific representation parameters: Example <pre class="language-ipldsch"><code class="language-ipldsch">type Status enum { | Nope ("Nay") | Yep ("Yay") | Maybe }</code></pre> In this example, the serialization expects, and uses, the strings <code>Nay</code>, <code>Yay</code> and <code>Maybe</code>. No general parameters are available for the <code>string</code> Enum representation strategy. <h3 id="enum-int-representation" tabindex="-1"><a class="header-anchor" href="#enum-int-representation">Enum <code>int</code> Representation</a></h3> Representation Kind: Int An alternative representation strategy for enums is <code>int</code>, which is closer to what users may expect from Enums in some programming languages that map enum values to integers. In IPLD Schemas we explicitly define the mapping to integers, so the user can dictate the appropriate data model values. Example <pre class="language-ipldsch"><code class="language-ipldsch">type Status enum { | Nope ("0") | Yep ("1") | Maybe ("100") } representation int</code></pre> As with the <code>string</code> representation strategy, Enums with an <code>int</code> representation strategy still quote the integer strings when provided as field-specific representation parameters. This is standard practice for field-specific representation parameters as they are converted to the correct type depending on context. In this context, they are assumed to be integers so must be convertible to integers. There are no optional values, as in the <code>string</code> representation strategy, all values must be provided when using <code>int</code> representation strategy. In our example, serialization expects, and uses, data model integer values <code>0</code>, <code>1</code>, and <code>100</code>. No other values at this position are valid. No general parameters are available for the <code>int</code> Enum representation strategy. </div> </main> </body> </html>