Update schema.md

documents/resources/schema.md

@@ -1,7 +1,8 @@
 # Schema
 
 ## [Claim](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/claim.proto)
-Claims have the encompassing schema:
+
+A `Claim` is the toplevel schema for everything that is published to the LBRY blockchain.
 
 ```protobuf
 message Claim {
@@ -10,12 +11,14 @@ message Claim {
         _0_0_1 = 1;
     }
     required Version version = 1;
+
     enum ClaimType {
         UNKNOWN_CLAIM_TYPE = 0;
         streamType = 1;
         certificateType = 2;
     }
     required ClaimType claimType = 2;
+    
     optional Stream stream = 3;
     optional Certificate certificate = 4;
     optional Signature publisherSignature = 5;
@@ -25,7 +28,8 @@ message Claim {
 
 
 ## [Stream](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/stream.proto)
-Claims of streamType have a `stream`:
+
+All content claims have a Stream field, which includes the content-specific information (e.g. a description of the content, instructions for downloading the content, etc).
 
 ```protobuf
 message Stream {
@@ -34,13 +38,15 @@ message Stream {
         _0_0_1 = 1;
     }
     required Version version = 1;
+    
     required Metadata metadata = 2;
     required Source source = 3;
 }
 ```
 
 ## [Metadata](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/metadata.proto)
-Streams have `metadata` describing their content:
+
+`Metadata` provides information about a piece of content, such as the title, description, and price.
 
 ```protobuf
 message Metadata {
@@ -51,12 +57,14 @@ message Metadata {
         _0_0_3 = 3;
         _0_1_0 = 4;
     }
+    required Version version = 1;
+
     enum Language {
         UNKNOWN_LANGUAGE = 0;
         en = 1;
     }
-    required Version version = 1;
     required Language language = 2;
+    
     required string title = 3;
     required string description = 4;
     required string author = 5;
@@ -64,6 +72,7 @@ message Metadata {
     required bool nsfw = 7;
 
     optional Fee fee = 8;
+    
     optional string thumbnail = 9;
     optional string preview = 10;
     optional string licenseUrl = 11;
@@ -71,7 +80,8 @@ message Metadata {
 ```
 
 ## [Fee](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/fee.proto)
-Metadata may include a fee to access the decryption key:
+
+A `Fee` defines the prices for accessing a piece of content.
 
 ```protobuf
 message Fee {
@@ -79,21 +89,24 @@ message Fee {
         UNKNOWN_VERSION = 0;
         _0_0_1 = 1;
     }
+    required Version version = 1;
+
     enum Currency {
         UNKNOWN_CURRENCY = 0;
         LBC = 1;
         BTC = 2;
         USD = 3;
     }
-    required Version version = 1;
     required Currency currency = 2;
+
     required bytes address = 3;
     required float amount = 4;
 }
 ```
 
 ## [Source](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/source.proto)
-Streams have a `source` to download:
+
+A `Source` contains information on how to download a stream. Only the LBRY data network is supported at the moment, but other sources may be added in the future.
 
 ```protobuf
 message Source {
@@ -102,19 +115,34 @@ message Source {
         _0_0_1 = 1;
     }
     required Version version = 1;
+
     enum SourceTypes {
         UNKNOWN_SOURCE_TYPE = 0;
         lbry_sd_hash = 1;
     }
     required SourceTypes sourceType = 2;
+
     required bytes source = 3;
     required string contentType = 4;
 }
 ```
 
+## Channels
 
-## [Certificate](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/certificate.proto)
+Channels are constructed out of Certificates and Signatures. Both utilize a KeyType:
-Claims of certificateType have a `certificate`:
+
+```protobuf
+enum KeyType {
+    UNKNOWN_PUBLIC_KEY_TYPE = 0;
+    NIST256p = 1;
+    NIST384p = 2;
+    SECP256k1 = 3;
+}
+```
+
+### [Certificate](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/certificate.proto)
+
+Creating a channel involves making a `certificateType` claim. This claim contains the public key for a channel. It must include a Certificate field:
 
 ```protobuf
 message Certificate {
@@ -123,13 +151,16 @@ message Certificate {
         _0_0_1 = 1;
     }
     required Version version = 1;
+    
     required KeyType keyType = 2;
     required bytes publicKey = 4;
 }
 ```
 
-## [Signature](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/signature.proto)
+
-Claims may be signed using the private key to a Certificate public key:
+### [Signature](https://github.com/lbryio/lbryschema/blob/master/lbryschema/proto/signature.proto)
+
+Publishing a claim to a channels simply means that the claim is signed using the private key for a channel. This is done by including a Signature field in a Claim:
 
 ```protobuf
 message Signature {
@@ -138,6 +169,7 @@ message Signature {
         _0_0_1 = 1;
     }
     required Version version = 1;
+    
     required KeyType signatureType = 2;
     required bytes signature = 3;
     required bytes certificateId = 4;