2.1. Object tree / Schema

2.1.1 目的

このページでは、WIP Core ModelにおけるObject treeと、それらをClientへ公開する際の最小スキーマを整理する。

WIPでは、Objectとエントリを別のデータ構造として定義しない。ObjectをWorldspaceのTree上に配置されたものとして扱うとき、そのObjectをエントリと呼ぶ。

ObjectはWIP上で観測・操作される対象そのものである。

エントリは、そのObjectをWorldspaceのTree上の位置として見たときの呼び名である。

したがって、エントリがObjectへの参照を別途保持する、あるいはエントリ schemaとObject schemaを二重に定義することは前提としない。

ObjectがTree上に配置されることでエントリとなり、pathはその配置位置を表すnavigation coordinateとなる。

同じObjectが複数の位置に現れる場合、一つのObjectが複数のエントリとして観測され得る。

Object / エントリが公開する情報は、Worldspaceを探索し、対象に対して何ができるかを理解するためのinterface metadataである。

現時点では、少なくとも次の情報を想定する。

name — Objectの短い名前。Tree上ではエントリ名としても用いられる。
description — Objectが何を表すかを説明する短い自然言語。長文documentationではなく、探索・判断に必要な最小限のsemantic metadataとする。
operations — Objectが公開するOperation。詳細は 2.2. Operation で定義する。
children — Tree上でindexableとして公開される子Object / エントリ。
ref — 必要に応じて公開される、同一Objectを再参照するための外部Handle。

WIPではドメインデータそのものをpropertiesとして直接公開することを前提としない。本文、metadata、状態などを読む行為もOperationとして表現する。

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に応じて動的に解決してよい。

子エントリには、機械的探索で辿ってよいものと、Operationによってのみ発見されるものがある。

fetch_treeが辿るのはindexableとして公開された子エントリのみとする。

indexableな子エントリは、Worldspaceの構造理解に必要で、通常は件数が小さいものを想定する。

一方、大量のIssue、検索結果、一時的なObject群などはindexable childとして露出しない。必要なエントリはCollection Objectのquery / list等のOperation結果として返す。

LinkはTree上の所有・内包ではない意味的関係を表す。

Linkによって未知のエントリが発見された場合、ClientはそのエントリをKnown Spaceへ追加できる。ただし、それだけではDiscoverable Spaceには追加しない。

そのエントリを起点にfetch_treeを行い、indexableなTreeを取得した場合にのみ、その範囲をdiscover対象として扱える。

fetch(entry)は、指定されたTree上の位置にあるObjectの公開情報を取得する。

fetch_tree(entry, depth, limit)は、指定エントリからindexable child edgeだけを幅優先探索し、Treeとしてまとめて返す。

探索がdepthまたはlimitにより打ち切られた場合は、レスポンスでtruncatedを必ず明示する。

Operationを実行した結果として、新しいエントリ、エントリツリー、Linkが返る場合がある。Clientはそれらを構造化された発見結果としてKnown Spaceへ統合する。