プレビュー版

PocketSign Link v2 は現在プレビュー版です。正式提供までに仕様が変更される可能性があります。

リソースモデル

Registry では、扱う情報の単位を リソース定義、ユーザーごとの実データを リソース値 として管理します。基本の考え方は Link v1 と近いですが、PocketSign Link v2 ではエイリアス、算出リソース、検証プロセス情報などを拡張しています。

リソース定義

リソース定義は、Registry が取り扱う情報や権限の単位です。

項目	説明
ID	UUID 形式のリソース定義の ID
表示名	ユーザーに表示するリソースの名前
説明	ユーザーに表示するリソースの説明
カテゴリ	アプリ画面上での分類表示時に使用されるリソース定義が属するカテゴリ
エイリアス	エイリアスを参照
リソース種別	リソース種別を参照
値フォーマット	値フォーマットを参照

リソース種別

リソース種別	説明	要求できる権限	備考
格納リソース	Registry 自身が値を保存するリソース	`READ` / `WRITE`	値フォーマットは `string` / `json` / `binary` のいずれか
実行リソース	特定機能を呼び出す権限を表すリソース	`INVOKE`	リソース値の実体は持たない
算出リソース	他のリソースやシステム上の情報から、読み取り時に値を導出するリソース	`READ`	値の実体を DB に直接持たないことがある。Registry が提供する組み込みリソースとして定義される

エイリアス

PocketSign Link v2 では、リソース定義 ID に加えて human-readable なエイリアスを使えます。 API では、id_or_alias で ID かエイリアスのどちらでも指定できます。

例:

my_org/favorite-food
klon/service.{service-id}.subscription-id

値フォーマット

リソース定義に従って、ユーザーごとの実データはリソース値として Registry に保存されます。リソース値はリソース定義の「値フォーマット」で指定した形式で、読み書きし、保存されています。

値フォーマットには次の 3 種類があります。

種類	説明
`string`	UTF-8 文字列
`json`	JSON Schema で構造を保証する JSON
`binary`	ファイルなどのバイナリ

`string` フォーマット

最も単純な形式です。 1 つの文字列として表せる値に向いています。

例:

氏名
メールアドレス
好きな食べ物
外部システム連携 ID

`json` フォーマット

構造を持ったデータを 1 つのリソースとして扱いたいときに使います。単なる JSON 文字列ではなく、リソース定義に登録された JSON Schema に従う JSON 値として扱われます。

例:

ユーザープロフィール
設定オブジェクト
複数項目を持つ申請データ

JSON Schema

json フォーマットのリソース定義では、JSON Schemaを登録します。たとえば次のようなスキーマを定義できます。

{
  "type": "object",
  "properties": {
    "phone": { "type": "string" },
    "email": { "type": "string" },
    "hobbies": {
      "type": "array",
      "items": { "type": "string" }
    },
    "address_detail": {
      "type": "object",
      "properties": {
        "zip": { "type": "string" },
        "building": { "type": "string" }
      }
    }
  }
}

json フォーマットの値を書き込むときは、その JSON がリソース定義に登録された JSON Schema を満たしているか検証されます。 JSON Schemaに適合しない値を書き込もうとした場合はエラーが返却されます。

`binary` フォーマット

文字列や JSON では表しにくい、ファイルやバイト列データ向けの形式です。

例:

PDF
画像
バイナリ証憑
署名済みデータ

検証プロセス情報

PocketSign Link v2 では、値そのものに加えて、その値がどのように検証されたかをメタデータとして返すことがあります。

例:

マイナンバーカード由来の情報かどうか
OTP で所有確認済みのメールアドレスかどうか

権限モデル

Registry では、どのユーザーがどのサービスに対してどのリソースのどの操作を許可しているかを権限として持ちます。サービスはユーザーが許可していないリソースにアクセスすることはできません。

動詞

動詞	意味
`READ`	値の読み取り
`WRITE`	値の書き込み
`INVOKE`	実行リソースの呼び出し

リソース定義​

リソース種別​

エイリアス​

値フォーマット​

string フォーマット​

json フォーマット​

JSON Schema​

binary フォーマット​

検証プロセス情報​

権限モデル​

動詞​

関連ページ​