unfs

Conventions and Terminology

#2.1 Requirements language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.

#2.2 Notation

  • a || b — concatenation of byte strings.
  • 0x.. — hexadecimal bytes. Test vectors are lowercase hex.
  • "byte string" — an ordered sequence of octets.
  • All multi-byte integers inside CBOR heads are big-endian (per CBOR); varints (§3.1) are little-endian base-128.

#2.3 Integers

Every integer on the wire in this format — CBOR integers (§5) and varints (§3.1) alike — MUST have magnitude ≤ 2^53 − 1. (This bound is chosen so that every conforming value is exactly representable in an IEEE-754 double; implementations in languages with native 64-bit integers MUST still enforce it on the wire.) There are no exceptions; individual fields impose only tighter ranges. DAG-CBOR itself permits the 64-bit signed range; this profile's bound is stricter, and a conforming value is valid DAG-CBOR either way (§5).

#2.4 Definitions

  • Block — an immutable byte string stored under its hash.
  • Ref — a reference to a block, carried on the wire as a CIDv1 Link (§4): the CID's content codec is the ref's kind (raw or node) and its multihash digest is the block's hash.
  • CID — an IPLD Content IDentifier, version 1: a varint version, a varint content codec (multicodec), and a multihash (§2.5).
  • Multihash — a self-describing hash value: varint hash-function code, varint digest length, digest.
  • Multicodec — a varint code from the multiformats code table naming a content type. This format uses 0x55 (raw) and 0x71 (dag-cbor).
  • Multibase — a one-character prefix naming a base encoding of binary data. This format uses 0x00 (identity) in binary contexts and b (base32lower) in text contexts (§4).
  • Link — the DAG-CBOR encoding of a CID: tag 42 wrapping the byte string 0x00 || CID (§5).
  • Node — a block whose bytes are a canonical-CBOR map with a type tag (§6). Referenced with the dag-cbor codec (§4).
  • Raw block — a block of opaque bytes (a file chunk). Referenced with the raw codec (§4).
  • Entry — a CBOR map describing one directory member, including its metadata (§7).
  • Store — a key–value namespace holding blocks and named refs (§10).
  • Pack — a self-delimiting byte stream carrying a set of blocks plus a list of root refs: a CARv1 archive under the profile of §12.
  • Spine — for a given path, the chain of blocks from the root to the block containing the path's final entry: the root node, then each component's directory node (and page segment, when paged). An edit rewrites exactly the spine of the edited path; every block off the spine carries over by reference.
  • (binding) — a label on some rationale-styled paragraphs elsewhere in this document (e.g. §4 "Tag choice (binding)", §10.2). A paragraph so marked is normative despite reading as rationale.

#2.5 External specifications (normative)

Edit this page
Previous unfs: A Content-Addressed Filesystem Data Format Next Primitives

unfs  A filesystem you can put in any key–value store.