Something went wrong. Try again.
DASL — Data-Addressed Structures & Links — is a small set of simple, standard primitives for working with content-addressed, linked data. If forked from dasl.ing/dasl.ing
Something went wrong. Try again.
dasl.ing drisl.src.html
6.2 kB · 121 lines
HTML
at governance
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122<!doctype html><html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>DRISL — Deterministic Representation for Interoperable Structures & Links</title> </head> <body> <div id="abstract"> <p> DRISL is a serialization format that is deterministic (so that the same data will have the same CID) and that features native support for using CIDs as links. It is based on CBOR, using a narrow profile of CBOR's "Core" featureset called "[[cborc-42]]", specified formally in <a href="https://datatracker.ietf.org/doc/draft-caballero-cbor-cborc42/">this IETF document</a>. </p> </div> <section> <h2>Introduction</h2> <p> Deterministic encodings that produce the same stream of bytes for any given data with the same semantics are particularly useful in a content-addressed context. DRISL provides that, compactly encoded as CBOR. Additionally, it supports CBOR's Tag 42 to compactly encode CIDs ([[cid]]) as bytestreams. This CID can be used for content-addressed linking between DRISL documents (such as MASL documents), or to resources (best wrapped in MASL documents where renderability as web documents or web apps is desired). </p> <p> DRISL does not fork CBOR, CDE, or dCBOR ([[cbor]], [[cde]], [[dcbor]]), but it is a subset of features defined in CBOR "Core" ([[cborc]]), first defined in the earliest CBOR RFC and largely unaffected by refinements made since. Any decoder for any version of CBOR since v1 will be able to read DRISL content as conformant CBOR, and with enough carefully configuration of a powerful CBOR library and in some case pre-processing of the data, DRISL can be encoded anywhere CBOR can. </p> </section> <section> <h2>Format</h2> <p> DRISL is an application profile of CBOR ([[cbor]]) that mostly subsets the more established [[cborc]] profile, with the following additional constraints: </p> <ul> <li> Implementations must support Tag 42 in the <a href="https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml">CBOR Tag registry</a>; this tag compactly encodes CIDs as bytestrings, as specified below. </li> <li> Implementations must reject all other tags, including any of the tags listed in the <a href="https://tools.ietf.org/html/rfc8949#section-3.4">section 3.4 of RFC 8949</a>. </li> <li> Implementations must reject map keys that are not strings. </li> <li> Floating-point numbers must always be encoded as a 64-bit IEEE 754 binary floating-point, never as a "half-precision" (16-byte, major 7-25) or "single-precision (32-byte, major 7-26)" CBOR key. <strong>NOTE</strong>: It is recommended that users avoid encoding floating-point numbers as much as possible to minimize interoperability and tooling issues. <ul> <li> Completely avoiding floating-point numbers is recommended to minimize interoperability and tooling issues. </li> <li> Even where floating-point numbers are used, most of the IEEE 754 "special" floating points (infinity, negative infinity, minimal NaN, NaN with payloads, and negative zero) must not be encoded. </li> </ul> </li> <li> Indefinite-length arrays (and the "break" code making them usable, in major type 7) are not allowed. </li> <li> Similarly, indefinite, incomplete, or streaming CBOR cannot be hashed and thus cannot be referenced by CID; for this reason, DRISL can only encode finite, bounded documents and resources. </li> <li> Concatenation of DRISL objects is generally discouraged and incurs both performance and interoperability risks. <ul> <li> Note that DRISL objects cannot be streamed as CBOR streams (defined in RFC 8742) except in MIME-type aware contexts, as per the CBOR streams specification. </li> <li> Applications are discouraged from handling concatenated DRISL objects or appending extra bytes of any kind to a DRISL object in memory or across interfaces, as doing so breaks the DRISL-wide assumption that each CID refers to one complete, discrete, and valid CBOR object, and that DRISL systems only ever will be expected to handle such objects. </li> </ul> </li> <li> Encoders must not encode any simple values other than <code>true</code>, <code>false</code>, and <code>null</code> (20, 21, and 22 in section 3.3 of [[rfc8949]]). </li> </ul> <p> All other requirements are as CBOR/c ([[cborc]]). </p> </section> <section> <h2>CIDs in CBOR</h2> <p> CIDs in CBOR are stored in binary format, as CBOR bytestrings under custom tag 42. For historical reasons the null byte <code>0x00</code> is prepended to the binary CID before storing in CBOR. </p> <p> For more information, see the [[cbor-tag42]] appendix to the [[drisl]] specification. </p> </section> <section> <h2>Conversion with JSON</h2> <p> JSON lacks a native way to encode tag 42 for CIDs ([[cbor-tag42]], [[cid]]). Historically, there have been different conventions to represent CIDs in JSON. For example, DAG-JSON, part of IPLD, used an object with a single <code>/</code> key pointing to the stringified CID. </p> <p> The AT Protocol uses an object with a <code>$link</code> key pointing to the stringified DASL CID: </p> <pre>{ "someSrc": { "$link": "bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4" }} </pre> <p> This specification recommends that implementations default to the AT Protocol <code>$link</code> convention, but may offer the option to support DAG-JSON or other conventions as well. </p> </section> </body></html>