From e884f5889dce2ac3b7cb411327683f8046ad583f Mon Sep 17 00:00:00 2001
From: Steven Allen <steven@stebalien.com>
Date: Tue, 30 Oct 2018 15:27:52 -0700
Subject: [PATCH] dag-cbor: add a draft spec

---
 formats/DagCBOR.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 formats/DagCBOR.md

diff --git a/formats/DagCBOR.md b/formats/DagCBOR.md
new file mode 100644
index 00000000..58417493
--- /dev/null
+++ b/formats/DagCBOR.md
@@ -0,0 +1,31 @@
+# DagCBOR Spec
+
+The CBOR IPLD format is called DagCBOR to disambiguate it from regular CBOR.
+Most CBOR objects are valid DagCBOR. The only hard restriction is that any field
+with the tag 42 must be a valid CID.
+
+## Link Format
+
+As with all IPLD formats, DagCBOR must be able to encode merkle-links. In
+DagCBOR, links are encoded using the raw-binary (identity, NUL) multibase in a
+field with a byte-string type (major type 2), with the tag 42.
+
+(the inclusion of the multibase exists for historical reasons)
+
+## Map Key Restriction
+
+In DagCBOR, map keys must be strings (TODO: drop this? We already have
+unpathable map keys). Furthermore, map keys should avoid using `/` as this is
+unpathable (TODO: drop this? IMO, we should support path escaping out of the
+box).
+
+## Canonical DagCBOR
+
+Canonical DagCBOR should:
+
+1. Use no tags other than the CID tag (42). Other tags may be lost in
+   conversion.
+2. Should use the canonical CBOR encoding and field ordering. Other orderings
+   will yield different CIDs.
+3. Should only use string map keys. Some implementations may not be able to
+   handle non-string keys.