Skip to content

Response Envelope v1

Source schema: doc/schemas/response-envelope.v1.schema.json

Machine-readable schema for the final answer returned from swarm procurement or collaborative answer flow. This artifact remains participant-scoped in v1 and does not define a nym-authored alternative path.

Governing Basis

Project Lineage

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
response/id yes string Stable identifier of the returned response boundary object.
question/id yes string Question lifecycle identifier from which the response originated.
room/id no string Room or execution path that produced the final answer or accepted summary.
contract/id no string Linked procurement contract when payment or narrowed execution applied.
receipt/id no string Linked procurement receipt when settlement or explicit rejection was recorded.
accepted-summary/id no string Accepted summary identifier when the final answer is derived from room convergence.
created-at yes string Response publication timestamp.
source/node-id yes string Primary remote responder or gateway node at the protocol boundary. This is the routing or hosting identity, not the authored participation identity. In v1 this MUST use canonical node:did:key:z... form.
source/participant-id yes string Participation-role identity that authored, endorsed, or stood behind the returned answer payload. In v1 this remains the accountable authored identity rather than being replaced by a pseudonymous nym path and MUST use canonical participant:did:key:z... form.
gateway/node-id no string Gateway node when the result was delivered through a delegated host or other relay role.
answer/content yes unspecified Returned answer payload in textual or structured form.
answer/format yes enum: plain-text, markdown, json, edn, mixed Representation format of the returned answer payload.
confidence/signal yes number Composite confidence signal shown to the consumer of the response.
uncertainty/signal no number Optional uncertainty signal paired with or derived from confidence.
human-linked-participation yes boolean Whether human-linked input materially influenced the final result.
provenance/origin-classes yes array Origin classes materially present in the answer path.
policy_annotations no object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "human-linked-participation": {
      "const": true
    }
  },
  "required": [
    "human-linked-participation"
  ]
}

Then:

{
  "properties": {
    "provenance/origin-classes": {
      "contains": {
        "enum": [
          "node-mediated-human",
          "human-live"
        ]
      }
    }
  }
}

Rule 2

When:

{
  "properties": {
    "human-linked-participation": {
      "const": false
    }
  },
  "required": [
    "human-linked-participation"
  ]
}

Then:

{
  "properties": {
    "provenance/origin-classes": {
      "items": {
        "const": "node-generated"
      }
    }
  }
}

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

response/id

  • Required: yes
  • Shape: string

Stable identifier of the returned response boundary object.

question/id

  • Required: yes
  • Shape: string

Question lifecycle identifier from which the response originated.

room/id

  • Required: no
  • Shape: string

Room or execution path that produced the final answer or accepted summary.

contract/id

  • Required: no
  • Shape: string

Linked procurement contract when payment or narrowed execution applied.

receipt/id

  • Required: no
  • Shape: string

Linked procurement receipt when settlement or explicit rejection was recorded.

accepted-summary/id

  • Required: no
  • Shape: string

Accepted summary identifier when the final answer is derived from room convergence.

created-at

  • Required: yes
  • Shape: string

Response publication timestamp.

source/node-id

  • Required: yes
  • Shape: string

Primary remote responder or gateway node at the protocol boundary. This is the routing or hosting identity, not the authored participation identity. In v1 this MUST use canonical node:did:key:z... form.

source/participant-id

  • Required: yes
  • Shape: string

Participation-role identity that authored, endorsed, or stood behind the returned answer payload. In v1 this remains the accountable authored identity rather than being replaced by a pseudonymous nym path and MUST use canonical participant:did:key:z... form.

gateway/node-id

  • Required: no
  • Shape: string

Gateway node when the result was delivered through a delegated host or other relay role.

answer/content

  • Required: yes
  • Shape: unspecified

Returned answer payload in textual or structured form.

answer/format

  • Required: yes
  • Shape: enum: plain-text, markdown, json, edn, mixed

Representation format of the returned answer payload.

confidence/signal

  • Required: yes
  • Shape: number

Composite confidence signal shown to the consumer of the response.

uncertainty/signal

  • Required: no
  • Shape: number

Optional uncertainty signal paired with or derived from confidence.

human-linked-participation

  • Required: yes
  • Shape: boolean

Whether human-linked input materially influenced the final result.

provenance/origin-classes

  • Required: yes
  • Shape: array

Origin classes materially present in the answer path.

policy_annotations

  • Required: no
  • Shape: object