tangled.org
Monorepo for Tangled
tangled.org
1{
2 "lexicon": 1,
3 "id": "sh.tangled.query.enrichResponse",
4 "defs": {
5 "main": {
6 "type": "procedure",
7 "description": "like calling an xrpc query directly, but the response comes back with a stats sidecar: aggregate counts (stars, follows, issues...) for every did / at-uri / strong-ref found in the response. counts are computed synchronously from the server's local index, so there are no pending states to resolve later. any GET query the server implements can be hydrated, including queries it proxies elsewhere.",
8 "input": {
9 "encoding": "application/json",
10 "schema": {
11 "type": "object",
12 "required": [
13 "xrpc",
14 "enrich"
15 ],
16 "properties": {
17 "xrpc": {
18 "type": "string",
19 "format": "nsid",
20 "description": "NSID of the inner query to run, e.g. sh.tangled.repo.listRepos."
21 },
22 "params": {
23 "type": "unknown",
24 "description": "Parameters for the inner query, exactly as it declares them."
25 },
26 "enrich": {
27 "type": "array",
28 "items": {
29 "type": "ref",
30 "ref": "#linkDescriptor"
31 },
32 "description": "Counts to compute for each found reference. A descriptor only applies to references it can meaningfully point at: a did can carry author-side counts (.repo), an at-uri can carry subject-side counts."
33 },
34 "sources": {
35 "type": "array",
36 "items": {
37 "type": "string"
38 },
39 "description": "RecordPaths into the inner response restricting which references get counted. When omitted, every did / at-uri / strong-ref in the response is counted. Paths that match nothing yield empty stats rather than an error."
40 },
41 "viewer": {
42 "type": "string",
43 "format": "did",
44 "description": "DID whose own relation to each reference is looked up for viewer-type descriptors, e.g. whether this did starred the found repo and with which record. Required when any enrich descriptor uses type viewer."
45 }
46 }
47 }
48 },
49 "output": {
50 "encoding": "application/json",
51 "schema": {
52 "type": "object",
53 "required": [
54 "output",
55 "stats"
56 ],
57 "properties": {
58 "output": {
59 "type": "unknown",
60 "description": "The inner query's response, unmodified."
61 },
62 "stats": {
63 "type": "unknown",
64 "description": "Reference value (did or at-uri) -> link source (echoed verbatim from the request) -> aggregation results. Example: stats[\"did:plc:...\"][\"sh.tangled.graph.follow:subject\"] = {\"count\": 12, \"distinctAuthors\": 11}."
65 }
66 }
67 }
68 },
69 "errors": [
70 {
71 "name": "UnknownQuery",
72 "description": "The xrpc parameter does not name a query this server can execute."
73 },
74 {
75 "name": "InvalidSourcePath",
76 "description": "A sources entry is not valid RecordPath syntax."
77 },
78 {
79 "name": "InvalidLinkDescriptor",
80 "description": "An enrich entry names an unknown collection, or a path the server's index does not support."
81 }
82 ]
83 },
84 "linkDescriptor": {
85 "type": "object",
86 "required": [
87 "source",
88 "type"
89 ],
90 "description": "one aggregate count: records whose reference field equals the found reference, addressed by a constellation-style link source (\"collection:recordpath\"). envelope paths (.repo etc.) address the record's own metadata instead of its contents.",
91 "properties": {
92 "source": {
93 "type": "string",
94 "description": "Link source: the collection whose records are counted, a colon, then a RecordPath naming the reference field (e.g. sh.tangled.feed.star:subject, sh.tangled.feed.star:subject.uri), or an envelope field: .repo (authoring repo), .collection, .rkey, or bare . (the record's own at-uri)."
95 },
96 "type": {
97 "type": "string",
98 "knownValues": ["count", "distinctAuthors", "viewer"],
99 "description": "What to compute over matching records: how many records (count), how many distinct authors (distinctAuthors), or the viewer's own record among the matches (viewer, requires the top-level viewer param). Results land in the stats sidecar at stats[ref][source][type]."
100 }
101 }
102 }
103 }
104}