diff --git a/bigchaindb/common/schema/vote.yaml b/bigchaindb/common/schema/vote.yaml
index 5bd02cda..8a09a10a 100644
--- a/bigchaindb/common/schema/vote.yaml
+++ b/bigchaindb/common/schema/vote.yaml
@@ -7,6 +7,10 @@ title: Vote Schema
description: |
A Vote is an endorsement of a Block (identified by a hash) by
a node (identified by a public key).
+
+ The outer Vote object contains the details of the vote being made
+ as well as the signature and identifying information of the node
+ passing the vote.
required:
- node_pubkey
- signature
@@ -34,16 +38,6 @@ properties:
- voting_for_block
- timestamp
properties:
- invalid_reason:
- anyOf:
- - type: "string"
- description: |
- Reason the block is voted invalid, or ``null``.
- - type: "null"
- is_block_valid:
- type: "boolean"
- description: |
- This field is ``true`` if the block was deemed valid by the node.
previous_block:
"$ref": "#/definitions/sha3_hexdigest"
description: |
@@ -53,6 +47,16 @@ properties:
"$ref": "#/definitions/sha3_hexdigest"
description: |
Sha3 identifier of the block being voted on.
+ is_block_valid:
+ type: "boolean"
+ description: |
+ This field is ``true`` if the block was deemed valid by the node.
+ invalid_reason:
+ anyOf:
+ - type: "string"
+ description: |
+ Reason the block is voted invalid, or ``null``.
+ - type: "null"
timestamp:
type: "string"
pattern: "[0-9]{10}"
diff --git a/docs/server/generate_schema_documentation.py b/docs/server/generate_schema_documentation.py
index e5562444..704157f3 100644
--- a/docs/server/generate_schema_documentation.py
+++ b/docs/server/generate_schema_documentation.py
@@ -5,7 +5,7 @@ import os.path
import yaml
-from bigchaindb.common.schema import TX_SCHEMA_PATH
+from bigchaindb.common.schema import TX_SCHEMA_PATH, VOTE_SCHEMA_PATH
TPL_PROP = """\
@@ -84,6 +84,23 @@ Metadata
""" + TPL_STYLES
+def generate_transaction_docs():
+ schema = load_schema(TX_SCHEMA_PATH)
+ defs = schema['definitions']
+
+ doc = TPL_TRANSACTION % {
+ 'transaction': render_section('Transaction', schema),
+ 'condition': render_section('Condition', defs['condition']),
+ 'fulfillment': render_section('Fulfillment', defs['fulfillment']),
+ 'asset': render_section('Asset', defs['asset']),
+ 'metadata': render_section('Metadata', defs['metadata']['anyOf'][0]),
+ 'container': 'transaction-schema',
+ 'file': os.path.basename(__file__),
+ }
+
+ write_schema_doc('transaction', doc)
+
+
TPL_VOTE = """\
.. This file was auto generated by %(file)s
@@ -91,9 +108,32 @@ TPL_VOTE = """\
Vote Schema
===========
+Vote
+----
+
+%(vote)s
+
+Vote Details
+------------
+
+%(vote_details)s
+
""" + TPL_STYLES
+def generate_vote_docs():
+ schema = load_schema(VOTE_SCHEMA_PATH)
+
+ doc = TPL_VOTE % {
+ 'vote': render_section('Vote', schema),
+ 'vote_details': render_section('Vote', schema['properties']['vote']),
+ 'container': 'vote-schema',
+ 'file': os.path.basename(__file__),
+ }
+
+ write_schema_doc('vote', doc)
+
+
def ordered_load_yaml(path):
""" Custom YAML loader to preserve key order """
class OrderedLoader(yaml.SafeLoader):
@@ -116,23 +156,6 @@ def load_schema(path):
return schema
-def generate_transaction_docs():
- schema = load_schema(TX_SCHEMA_PATH)
- defs = schema['definitions']
-
- doc = TPL_TRANSACTION % {
- 'transaction': render_section('Transaction', schema),
- 'condition': render_section('Condition', defs['condition']),
- 'fulfillment': render_section('Fulfillment', defs['fulfillment']),
- 'asset': render_section('Asset', defs['asset']),
- 'metadata': render_section('Metadata', defs['metadata']['anyOf'][0]),
- 'container': 'transaction-schema',
- 'file': os.path.basename(__file__),
- }
-
- write_schema_doc('transaction', doc)
-
-
def write_schema_doc(name, doc):
# Check base path exists
base_path = os.path.join(os.path.dirname(__file__), 'source/schema')
@@ -197,6 +220,7 @@ def resolve_ref(ref):
def main():
""" Main function """
generate_transaction_docs()
+ generate_vote_docs()
def setup(*_):
diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst
index 1c2b4428..932f1951 100644
--- a/docs/server/source/index.rst
+++ b/docs/server/source/index.rst
@@ -16,5 +16,6 @@ BigchainDB Server Documentation
topic-guides/index
data-models/index
schema/transaction
+ schema/vote
release-notes
appendices/index
diff --git a/docs/server/source/schema/vote.rst b/docs/server/source/schema/vote.rst
new file mode 100644
index 00000000..98bed941
--- /dev/null
+++ b/docs/server/source/schema/vote.rst
@@ -0,0 +1,118 @@
+.. This file was auto generated by generate_schema_documentation.py
+
+===========
+Vote Schema
+===========
+
+Vote
+----
+
+A Vote is an endorsement of a Block (identified by a hash) by
+a node (identified by a public key).
+
+The outer Vote object contains the details of the vote being made
+as well as the signature and identifying information of the node
+passing the vote.
+
+
+Vote.node_pubkey
+^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Ed25519 public key identifying the voting node.
+
+
+
+Vote.signature
+^^^^^^^^^^^^^^
+
+**type:** string
+
+Ed25519 signature of the ``vote`` object.
+
+
+Vote.vote
+^^^^^^^^^
+
+**type:** object
+
+Vote details to be signed.
+
+
+
+
+
+Vote Details
+------------
+
+Vote details to be signed.
+
+
+Vote.previous_block
+^^^^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Sha3 identifier of the block that preceeds the block being voted on.
+The notion of a "previous" block is subject to vote.
+
+
+
+Vote.voting_for_block
+^^^^^^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Sha3 identifier of the block being voted on.
+
+
+
+Vote.is_block_valid
+^^^^^^^^^^^^^^^^^^^
+
+**type:** boolean
+
+This field is ``true`` if the block was deemed valid by the node.
+
+
+
+Vote.invalid_reason
+^^^^^^^^^^^^^^^^^^^
+
+**type:** string or null
+
+Reason the block is voted invalid, or ``null``.
+
+
+
+Vote.timestamp
+^^^^^^^^^^^^^^
+
+**type:** string
+
+Unix timestamp that the vote was created by the node, according
+to the system time of the node.
+
+
+
+
+
+
+.. raw:: html
+
+ <style>
+ #vote-schema h2 {
+ border-top: solid 3px #6ab0de;
+ background-color: #e7f2fa;
+ padding: 5px;
+ }
+ #vote-schema h3 {
+ background: #f0f0f0;
+ border-left: solid 3px #ccc;
+ font-weight: bold;
+ padding: 6px;
+ font-size: 100%;
+ font-family: monospace;
+ }
+ </style>