started on our in-progress (re)design documents

8 files changed, 187 insertions, 0 deletions

diff --git a/doc/schema/consistency_proof.schema.json b/doc/schema/consistency_proof.schema.json
new file mode 100644
index 0000000..003f3c7
--- /dev/null
+++ b/doc/schema/consistency_proof.schema.json
@@ -0,0 +1,30 @@
+{
+	"$schema": "https://json-schema.org/draft-07/schema#",
+	"title": "inclusion_proof",
+	"description": "JSON-formatted inclusion proof, version 0.",
+
+	"type": "object",
+	"required": [ "new_size", "old_size", "consistency_proof" ],
+	"properties": {
+		"new_size": {
+			"description": "The tree size of the newer Merkle tree head.",
+			"type": "integer",
+			"minimum": 0
+		},
+		"old_size": {
+			"description": "The tree size of the older Merkle tree head.",
+			"type": "integer",
+			"minimum": 0
+		},
+		"consistency_proof": {
+			"description": "A list of base64-encoded node hashes that proves consistency",
+			"type": "array",
+			"items": {
+				"description": "A node hash in base64",
+				"type": "string",
+				"minLength": 44,
+				"maxLength": 44
+			}
+		}
+	}
+}
diff --git a/doc/schema/example/consistency_proof.json b/doc/schema/example/consistency_proof.json
new file mode 100644
index 0000000..0a323b7
--- /dev/null
+++ b/doc/schema/example/consistency_proof.json
@@ -0,0 +1,7 @@
+{
+	"new_size": 2,
+	"old_size": 1,
+	"consistency_proof": [
+		"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+	]
+}
diff --git a/doc/schema/example/inclusion_proof.json b/doc/schema/example/inclusion_proof.json
new file mode 100644
index 0000000..d46d426
--- /dev/null
+++ b/doc/schema/example/inclusion_proof.json
@@ -0,0 +1,7 @@
+{
+	"tree_size": 2,
+	"leaf_index": 0,
+	"inclusion_proof": [
+		"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+	]
+}
diff --git a/doc/schema/example/leaves.json b/doc/schema/example/leaves.json
new file mode 100644
index 0000000..1eed05d
--- /dev/null
+++ b/doc/schema/example/leaves.json
@@ -0,0 +1,14 @@
+[
+	{
+		"checksum": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+		"signature_scheme": 1,
+		"signature": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",
+		"key_hash": "DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD="
+	},
+	{
+		"checksum": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+		"signature_scheme": 2,
+		"signature": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+		"key_hash": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC="
+	}
+]
diff --git a/doc/schema/example/sth.json b/doc/schema/example/sth.json
new file mode 100644
index 0000000..ec3ad11
--- /dev/null
+++ b/doc/schema/example/sth.json
@@ -0,0 +1,11 @@
+{
+    "timestamp": 0,
+    "tree_size": 0,
+    "root_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+    "signatures": [
+        {
+            "key_hash": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",
+            "signature": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC="
+        }
+    ]
+}
diff --git a/doc/schema/inclusion_proof.schema.json b/doc/schema/inclusion_proof.schema.json
new file mode 100644
index 0000000..3309d37
--- /dev/null
+++ b/doc/schema/inclusion_proof.schema.json
@@ -0,0 +1,30 @@
+{
+	"$schema": "https://json-schema.org/draft-07/schema#",
+	"title": "inclusion_proof",
+	"description": "JSON-formatted inclusion proof, version 0.",
+
+	"type": "object",
+	"required": [ "tree_size", "leaf_index", "inclusion_proof" ],
+	"properties": {
+		"tree_size": {
+			"description": "The Merkle tree size that the inclusion proof is based on.",
+			"type": "integer",
+			"minimum": 0
+		},
+		"leaf_index": {
+			"description": "The zero-based index of the leaf that the inclusion proof is for.",
+			"type": "integer",
+			"minimum": 0
+		},
+		"inclusion_proof": {
+			"description": "A list of base64-encoded node hashes that proves inclusion",
+			"type": "array",
+			"items": {
+				"description": "A node hash in base64",
+				"type": "string",
+				"minLength": 44,
+				"maxLength": 44
+			}
+		}
+	}
+}
diff --git a/doc/schema/leaves.schema.json b/doc/schema/leaves.schema.json
new file mode 100644
index 0000000..74d7454
--- /dev/null
+++ b/doc/schema/leaves.schema.json
@@ -0,0 +1,38 @@
+{
+	"$schema": "https://json-schema.org/draft-07/schema#",
+	"title": "list of tree_leaf",
+	"description": "JSON-formatted tree leaf list, version 0.",
+
+	"type": "array",
+	"description": "A list Merkle tree leaves",
+	"items": {
+		"type": "object",
+		"required": [ "checksum", "signature_scheme", "signature", "key_hash" ],
+		"properties": {
+			"checksum": {
+				"description": "A cryptographic hash that is computed over some data of opaque type.  The result is base64-encoded.",
+				"type": "string",
+				"minLength": 44,
+				"maxLength": 44
+			},
+			"signature_scheme": {
+				"description": "An integer that identifies the signature scheme used by the submitter.  See API documentation.",
+				"type": "integer",
+				"enum": [ 1, 2, 3 ]
+			},
+			"signature": {
+				"description": "The submitter's signature over the checksum in base64",
+				"type": "string",
+				"minLength": 44,
+				"maxLength": 684
+			},
+			"key_hash": {
+				"description": "A public verification-key hash that identifies the signer.",
+				"type": "string",
+				"minLength": 44,
+				"maxLength": 44
+			}
+		}
+	},
+	"minItems": 1
+}
diff --git a/doc/schema/sth.schema.json b/doc/schema/sth.schema.json
new file mode 100644
index 0000000..86de2d3
--- /dev/null
+++ b/doc/schema/sth.schema.json
@@ -0,0 +1,50 @@
+{
+	"$schema": "https://json-schema.org/draft-07/schema#",
+	"title": "signed_tree_head_v0",
+	"description": "JSON-formatted signed tree head, version 0.",
+
+	"type": "object",
+	"required": [ "timestamp", "tree_size", "root_hash", "signatures" ],
+	"properties": {
+		"timestamp": {
+			"description": "The number of milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC).",
+			"type": "integer",
+			"minimum": 0
+		},
+		"tree_size": {
+			"description": "The number of entries that are stored in the log's Merkle tree.",
+			"type": "integer",
+			"minimum": 0
+		},
+		"root_hash": {
+			"description": "The log's Merkle tree root hash in base64.",
+			"type": "string",
+			"minLength": 44,
+			"maxLength": 44
+		},
+		"signatures": {
+			"description": "A list of signer-signature pairs.",
+			"type": "array",
+			"items": {
+				"description": "A signer-signature pair.",
+				"type": "object",
+				"required": [ "key_hash", "signature" ],
+				"properties": {
+					"key_hash": {
+						"description": "A public verification-key hash that identifies the signer in base64.",
+						"type": "string",
+						"minLength": 44,
+						"maxLength": 44
+					},
+					"signature": {
+						"description": "The signer's signature over the log's tree_leaf structure in base64.",
+						"type": "string",
+						"minLength": 44,
+						"maxLength": 44
+					}
+				}
+			},
+			"minItems": 1
+		}
+	}
+}