[Milestone task]: 独自lexiconの定義方法の調査

[nkte8]

How it would to do to accomplish?

lexiconをどのように定義すれば正であるかの調査の実施。

What it should do to accomplish?

具体的なlexiconの定義方法や書式についての整理

[nkte8]

lexiconのタイプについて

lexiconにはメソッドタイプ・レコードタイプ・トークンタイプの定義がある

参考: https://atproto.com/guides/lexicon

メソッドの例

getProfile: https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/actor/getProfile.json

{
  "lexicon": 1,
  "id": "app.bsky.actor.getProfile",
  "defs": {
    "main": {
      "type": "query",
      "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": {  # <------------- "actor"入力値に関する定義
            "type": "string",
            "format": "at-identifier",
            "description": "Handle or DID of account to fetch profile of."
          }
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {  # <---------- 返り値のスキーマ定義
          "type": "ref", # <----------- 他定義からの参照(?)
          "ref": "app.bsky.actor.defs#profileViewDetailed"  # <----------- 参照箇所を定義
        }
      }
    }
  }
}

レコードタイプ

※ドキュメントが不足しているため、誤っている可能性があります。

defs.json https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/actor/defs.json

{
  "lexicon": 1,
  "id": "app.bsky.actor.defs", 
  "defs": {
...
    "profileViewDetailed": { # <------- app.bsky.actor.defs#profileViewDetailed が指す定義
      "type": "object",
      "required": ["did", "handle"], # <----- 必須パラメータ（=outputの場合は必ず返り値に含まれるパラメータ）
      "properties": {
        "did": { "type": "string", "format": "did" }, # <----- "did"の定義, string型で、format: didの体を取る
        "handle": { "type": "string", "format": "handle" },
        "displayName": {
          "type": "string",
          "maxGraphemes": 64,
          "maxLength": 640
        },
        "description": {
          "type": "string",
          "maxGraphemes": 256,
          "maxLength": 2560
        },
        "avatar": { "type": "string", "format": "uri" },
        "banner": { "type": "string", "format": "uri" },
        "followersCount": { "type": "integer" },
        "followsCount": { "type": "integer" },
        "postsCount": { "type": "integer" },
        "associated": {
          "type": "ref",
          "ref": "#profileAssociated"
        },
        "indexedAt": { "type": "string", "format": "datetime" },
        "viewer": { "type": "ref", "ref": "#viewerState" },
        "labels": {
          "type": "array",
          "items": { "type": "ref", "ref": "com.atproto.label.defs#label" }
        }
      }
    },
...

※formatについてはenum定義自体は発見しているが、どのようにして判別しているのかは不明
formatの定義: https://github.com/bluesky-social/atproto/blob/115df69574af9297c2c81a9295a79222648eb629/packages/lexicon/src/types.ts#L31-L41

トークンタイプ

※現在のblueskyではあまり使われていない？発見できず。

以下のような定義を作成すると

{
  "lexicon": 1,
  "id": "com.example.green",
  "type": "token",
  "description": "Traffic light state representing 'Go!'.",
}
{
  "lexicon": 1,
  "id": "com.example.yellow",
  "type": "token",
  "description": "Traffic light state representing 'Stop Soon!'.",
}
{
  "lexicon": 1,
  "id": "com.example.red",
  "type": "token",
  "description": "Traffic light state representing 'Stop!'.",
}

次のように使うことができる

{
  "lexicon": 1,
  "id": "com.example.trafficLight",
  "type": "record",
  "record": {
    "type": "object",
    "required": ["state"],
    "properties": {
      "state": {
        "type": "string",
        "knownValues": [
          "com.example.green", # <-------- tokenタイプのlexiconをそのまま利用
          "com.example.yellow",
          "com.example.red"
        ]
      },
    }
  }
}

lexiconの生成(?)

lexiconは @atproto/lexiconを使って生成することができる（？）
https://github.com/bluesky-social/atproto/tree/115df69574af9297c2c81a9295a79222648eb629/packages/lexicon

ドキュメントが皆無だと思われる。利用のためには検証が必要。

[nkte8]

lexiconの命名について

NSIDを用いている。基本的には逆引きDNS名。今のところはASCII文字のみ許容される

参考: https://atproto.com/specs/nsid

これとDNS本体（PDSがlexiconを見に行くための情報?）がどういった関係性なのかは不明
明らかになった場合は、#67 に記載すること。