Major reorg and introduction of spec status & governance

CID.md → block-layer/CID.md

@@ -1,10 +1,34 @@
-# CIDv1
+# Specification: CIDs
 
-# Content IDs
+**Status: Descriptive - Final**
 
-This document will use the words Content IDs or CIDs.
+This document will use the words "Content IDs" or "CIDs" interchangeably.
 
-Prior base58 multihash links to protobuf data be called CID Version 0.
+Prior Base58 Multihash links to Protobuf data is referred to as CID Version 0.
+
+## Summary
+
+A CID is a hash-based content identifier. Includes the `codec` and `multihash`.
+
+```
++-------+------------------------------+
+| Codec | Multihash                    |
++-------+------------------------------+
+```
+
+The long version:
+
+```
++------------------------------+
+|Codec                         |
++------------------------------+
+|Multihash                     |
+| +----------+---------------+ |
+| |Hash Type | Hash Value    | |
+| +----------+---------------+ |
+|                              |
++------------------------------+
+```
 
 ## CIDs Version 1
 

block-layer/block.md

@@ -0,0 +1,27 @@
+# Concept: Block
+
+A IPLD Block is a CID and the binary data value for that CID.
+
+The short version:
+```
++-----+--------------------------------+
+| CID | Data                           |
++-----+--------------------------------+
+```
+
+The long version:
+```
++-----------------------------------+------------------+
+| CID                               | Binary Data      |
+| +------------------------------+  |                  |
+| |Codec                         |  |                  |
+| +------------------------------+  |                  |
+| |Multihash                     |  |                  |
+| | +----------+---------------+ |  |                  |
+| | |Hash Type | Hash Value    | |  |                  |
+| | +----------+---------------+ |  |                  |
+| |                              |  |                  |
+| +------------------------------+  |                  |
+|                                   |                  |
++-----------------------------------+------------------+
+```

Codecs/DAG-CBOR.md → block-layer/codecs/DAG-CBOR.md

@@ -1,8 +1,10 @@
-# [WIP] DagCBOR Spec
+# Specification: DAG-CBOR
 
-DAG-CBOR supports the full ["IPLD Data Model v1."](../IPLD-Data-Model-v1.md)
+**Status: Descriptive - Final**
 
