Updated some docs about the asset model

docs/server/source/data-models/asset-model.md

@@ -1,21 +1,20 @@
-# The Digital Asset Model
+# The Asset Model
 
-To avoid redundant data in transactions, the digital asset model is different for `CREATE` and `TRANSFER` transactions.
+To avoid redundant data in transactions, the asset model is different for `CREATE` and `TRANSFER` transactions.
 
-A digital asset's properties are defined in a `CREATE` transaction with the following model:
+In a `CREATE` transaction, the `"asset"` must contain exactly one key-value pair. The key must be `"data"` and the value can be any valid JSON document, or `null`. For example:
 ```json
 {
-    "data": "<json document>"
+    "data": {
+                "desc": "Gold-inlay bookmark owned by Xavier Bellomat Dickens III",
+                "xbd_collection_id": 1857
+            }
 }
 ```
 
-For `TRANSFER` transactions we only keep the asset ID:
+In a `TRANSFER` transaction, the `"asset"` must contain exactly one key-value pair. They key must be `"id"` and the value must contain a transaction ID (i.e. a SHA3-256 hash: the ID of the `CREATE` transaction which created the asset, which also serves as the asset ID). For example:
 ```json
 {
-    "id": "<asset's CREATE transaction ID (sha3-256 hash)>"
+    "id": "38100137cea87fb9bd751e2372abb2c73e7d5bcf39d940a5516a324d9c7fb88d"
 }
 ```
-
-
-- `id`: The ID of the `CREATE` transaction that created the asset.
-- `data`: A user supplied JSON document with custom information about the asset. Defaults to null.

docs/server/source/data-models/index.rst

@@ -3,7 +3,7 @@ Data Models
 
 BigchainDB stores all data in the underlying database as JSON documents (conceptually, at least). There are three main kinds:
 
-1. Transactions, which contain digital assets, inputs, outputs, and other things
+1. Transactions, which contain assets, inputs, outputs, and other things
 2. Blocks
 3. Votes
 

docs/server/source/data-models/transaction-model.rst

@@ -25,14 +25,16 @@ A transaction has the following structure:
         "inputs": ["<list of inputs>"],
         "outputs": ["<list of outputs>"],
         "operation": "<string>",
-        "asset": "<digital asset description (explained in the next section)>",
+        "asset": "<asset model; see below>",
         "metadata": "<any JSON document>"
     }
 
 Here's some explanation of the contents of a :ref:`transaction <transaction>`:
 
-- id: The :ref:`id <transaction.id>` of the transaction, and also the database primary key.
-- version: :ref:`Version <transaction.version>` number of the transaction model, so that software can support different transaction models.
+- **id**: The :ref:`id <transaction.id>` of the transaction, and also the database primary key.
+
+- **version**: :ref:`Version <transaction.version>` number of the transaction model, so that software can support different transaction models.
+
 - **inputs**: List of inputs. Each :ref:`input <Input>` contains a pointer to an unspent output
   and a *crypto fulfillment* that satisfies the conditions of that output. A *fulfillment*
   is usually a signature proving the ownership of the asset.
@@ -43,7 +45,7 @@ Here's some explanation of the contents of a :ref:`transaction <transaction>`:
 
 - **operation**: String representation of the :ref:`operation <transaction.operation>` being performed (currently either "CREATE", "TRANSFER" or "GENESIS"). It determines how the transaction should be validated.
 
-- **asset**: Definition of the digital :ref:`asset <Asset>`. See next section.
+- **asset**: Definition of the :ref:`asset <Asset>`. See :ref:`the page about the asset model <The Asset Model>`.
 
 - **metadata**: User-provided transaction :ref:`metadata <metadata>`: Can be any JSON document, or `NULL`.