init

2.1-object-tree-schema.md

@@ -0,0 +1,73 @@
+# 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で表す。
+
+子エントリは所有・内包関係を表す。非内包の意味的関係はLinkとして扱う。
+
+例えばRepository配下の`issues`は子エントリとして自然だが、Issueから関連Pull Requestへの参照はLinkとして表現する。
+
+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結果として返す。
+
+## 2.1.6 Link
+
+LinkはTree上の所有・内包ではない意味的関係を表す。
+
+Linkによって未知のエントリが発見された場合、ClientはそのエントリをKnown Spaceへ追加できる。ただし、それだけではDiscoverable Spaceには追加しない。
+
+そのエントリを起点に`fetch_tree`を行い、indexableなTreeを取得した場合にのみ、その範囲をdiscover対象として扱える。
+
+## 2.1.7 Core Protocolとの対応
+
+`fetch(entry)`は、指定されたTree上の位置にあるObjectの公開情報を取得する。
+
+`fetch_tree(entry, depth, limit)`は、指定エントリからindexable child edgeだけを幅優先探索し、Treeとしてまとめて返す。
+
+探索が`depth`または`limit`により打ち切られた場合は、レスポンスで`truncated`を必ず明示する。
+
+Operationを実行した結果として、新しいエントリ、エントリツリー、Linkが返る場合がある。Clientはそれらを構造化された発見結果としてKnown Spaceへ統合する。