-CBOR already natively supports all ["IPLD Data Model v1: Simple Types."](../IPLD-Data-Model-v1.md#simple-types)
+DAG-CBOR supports the full [IPLD Data Model](../data-model-layer/data-model.md).
+
+CBOR already natively supports all [IPLD Data Model Kinds](../data-model-layer/data-model.md#kinds).
 
 ## Format
 

Codecs/DAG-JSON.md → block-layer/codecs/DAG-JSON.md

@@ -1,6 +1,8 @@
-# [WIP] DAG-JSON v1
+# Specification: DAG-JSON
 
-DAG-JSON supports the full ["IPLD Data Model v1."](../IPLD-Data-Model-v1.md)
+**Status: Descriptive - Final**
+
+DAG-JSON supports the full [IPLD Data Model](../data-model-layer/data-model.md).
 
 ## Format
 

block-layer/codecs/README.md

@@ -0,0 +1,5 @@
+# IPLD Codecs
+
+A codec exposes serialization and deserialization for IPLD blocks.
+If it also supports content addressable links then the codec exposes those links as CIDs.
+A codec also supports atomic IPLD Path lookups on the block.

block-layer/content-addressability.md

@@ -0,0 +1,7 @@
+# Concept: Content Addressability
+
+"Content addressability" refers to the ability to refer to content by a trustless identifier.
+
+Rather than referring to content by a string identifier or URL, content addressable systems refer to content
+by a cryptographic hash. This allows complete decentralization of the content as the identifier
+does not specify the retrieval method and provides a secure way to verify the content.

graphsync/graphsync.md → block-layer/graphsync/graphsync.md

@@ -1,4 +1,6 @@
-# graphsync
+# Graphsync
+
+**Status: Prescriptive - Draft**
 
 A protocol to synchronize graphs across peers.
 

block-layer/multihash.md

@@ -0,0 +1,21 @@
+# Concept: Multihash
+
+Multihash is hash format that is not specific to a single hashing algorithm.
+
+A multihash describes the algorithm used for the hash as well as the hash value.
+
+```
++-----------+----------------------------+
+| Hash Type | Hash Value                 |
++-----------+----------------------------+
+```
+
+SHA-256 example.
+
+```
++---------+------------------------------------------------------------------+
+| SHA-256 | 2413fb3709b05939f04cf2e92f7d0897fc2596f9ad0b8a9ea855c7bfebaae892 |
++---------+------------------------------------------------------------------+
+```
+
+Note: these examples are simplifications of the concepts. For a complete description visit the [project and its specs](https://github.com/multiformats/multihash).

selectors/selectors.md → block-layer/selectors/selectors.md

@@ -1,4 +1,6 @@
-# IPLD Selectors
+# Specification: IPLD Selectors
+
+**Status: Prescriptive - Draft**
 
 This document is a designdoc for IPLD Selectors.
 

block-layer/serialization-and-formats.md

@@ -0,0 +1,27 @@
+# Concept: Serialization and Formats
+
+A logical separation exists in any given IPLD codec between the **format** and the **serializer/deserializer**.
+
+```
+┌────────────────────┐             ┌────────────────────┐
+│                    │             │                    │
+│     Serializer     │             │    Deserializer    │
+│                    │             │                    │
+└─────────┬──────────┘             └──────────^─────────┘
+          │                                   │
+          │         Sent to another peer      │
+          │                                   │
+┌─────────v──────────┐             ┌──────────┴─────────┐
+│                    │             │                    │
+│       Format       ├─────────────>       Format       │
+│                    │             │                    │
+└────────────────────┘             └────────────────────┘
+```
+
+A **format** may represent object types and tree structures any way it wishes.
+This includes existing representations (JSON, BSON, CBOR, Protobuf, msgpack, etc) or even new custom serializations.
+
+Therefor, a **format** is the standardized representation of IPLD Links and Paths.
+It describes how to translate between structured data and binary.
+
+It is worth noting that **serializers** and **deserializers** differ by programming language while the **format** does not and MUST remain consistent across all codec implementations.

IPLD-Data-Model-v1.md → data-model-layer/data-model.md

@@ -1,5 +1,6 @@
-IPLD Data Model
-===============
+# Specification: IPLD Data Model
+
+**Status: Descriptive - Draft**
 
 The IPLD Data Model is a core part of the IPLD specification,
 which describes what data is representable in IPLD --

IPLD-Path.md → data-model-layer/paths.md

@@ -1,13 +1,19 @@
-# [WIP] IPLD Path v1
+# Specification: IPLD Paths
 
-An IPLD Path is a string identifier used for deep references into IPLD
-graphs.
+**Status: Descriptive - Draft**
+
+## Summary
+
+An IPLD "Path" is a string identifier used for deep references into IPLD graphs.
+Paths follow similar escape and segmentation rules as URI paths.
+
+An IPLD Path is a string identifier used for deep references into IPLD graphs.
 
 IPLD Path's are constructed following the same constraints as [URI Paths](https://tools.ietf.org/html/rfc3986#section-3.3).
 
 Similarly, the string `?` is reserved for future use as a query separator.
 
-# Path Resolution
+## Path Resolution
 
 Path resolution is broken into two parts: full path resolution and block level resolution.
 

data-structures/multiblock-collections.md → schema-layer/data-structures/multiblock-collections.md

@@ -1,4 +1,4 @@
-# IPLD Multi-block Collections
+# Concept: IPLD Multi-block Collections
 
 Organizing IPLD data into usable, efficient, complex collections spanning many blocks aimed for use by end-user applications.
 

schema/representations.md → schema-layer/schemas/representations.md

@@ -1,4 +1,3 @@
-
 Kinds and their Representations
 -------------------------------
 

schema/schema-kinds.md → schema-layer/schemas/schema-kinds.md

@@ -1,5 +1,3 @@
-
-
 Schema Kinds
 ------------
 

schema-layer/schemas/schemas.md

@@ -0,0 +1,3 @@
+# Specification: IPLD Schemas
+
+**Status: Prescriptive - Exploratory**