Protocol records (#18)

* added info on authentication and updated info on creating DIDs * shortened subject * add more info on SSI Service * updates for web5 v0.8.1 * did documents * did documents * new query examples * added example of writing response record
TBD54566975 · Oct 12, 2023 · 30caeb3 · 30caeb3
1 parent 31bb1ed
commit 30caeb3
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 12 deletions.
diff --git a/content/protocol.txt b/content/protocol.txt
@@ -45,14 +45,29 @@ const { protocol, status } = await web5.dwn.protocols.configure({
 }
 
 
-// using a protocol looks like this: 
-
-    const { record, status } = await web5.dwn.records.write({
-      data: ding,
-      message: {
-        protocol: 'http://credential-issuance-protocol.xyz',
-        protocolPath: 'credentialApplication',
-        schema: '...',
-        recipient: did
-      }
-    });
+// using a protocol to write a record: 
+
+const { record: application, status } = await web5.dwn.records.write({
+  data: ding,
+  message: {
+    protocol: 'http://credential-issuance-protocol.xyz',
+    protocolPath: 'credentialApplication',
+    schema: 'https://identity.foundation/credential-manifest/schemas/credential-application',
+    recipient: did
+  }
+});
+
+// using a protocol to write a child record
+
+const { record: response, status } = await web5.dwn.records.write({
+  data: ding,
+  message: {
+    protocol: 'http://credential-issuance-protocol.xyz',
+    protocolPath: 'credentialApplication/credentialResponse',
+    schema: 'https://identity.foundation/credential-manifest/schemas/credential-response',
+    recipient: applicantDid,
+    dataFormat: 'application/json',
+    parentId: application.id,
+    contextId: application.contextId,
+  }
+});
diff --git a/content/query_filters.txt b/content/query_filters.txt
@@ -0,0 +1,42 @@
+Shows how to use filters to query DWN for specific records
+-----
+
+Here are the properties you can use to filter your record query, along with explanations and examples for each.
+
+| Property            | Value                                                |   Example   |
+| -----------         | ----------                                           | ----------- |  
+| **`recipient`**     | Recipient DID of message                             | "did:example:alice"  |
+| **`protocol`**      | The URI of the protocol bucket in which to query     | "example.com" |
+| **`protocolPath`**  | Records under a protocol path across all context IDs | "example" |
+| **`contextId`**     | `recordId` of a root record of a protocol            | "bafyreianzpmhbgcgam5mys722vnsiuwn..." |
+| **`schema`**        | The URI of the schema bucket in which to query       | "https<span>://</span>schema.org/Message" |
+| **`recordId`**      | Property contains the message recordId               | "aa36ec55-c59b-4f20-8143-10f74aac696d" |
+| **`parentId`**      | `recordId` of the parent record in a protocol        | "iadsfdreianzpmasdffcgam5mys722vnd..." |
+| **`dataFormat`**    | The IANA string for the data format to filter        | "application/json" |
+| **`dateCreated`**   | Date the record was created                          | "2023-04-30T22:49:37.713976Z" |
+
+Examples:
+
+Filter by parentId
+This snippet queries the DWN for records that have a parent record with a specific record ID:
+
+const response = await web5.dwn.records.query({
+    message: {
+      filter: {
+        parentId: 'bafyreianzpmhbgcgam5mys722vnsiuwn7y4ek6kjeyjptttquasw4hge2m',
+      },
+    },
+});
+
+
+Filter by protocol and protocolPath
+assuming playlist and video records have been created using this protocol, the following snippet demonstrates how to query for video records that match the protocol:
+
+const { records } = await web5.dwn.records.query({
+    message: {
+      filter: {
+        protocol: 'https://playlist.org/protocol',
+        protocolPath: 'playlist/video'
+      },
+    },
+});
diff --git a/content/query_full.txt → content/query_protocols.txt b/content/query_full.txt → content/query_protocols.txt
diff --git a/content/query.txt → content/query_records.txt b/content/query.txt → content/query_records.txt
@@ -17,4 +17,6 @@ const response = await web5.dwn.records.query({
 });
 
 // logs array of Record class instances
-console.log(response.entries) 
+console.log(response.entries) 
+
+Note that records.query() does not guarantee that the data is returned unless it is under a specific threshold (50 kb). To guarantee record data, call records.read().
diff --git a/content/query_sort.txt b/content/query_sort.txt
@@ -0,0 +1,31 @@
+Shows how to sort query results of DWN records and protocols
+-----
+
+Query results can be sorted via the dateSort field. Valid values for dateSort are:
+
+* createdAscending - sorts by dateCreated in ascending order
+* createdDescending - sorts by dateCreated in descending order
+* publshedAscending	- sorts by datePublished in ascending order
+* publishedDescending- sorts by datePublished in descending order
+
+
+//Ascending Order - queries for records with a plain text data format, and returns them in ascending order by the date they were published:
+const response = await web5.dwn.records.query({
+    message: {
+      filter: {
+        dataFormat: 'text/plain',
+      },
+      dateSort: 'publishedAscending',
+    },
+  });
+
+
+//Descending Order - queries for protocols with a certain URL, and returns them in descending order by the date they were created.
+const { protocols } = await web5.dwn.protocols.query({
+    message: {
+      filter: {
+        protocol: 'http://social-media.xyz',
+      },
+      dateSort: 'createdDescending'
+    },
+  });