lexicons: update descriptions in com.atproto.*

bluesky-social · Jan 30, 2024 · 7c1ea3d · 7c1ea3d
1 parent c048962
commit 7c1ea3d
Show file tree

Hide file tree

Showing 34 changed files with 205 additions and 92 deletions.
diff --git a/lexicons/com/atproto/identity/resolveHandle.json b/lexicons/com/atproto/identity/resolveHandle.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Provides the DID of a repo.",
+      "description": "Resolves a handle (domain name) to a DID.",
       "parameters": {
         "type": "params",
         "required": ["handle"],

diff --git a/lexicons/com/atproto/identity/updateHandle.json b/lexicons/com/atproto/identity/updateHandle.json
@@ -4,14 +4,18 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Updates the handle of the account.",
+      "description": "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.",
       "input": {
         "encoding": "application/json",
         "schema": {
           "type": "object",
           "required": ["handle"],
           "properties": {
-            "handle": { "type": "string", "format": "handle" }
+            "handle": {
+              "type": "string",
+              "format": "handle",
+              "description": "The new handle."
+            }
           }
         }
       }

diff --git a/lexicons/com/atproto/label/queryLabels.json b/lexicons/com/atproto/label/queryLabels.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Find labels relevant to the provided URI patterns.",
+      "description": "Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.",
       "parameters": {
         "type": "params",
         "required": ["uriPatterns"],

diff --git a/lexicons/com/atproto/label/subscribeLabels.json b/lexicons/com/atproto/label/subscribeLabels.json
@@ -4,13 +4,13 @@
   "defs": {
     "main": {
       "type": "subscription",
-      "description": "Subscribe to label updates.",
+      "description": "Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.",
       "parameters": {
         "type": "params",
         "properties": {
           "cursor": {
             "type": "integer",
-            "description": "The last known event to backfill from."
+            "description": "The last known event seq number to backfill from."
           }
         }
       },

diff --git a/lexicons/com/atproto/moderation/createReport.json b/lexicons/com/atproto/moderation/createReport.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Report a repo or a record.",
+      "description": "Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.",
       "input": {
         "encoding": "application/json",
         "schema": {
@@ -13,9 +13,13 @@
           "properties": {
             "reasonType": {
               "type": "ref",
+              "description": "Indicates the broad category of violation the report is for.",
               "ref": "com.atproto.moderation.defs#reasonType"
             },
-            "reason": { "type": "string" },
+            "reason": {
+              "type": "string",
+              "description": "Additional context about the content and violation."
+            },
             "subject": {
               "type": "union",
               "refs": [

diff --git a/lexicons/com/atproto/repo/applyWrites.json b/lexicons/com/atproto/repo/applyWrites.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Apply a batch transaction of creates, updates, and deletes.",
+      "description": "Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.",
       "input": {
         "encoding": "application/json",
         "schema": {
@@ -14,12 +14,12 @@
             "repo": {
               "type": "string",
               "format": "at-identifier",
-              "description": "The handle or DID of the repo."
+              "description": "The handle or DID of the repo (aka, current account)."
             },
             "validate": {
               "type": "boolean",
               "default": true,
-              "description": "Flag for validating the records."
+              "description": "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations."
             },
             "writes": {
               "type": "array",
@@ -31,16 +31,22 @@
             },
             "swapCommit": {
               "type": "string",
+              "description": "If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.",
               "format": "cid"
             }
           }
         }
       },
-      "errors": [{ "name": "InvalidSwap" }]
+      "errors": [
+        {
+          "name": "InvalidSwap",
+          "description": "Indicates that the 'swapCommit' parameter did not match current commit."
+        }
+      ]
     },
     "create": {
       "type": "object",
-      "description": "Create a new record.",
+      "description": "Operation which creates a new record.",
       "required": ["collection", "value"],
       "properties": {
         "collection": { "type": "string", "format": "nsid" },
@@ -50,7 +56,7 @@
     },
     "update": {
       "type": "object",
-      "description": "Update an existing record.",
+      "description": "Operation which updates an existing record.",
       "required": ["collection", "rkey", "value"],
       "properties": {
         "collection": { "type": "string", "format": "nsid" },
@@ -60,7 +66,7 @@
     },
     "delete": {
       "type": "object",
-      "description": "Delete an existing record.",
+      "description": "Operation which deletes an existing record.",
       "required": ["collection", "rkey"],
       "properties": {
         "collection": { "type": "string", "format": "nsid" },

diff --git a/lexicons/com/atproto/repo/createRecord.json b/lexicons/com/atproto/repo/createRecord.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Create a new record.",
+      "description": "Create a single new repository record. Requires auth, implemented by PDS.",
       "input": {
         "encoding": "application/json",
         "schema": {
@@ -14,7 +14,7 @@
             "repo": {
               "type": "string",
               "format": "at-identifier",
-              "description": "The handle or DID of the repo."
+              "description": "The handle or DID of the repo (aka, current account)."
             },
             "collection": {
               "type": "string",
@@ -23,17 +23,17 @@
             },
             "rkey": {
               "type": "string",
-              "description": "The key of the record.",
+              "description": "The Record Key.",
               "maxLength": 15
             },
             "validate": {
               "type": "boolean",
               "default": true,
-              "description": "Flag for validating the record."
+              "description": "Can be set to 'false' to skip Lexicon schema validation of record data."
             },
             "record": {
               "type": "unknown",
-              "description": "The record to create."
+              "description": "The record itself. Must contain a $type field."
             },
             "swapCommit": {
               "type": "string",
@@ -54,7 +54,12 @@
           }
         }
       },
-      "errors": [{ "name": "InvalidSwap" }]
+      "errors": [
+        {
+          "name": "InvalidSwap",
+          "description": "Indicates that 'swapCommit' didn't match current repo commit."
+        }
+      ]
     }
   }
 }
diff --git a/lexicons/com/atproto/repo/deleteRecord.json b/lexicons/com/atproto/repo/deleteRecord.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Delete a record, or ensure it doesn't exist.",
+      "description": "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.",
       "input": {
         "encoding": "application/json",
         "schema": {
@@ -14,7 +14,7 @@
             "repo": {
               "type": "string",
               "format": "at-identifier",
-              "description": "The handle or DID of the repo."
+              "description": "The handle or DID of the repo (aka, current account)."
             },
             "collection": {
               "type": "string",
@@ -23,7 +23,7 @@
             },
             "rkey": {
               "type": "string",
-              "description": "The key of the record."
+              "description": "The Record Key."
             },
             "swapRecord": {
               "type": "string",

diff --git a/lexicons/com/atproto/repo/describeRepo.json b/lexicons/com/atproto/repo/describeRepo.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get information about the repo, including the list of collections.",
+      "description": "Get information about an account and repository, including the list of collections. Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["repo"],
@@ -30,12 +30,19 @@
           "properties": {
             "handle": { "type": "string", "format": "handle" },
             "did": { "type": "string", "format": "did" },
-            "didDoc": { "type": "unknown" },
+            "didDoc": {
+              "type": "unknown",
+              "description": "The complete DID document for this account."
+            },
             "collections": {
               "type": "array",
+              "description": "List of all the collections (NSIDs) for which this repo contains at least one record.",
               "items": { "type": "string", "format": "nsid" }
             },
-            "handleIsCorrect": { "type": "boolean" }
+            "handleIsCorrect": {
+              "type": "boolean",
+              "description": "Indicates if handle is currently valid (resolves bi-directionally)"
+            }
           }
         }
       }

diff --git a/lexicons/com/atproto/repo/getRecord.json b/lexicons/com/atproto/repo/getRecord.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a record.",
+      "description": "Get a single record from a repository. Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["repo", "collection", "rkey"],
@@ -19,7 +19,7 @@
             "format": "nsid",
             "description": "The NSID of the record collection."
           },
-          "rkey": { "type": "string", "description": "The key of the record." },
+          "rkey": { "type": "string", "description": "The Record Key." },
           "cid": {
             "type": "string",
             "format": "cid",

diff --git a/lexicons/com/atproto/repo/listRecords.json b/lexicons/com/atproto/repo/listRecords.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "List a range of records in a collection.",
+      "description": "List a range of records in a repository, matching a specific collection. Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["repo", "collection"],

diff --git a/lexicons/com/atproto/repo/putRecord.json b/lexicons/com/atproto/repo/putRecord.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Write a record, creating or updating it as needed.",
+      "description": "Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.",
       "input": {
         "encoding": "application/json",
         "schema": {
@@ -15,7 +15,7 @@
             "repo": {
               "type": "string",
               "format": "at-identifier",
-              "description": "The handle or DID of the repo."
+              "description": "The handle or DID of the repo (aka, current account)."
             },
             "collection": {
               "type": "string",
@@ -24,13 +24,13 @@
             },
             "rkey": {
               "type": "string",
-              "description": "The key of the record.",
+              "description": "The Record Key.",
               "maxLength": 15
             },
             "validate": {
               "type": "boolean",
               "default": true,
-              "description": "Flag for validating the record."
+              "description": "Can be set to 'false' to skip Lexicon schema validation of record data."
             },
             "record": {
               "type": "unknown",
@@ -39,7 +39,7 @@
             "swapRecord": {
               "type": "string",
               "format": "cid",
-              "description": "Compare and swap with the previous record by CID."
+              "description": "Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation"
             },
             "swapCommit": {
               "type": "string",

diff --git a/lexicons/com/atproto/repo/uploadBlob.json b/lexicons/com/atproto/repo/uploadBlob.json
@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "procedure",
-      "description": "Upload a new blob to be added to repo in a later request.",
+      "description": "Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.",
       "input": {
         "encoding": "*/*"
       },