update descriptions in Lexicons (#2110)

* lexicons: update descriptions in com.atproto.*

* lexicons: update descriptions in app.bsky.*

* Apply suggestions from code review

Thanks Emily!

Co-authored-by: Emily Liu <emilyliu7321@gmail.com>

* codegen description-only Lexicon updates

---------

Co-authored-by: Emily Liu <emilyliu7321@gmail.com>

lexicons/app/bsky/actor/defs.json

@@ -1,7 +1,6 @@
 {
   "lexicon": 1,
   "id": "app.bsky.actor.defs",
-  "description": "A reference to an actor in the network.",
   "defs": {
     "profileViewBasic": {
       "type": "object",
@@ -78,6 +77,7 @@
     },
     "viewerState": {
       "type": "object",
+      "description": "Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests.",
       "properties": {
         "muted": { "type": "boolean" },
         "mutedByList": {

lexicons/app/bsky/actor/getPreferences.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get private preferences attached to the account.",
+      "description": "Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.",
       "parameters": {
         "type": "params",
         "properties": {}

lexicons/app/bsky/actor/getProfile.json

@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get detailed profile view of an actor.",
+      "description": "Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],
         "properties": {
-          "actor": { "type": "string", "format": "at-identifier" }
+          "actor": {
+            "type": "string",
+            "format": "at-identifier",
+            "description": "Handle or DID of account to fetch profile of."
+          }
         }
       },
       "output": {

lexicons/app/bsky/actor/getSuggestions.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of suggested actors, used for discovery.",
+      "description": "Get a list of suggested actors. Expected use is discovery of accounts to follow during new account onboarding.",
       "parameters": {
         "type": "params",
         "properties": {

lexicons/app/bsky/actor/profile.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "record",
-      "description": "A declaration of a profile.",
+      "description": "A declaration of a Bluesky account profile.",
       "key": "literal:self",
       "record": {
         "type": "object",
@@ -16,21 +16,25 @@
           },
           "description": {
             "type": "string",
+            "description": "Free-form profile description text.",
             "maxGraphemes": 256,
             "maxLength": 2560
           },
           "avatar": {
             "type": "blob",
+            "description": "Small image to be displayed next to posts from account. AKA, 'profile picture'",
             "accept": ["image/png", "image/jpeg"],
             "maxSize": 1000000
           },
           "banner": {
             "type": "blob",
+            "description": "Larger horizontal image to display behind profile view.",
             "accept": ["image/png", "image/jpeg"],
             "maxSize": 1000000
           },
           "labels": {
             "type": "union",
+            "description": "Self-label values, specific to the Bluesky application, on the overall account.",
             "refs": ["com.atproto.label.defs#selfLabels"]
           }
         }

lexicons/app/bsky/actor/searchActors.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Find actors (profiles) matching search criteria.",
+      "description": "Find actors (profiles) matching search criteria. Does not require auth.",
       "parameters": {
         "type": "params",
         "properties": {

lexicons/app/bsky/actor/searchActorsTypeahead.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Find actor suggestions for a prefix search term.",
+      "description": "Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.",
       "parameters": {
         "type": "params",
         "properties": {

lexicons/app/bsky/embed/external.json

@@ -1,10 +1,10 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.external",
-  "description": "A representation of some externally linked content, embedded in another form of content.",
   "defs": {
     "main": {
       "type": "object",
+      "description": "A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post).",
       "required": ["external"],
       "properties": {
         "external": {

lexicons/app/bsky/embed/images.json

@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.images",
-  "description": "A set of images embedded in some other form of content.",
+  "description": "A set of images embedded in a Bluesky record (eg, a post).",
   "defs": {
     "main": {
       "type": "object",
@@ -23,7 +23,10 @@
           "accept": ["image/*"],
           "maxSize": 1000000
         },
-        "alt": { "type": "string" },
+        "alt": {
+          "type": "string",
+          "description": "Alt text description of the image, for accessibility."
+        },
         "aspectRatio": { "type": "ref", "ref": "#aspectRatio" }
       }
     },
@@ -51,9 +54,18 @@
       "type": "object",
       "required": ["thumb", "fullsize", "alt"],
       "properties": {
-        "thumb": { "type": "string" },
-        "fullsize": { "type": "string" },
-        "alt": { "type": "string" },
+        "thumb": {
+          "type": "string",
+          "description": "Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View."
+        },
+        "fullsize": {
+          "type": "string",
+          "description": "Fully-qualified URL where a large version of the image can be fetched. May or may not be the exact original blob. For example, CDN location provided by the App View."
+        },
+        "alt": {
+          "type": "string",
+          "description": "Alt text description of the image, for accessibility."
+        },
         "aspectRatio": { "type": "ref", "ref": "#aspectRatio" }
       }
     }

lexicons/app/bsky/embed/record.json

@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.record",
-  "description": "A representation of a record embedded in another form of content.",
+  "description": "A representation of a record embedded in a Bluesky record (eg, a post). For example, a quote-post, or sharing a feed generator record.",
   "defs": {
     "main": {
       "type": "object",
@@ -36,7 +36,10 @@
           "type": "ref",
           "ref": "app.bsky.actor.defs#profileViewBasic"
         },
-        "value": { "type": "unknown" },
+        "value": {
+          "type": "unknown",
+          "description": "The record data itself."
+        },
         "labels": {
           "type": "array",
           "items": { "type": "ref", "ref": "com.atproto.label.defs#label" }

lexicons/app/bsky/embed/recordWithMedia.json

@@ -1,7 +1,7 @@
 {
   "lexicon": 1,
   "id": "app.bsky.embed.recordWithMedia",
-  "description": "A representation of a record embedded in another form of content, alongside other compatible embeds.",
+  "description": "A representation of a record embedded in a Bluesky record (eg, a post), alongside other compatible embeds. For example, a quote post and image, or a quote post and external URL card.",
   "defs": {
     "main": {
       "type": "object",

lexicons/app/bsky/feed/defs.json

@@ -36,6 +36,7 @@
     },
     "viewerState": {
       "type": "object",
+      "description": "Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests.",
       "properties": {
         "repost": { "type": "string", "format": "at-uri" },
         "like": { "type": "string", "format": "at-uri" },

lexicons/app/bsky/feed/describeFeedGenerator.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get information about a feed generator, including policies and offered feed URIs.",
+      "description": "Get information about a feed generator, including policies and offered feed URIs. Does not require auth; implemented by Feed Generator services (not App View).",
       "output": {
         "encoding": "application/json",
         "schema": {

lexicons/app/bsky/feed/generator.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "record",
-      "description": "A declaration of the existence of a feed generator.",
+      "description": "Record declaring of the existence of a feed generator, and containing metadata about it. The record can exist in any repository.",
       "key": "any",
       "record": {
         "type": "object",
@@ -32,6 +32,7 @@
           },
           "labels": {
             "type": "union",
+            "description": "Self-label values",
             "refs": ["com.atproto.label.defs#selfLabels"]
           },
           "createdAt": { "type": "string", "format": "datetime" }

lexicons/app/bsky/feed/getActorFeeds.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of feeds created by the actor.",
+      "description": "Get a list of feeds (feed generator records) created by the actor (in the actor's repo).",
       "parameters": {
         "type": "params",
         "required": ["actor"],

lexicons/app/bsky/feed/getActorLikes.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a list of posts liked by an actor.",
+      "description": "Get a list of posts liked by an actor. Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],

lexicons/app/bsky/feed/getAuthorFeed.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a view of an actor's feed.",
+      "description": "Get a view of an actor's 'author feed' (post and reposts by the author). Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["actor"],
@@ -19,6 +19,7 @@
           "cursor": { "type": "string" },
           "filter": {
             "type": "string",
+            "description": "Combinations of post/repost types to include in response.",
             "knownValues": [
               "posts_with_replies",
               "posts_no_replies",

lexicons/app/bsky/feed/getFeed.json

@@ -4,7 +4,7 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a hydrated feed from an actor's selected feed generator.",
+      "description": "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.",
       "parameters": {
         "type": "params",
         "required": ["feed"],

lexicons/app/bsky/feed/getFeedGenerator.json

@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get information about a feed generator.",
+      "description": "Get information about a feed generator. Implemented by AppView.",
       "parameters": {
         "type": "params",
         "required": ["feed"],
         "properties": {
-          "feed": { "type": "string", "format": "at-uri" }
+          "feed": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "AT-URI of the feed generator record."
+          }
         }
       },
       "output": {
@@ -22,8 +26,14 @@
               "type": "ref",
               "ref": "app.bsky.feed.defs#generatorView"
             },
-            "isOnline": { "type": "boolean" },
-            "isValid": { "type": "boolean" }
+            "isOnline": {
+              "type": "boolean",
+              "description": "Indicates whether the feed generator service has been online recently, or else seems to be inactive."
+            },
+            "isValid": {
+              "type": "boolean",
+              "description": "Indicates whether the feed generator service is compatible with the record declaration."
+            }
           }
         }
       }

lexicons/app/bsky/feed/getFeedSkeleton.json

@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a skeleton of a feed provided by a feed generator.",
+      "description": "Get a skeleton of a feed provided by a feed generator. Auth is optional, depending on provider requirements, and provides the DID of the requester. Implemented by Feed Generator Service.",
       "parameters": {
         "type": "params",
         "required": ["feed"],
         "properties": {
-          "feed": { "type": "string", "format": "at-uri" },
+          "feed": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "Reference to feed generator record describing the specific feed being requested."
+          },
           "limit": {
             "type": "integer",
             "minimum": 1,

lexicons/app/bsky/feed/getLikes.json

@@ -4,13 +4,21 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get the list of likes.",
+      "description": "Get like records which reference a subject (by AT-URI and CID).",
       "parameters": {
         "type": "params",
         "required": ["uri"],
         "properties": {
-          "uri": { "type": "string", "format": "at-uri" },
-          "cid": { "type": "string", "format": "cid" },
+          "uri": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "AT-URI of the subject (eg, a post record)."
+          },
+          "cid": {
+            "type": "string",
+            "format": "cid",
+            "description": "CID of the subject record (aka, specific version of record), to filter likes."
+          },
           "limit": {
             "type": "integer",
             "minimum": 1,

lexicons/app/bsky/feed/getListFeed.json

@@ -4,12 +4,16 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get a view of a recent posts from actors in a list.",
+      "description": "Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.",
       "parameters": {
         "type": "params",
         "required": ["list"],
         "properties": {
-          "list": { "type": "string", "format": "at-uri" },
+          "list": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "Reference (AT-URI) to the list record."
+          },
           "limit": {
             "type": "integer",
             "minimum": 1,

lexicons/app/bsky/feed/getPostThread.json

@@ -4,20 +4,26 @@
   "defs": {
     "main": {
       "type": "query",
-      "description": "Get posts in a thread.",
+      "description": "Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.",
       "parameters": {
         "type": "params",
         "required": ["uri"],
         "properties": {
-          "uri": { "type": "string", "format": "at-uri" },
+          "uri": {
+            "type": "string",
+            "format": "at-uri",
+            "description": "Reference (AT-URI) to post record."
+          },
           "depth": {
             "type": "integer",
+            "description": "How many levels of reply depth should be included in response.",
             "default": 6,
             "minimum": 0,
             "maximum": 1000
           },
           "parentHeight": {
             "type": "integer",
+            "description": "How many levels of parent (and grandparent, etc) post to include.",
             "default": 80,
             "minimum": 0,
             "maximum": 1000