Przejdź do treści

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.
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.
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:

{
  "required": [
    "contract/id"
  ]
}

Then:

{
  "required": [
    "receipt/id"
  ]
}

Rule 2

When:

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

Then:

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

Rule 3

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.

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.

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