68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# 2.1. Object tree / Schema
|
|
|
|
## 2.1.1 目的
|
|
|
|
このページでは、WIP Core ModelにおけるObject treeと、それらをClientへ公開する際の最小スキーマを整理する。
|
|
|
|
WIPでは、**Objectとエントリを別のデータ構造として定義しない**。ObjectをWorldspaceのTree上に配置されたものとして扱うとき、そのObjectをエントリと呼ぶ。
|
|
|
|
## 2.1.2 Objectとエントリ
|
|
|
|
**Object**はWIP上で観測・操作される対象そのものである。
|
|
|
|
**エントリ**は、そのObjectをWorldspaceのTree上の位置として見たときの呼び名である。
|
|
|
|
したがって、エントリがObjectへの参照を別途保持する、あるいはエントリ schemaとObject schemaを二重に定義することは前提としない。
|
|
|
|
ObjectがTree上に配置されることでエントリとなり、pathはその配置位置を表すnavigation coordinateとなる。
|
|
|
|
同じObjectが複数の位置に現れる場合、一つのObjectが複数のエントリとして観測され得る。
|
|
|
|
## 2.1.3 公開情報
|
|
|
|
Object / エントリが公開する情報は、Worldspaceを探索し、対象に対して何ができるかを理解するための**interface metadata**である。
|
|
|
|
現時点では、少なくとも次の情報を想定する。
|
|
|
|
- `name` — Objectの短い名前。Tree上ではエントリ名としても用いられる。
|
|
- `description` — Objectが何を表すかを説明する短い自然言語。長文documentationではなく、探索・判断に必要な最小限のsemantic metadataとする。
|
|
- `operations` — Objectが公開するOperation。詳細は [2.2. Operation](2.2-operation.md) で定義する。
|
|
- `children` — Tree上でindexableとして公開される子Object / エントリ。
|
|
- `ref` — 必要に応じて公開される、同一Objectを再参照するための外部Handle。
|
|
|
|
WIPではドメインデータそのものをpropertiesとして直接公開することを前提としない。本文、metadata、状態などを読む行為もOperationとして表現する。
|
|
|
|
## 2.1.4 Tree
|
|
|
|
Worldspaceは、Objectが親子関係によって配置されたTreeとして観測される。
|
|
|
|
Tree上のObjectをエントリとして呼び、その位置をpathで表す。
|
|
|
|
子エントリは所有・内包関係を表す。非内包の意味的関係は、それを表すOperationから関連エントリのpathを返す。
|
|
|
|
例えばRepository配下の`issues`は子エントリとして自然だが、Issueから関連Pull Requestを得る場合は`get_related_pull_requests`のようなOperationで表現する。
|
|
|
|
Treeはmaterializedな全世界ではなく、HostがそのClientに対して公開する**lazy / virtual tree**である。Hostは全Objectを事前保持する必要はなく、`fetch`や`fetch_tree`に応じて動的に解決してよい。
|
|
|
|
## 2.1.5 Indexable children
|
|
|
|
子エントリには、機械的探索で辿ってよいものと、Operationによってのみ発見されるものがある。
|
|
|
|
`fetch_tree`が辿るのは**indexableとして公開された子エントリのみ**とする。
|
|
|
|
indexableな子エントリは、Worldspaceの構造理解に必要で、通常は件数が小さいものを想定する。
|
|
|
|
一方、大量のIssue、検索結果、一時的なObject群などはindexable childとして露出しない。必要なエントリはCollection Objectの`query` / `list`等のOperation結果として返す。
|
|
|
|
Operation結果として返されることは、実行対象との親子関係を意味しない。Collectionの要素を返す場合だけでなく、親、兄弟、関連Objectなど、Worldspace内の別の位置にあるエントリを発見するためにもOperationを利用できる。
|
|
|
|
## 2.1.6 Core Protocolとの対応
|
|
|
|
`fetch(entry)`は、指定されたTree上の位置にあるObjectの公開情報を取得する。
|
|
|
|
`fetch_tree(entry, depth, limit)`は、指定エントリからindexable child edgeだけを幅優先探索し、Treeとしてまとめて返す。
|
|
|
|
探索が`depth`または`limit`により打ち切られた場合は、レスポンスで`truncated`を必ず明示する。
|
|
|
|
Operationを実行した結果には、WIP IDLの`entry`型として新しいエントリのpathが含まれる場合がある。Clientはそれらを一時的な発見結果として扱い、後続の参照に必要なものだけを取得してKnown Spaceへ統合できる。
|