Skip to main content
Three JSON shapes define the ShoulderTap protocol: ContextRequest (a consumer asking for context), ContextProposal (an expert’s answer), and ConsumerRegistration (how a consumer signs up). The authoritative JSON Schemas live in spec/schemas/*.json in the repository, generated directly from the reference implementation and checked for drift.

​
ContextRequest

A consumer’s request for context. Four fields are required: kind, topic, question, consumer.
​
string
ULID, prefix req_. Engine-assigned if omitted.
​
string
default:"default"
Fixed to "default" in the single-tenant community edition.
​
string
required
The question kind; determines the answer’s capture schema and which consumers it routes back to. See Kinds.
​
string
required
The routing key. Normalized to lowercase for matching against expert topics.
​
string
required
The raw question.
​
object
Free-form, shown to the expert. context.asked_because becomes the “why I’m asking” line in the ask.
​
array | null
default:"null"
[{ expert_id, role }]. Bypasses topic routing entirely and asks these experts directly. role defaults to "primary".
​
object
Per-request overrides for the config defaults.
​
string
required
The submitting consumer’s id.
​
string | null
default:"null"
Requests with the same key from the same consumer, within the dedup window, are deduplicated. See Concepts.
​
object | null
default:"null"
Free-form passthrough, for example { "trace_id": "..." }.
​
string
ISO-8601 date-time.

​
Example

​
ContextProposal

An expert’s answer, structured and attributed. Required: request_id, kind, answer, provenance, consumer.
​
string
ULID, prefix prop_. Engine-assigned.
​
string
required
The request this answers.
​
string
required
Mirrors the request’s kind.
​
string
required
The expert’s verbatim reply. Never dropped, even if structuring fails.
​
object | null
default:"null"
The LLM-structured form of the answer, matching the kind’s schema. null on extraction failure or when confidence is below 0.3.
​
number | null
default:"null"
The structurer’s self-assessed extraction confidence, independent of whether structured ended up null.
​
object
required
Who answered and how.
​
string
required
​
string
ISO-8601 date-time.

​
ConsumerRegistration

How a consumer registers to receive answers. Required: id, handles_kinds, delivery.
​
string
required
The consumer’s id, for example bi.assistant.
​
array
required
The kinds this consumer deals with.
​
object
required
A discriminated union on type: { "type": "webhook", "url": "..." } or { "type": "inprocess" } for an SDK-embedded consumer.
​
string
default:"P1D"
ISO-8601 duration for the deduplication window (default one day).
​
boolean
default:"false"
Deliver proposals without human review. Off by default — see the warning in Consumers.
​
object
Optional map of kind name to a custom JSON Schema, overriding the built-in for that kind. See Kinds.