Question Envelope v1¶

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

Machine-readable schema for signed question publication on the procurement event layer.

Governing Basis¶

Project Lineage¶

Requirements¶

doc/project/50-requirements/requirements-006.md

Stories¶

Fields¶

Field	Required	Shape	Description
`schema/v`	`yes`	const: `1`	Schema version.
`question/id`	`yes`	string	Stable lifecycle identifier that links the event layer, room layer, and later procurement artifacts.
`created-at`	`yes`	string	Publication timestamp of the question envelope.
`sender/node-id`	`yes`	string	Swarm-facing routing and hosting identity of the Node that published the envelope.
`sender/participant-id`	`no`	string	Participation-role identity that authored or initiated the question publication. In the MVP baseline this may be role-distinct but key-equal to the local `node-id`. This is the authored participation identity, not the network routing identity.
`sender/federation-id`	`no`	string	Federation scope of the sender when publication is federation-bound.
`sender/pod-user-id`	`no`	string	Hosted-user identity when publication is delegated through a later pod-backed client flow. This is additive to, not a replacement for, `sender/participant-id`, and it is not part of the networking routing contract.
`sender/public-nym`	`no`	string	Optional public-facing pseudonym shown at protocol boundaries where policy allows it. This is optional presentation metadata, not a routing identity.
`author/nym`	`no`	string	Visible authored pseudonym when the envelope uses a nym-authored path instead of disclosing `sender/participant-id`.
`auth/nym-certificate`	`no`	ref: `nym-certificate.v1.schema.json`	Attached council-issued nym certificate for the pseudonymous authored path. Its `nym/id` should match `author/nym`.
`auth/nym-signature`	`no`	ref: `#/$defs/signature`	Nym signature over the envelope body when the question uses the pseudonymous authored path.
`ttl-sec`	`yes`	integer	Time-to-live of the open request on the event layer.
`question/text`	`yes`	string	Full textual question content published at the envelope layer in the current split architecture.
`question/tags`	`yes`	array	Semantic tags used for routing and responder matching.
`question/urgency`	`no`	enum: `low`, `normal`, `high`, `critical`	Advisory urgency classification visible to eligible responders.
`delivery/scope`	`yes`	enum: `private-to-swarm`, `federation-local`, `cross-federation`, `global`	Transport-level dissemination scope derived from the chosen exposure policy.
`delivery/response-channel-id`	`yes`	string	Room or channel identifier bound to the same question lifecycle.
`follow-ups/allowed`	`no`	boolean	Whether responders may expect iterative clarification or debate after initial publication.
`request/exposure-mode`	`yes`	enum: `private-to-swarm`, `federation-local`, `public-call-for-help`	User-facing exposure policy chosen before submission.
`room-policy/profile`	`no`	enum: `none`, `mediated-only`, `direct-live-allowed`	Requested room policy profile for the answer room created from this envelope.
`responder/min-reputation`	`no`	number	Minimum reputation threshold for eligible responders.
`models/require`	`no`	array	Required model or capability labels.
`models/exclude`	`no`	array	Disallowed model or capability labels.
`languages`	`no`	array	Preferred answer languages.
`reward/mode`	`yes`	enum: `none`, `collaborative`, `procurement`	Whether the request seeks open collaboration only or explicit responder procurement.
`procurement/max-price-amount`	`no`	integer	Maximum acceptable price in minor units when procurement is enabled. When `procurement/price-currency = ORC`, the value uses ORC minor units with fixed scale `2`.
`procurement/price-currency`	`no`	string	Currency or settlement unit symbol associated with procurement ceiling and offers.
`procurement/max-wait-sec`	`no`	integer	Maximum wait time acceptable to the asker when procurement is enabled.
`signature`	`no`	ref: `#/$defs/signature`	Detached or embedded signature container for the participant-authored publication path.
`policy_annotations`	`no`	object	Optional federation- or implementation-local policy annotations that do not change the core lifecycle semantics.

Definitions¶

Definition	Shape	Description
`signature`	object

Conditional Rules¶

Rule 1¶

Constraint:

{
  "oneOf": [
    {
      "required": [
        "sender/participant-id",
        "signature"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "author/nym"
            ]
          },
          {
            "required": [
              "auth/nym-certificate"
            ]
          },
          {
            "required": [
              "auth/nym-signature"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "author/nym",
        "auth/nym-certificate",
        "auth/nym-signature"
      ],
      "not": {
        "required": [
          "sender/participant-id"
        ]
      }
    }
  ]
}

Rule 2¶

When:

{
  "properties": {
    "request/exposure-mode": {
      "const": "private-to-swarm"
    }
  },
  "required": [
    "request/exposure-mode"
  ]
}

Then:

{
  "properties": {
    "delivery/scope": {
      "const": "private-to-swarm"
    }
  }
}

Rule 3¶

When:

{
  "properties": {
    "request/exposure-mode": {
      "const": "federation-local"
    }
  },
  "required": [
    "request/exposure-mode"
  ]
}

Then:

{
  "properties": {
    "delivery/scope": {
      "const": "federation-local"
    }
  },
  "required": [
    "sender/federation-id"
  ]
}

Rule 4¶

When:

{
  "properties": {
    "request/exposure-mode": {
      "const": "public-call-for-help"
    }
  },
  "required": [
    "request/exposure-mode"
  ]
}

Then:

{
  "properties": {
    "delivery/scope": {
      "enum": [
        "cross-federation",
        "global"
      ]
    }
  }
}

Rule 5¶

When:

{
  "properties": {
    "reward/mode": {
      "const": "procurement"
    }
  },
  "required": [
    "reward/mode"
  ]
}

Then:

{
  "required": [
    "procurement/max-price-amount",
    "procurement/price-currency",
    "procurement/max-wait-sec"
  ]
}

Field Semantics¶

`schema/v`¶

Required: yes
Shape: const: 1

Schema version.

`question/id`¶

Required: yes
Shape: string

Stable lifecycle identifier that links the event layer, room layer, and later procurement artifacts.

`created-at`¶

Required: yes
Shape: string

Publication timestamp of the question envelope.

`sender/node-id`¶

Required: yes
Shape: string

Swarm-facing routing and hosting identity of the Node that published the envelope.

`sender/participant-id`¶

Required: no
Shape: string

Participation-role identity that authored or initiated the question publication. In the MVP baseline this may be role-distinct but key-equal to the local node-id. This is the authored participation identity, not the network routing identity.

`sender/federation-id`¶

Required: no
Shape: string

Federation scope of the sender when publication is federation-bound.

`sender/pod-user-id`¶

Required: no
Shape: string

Hosted-user identity when publication is delegated through a later pod-backed client flow. This is additive to, not a replacement for, sender/participant-id, and it is not part of the networking routing contract.

`sender/public-nym`¶

Required: no
Shape: string

Optional public-facing pseudonym shown at protocol boundaries where policy allows it. This is optional presentation metadata, not a routing identity.

`author/nym`¶

Required: no
Shape: string

Visible authored pseudonym when the envelope uses a nym-authored path instead of disclosing sender/participant-id.

`auth/nym-certificate`¶

Required: no
Shape: ref: nym-certificate.v1.schema.json

Attached council-issued nym certificate for the pseudonymous authored path. Its nym/id should match author/nym.

`auth/nym-signature`¶

Required: no
Shape: ref: #/$defs/signature

Nym signature over the envelope body when the question uses the pseudonymous authored path.

`ttl-sec`¶

Required: yes
Shape: integer

Time-to-live of the open request on the event layer.

`question/text`¶

Required: yes
Shape: string

Full textual question content published at the envelope layer in the current split architecture.

`question/tags`¶

Required: yes
Shape: array

Semantic tags used for routing and responder matching.

`question/urgency`¶

Required: no
Shape: enum: low, normal, high, critical

Advisory urgency classification visible to eligible responders.

`delivery/scope`¶

Required: yes
Shape: enum: private-to-swarm, federation-local, cross-federation, global

Transport-level dissemination scope derived from the chosen exposure policy.

`delivery/response-channel-id`¶

Required: yes
Shape: string

Room or channel identifier bound to the same question lifecycle.

`follow-ups/allowed`¶

Required: no
Shape: boolean

Whether responders may expect iterative clarification or debate after initial publication.

`request/exposure-mode`¶

Required: yes
Shape: enum: private-to-swarm, federation-local, public-call-for-help

User-facing exposure policy chosen before submission.

`room-policy/profile`¶

Required: no
Shape: enum: none, mediated-only, direct-live-allowed

Requested room policy profile for the answer room created from this envelope.

`responder/min-reputation`¶

Required: no
Shape: number

Minimum reputation threshold for eligible responders.

`models/require`¶

Required: no
Shape: array

Required model or capability labels.

`models/exclude`¶

Required: no
Shape: array

Disallowed model or capability labels.

`languages`¶

Required: no
Shape: array

Preferred answer languages.

`reward/mode`¶

Required: yes
Shape: enum: none, collaborative, procurement

Whether the request seeks open collaboration only or explicit responder procurement.

`procurement/max-price-amount`¶

Required: no
Shape: integer

Maximum acceptable price in minor units when procurement is enabled. When procurement/price-currency = ORC, the value uses ORC minor units with fixed scale 2.

`procurement/price-currency`¶

Required: no
Shape: string

Currency or settlement unit symbol associated with procurement ceiling and offers.

`procurement/max-wait-sec`¶

Required: no
Shape: integer

Maximum wait time acceptable to the asker when procurement is enabled.

`signature`¶

Required: no
Shape: ref: #/$defs/signature

Detached or embedded signature container for the participant-authored publication path.

`policy_annotations`¶

Required: no
Shape: object

Optional federation- or implementation-local policy annotations that do not change the core lifecycle semantics.

Definition Semantics¶

`$defs.signature`¶

Shape: object

Question Envelope v1¶

Governing Basis¶

Project Lineage¶

Requirements¶

Stories¶

Fields¶

Definitions¶

Conditional Rules¶

Rule 1¶

Rule 2¶

Rule 3¶

Rule 4¶

Rule 5¶

Field Semantics¶

schema/v¶

question/id¶

created-at¶

sender/node-id¶

sender/participant-id¶

sender/federation-id¶

sender/pod-user-id¶

sender/public-nym¶

author/nym¶

auth/nym-certificate¶

auth/nym-signature¶

ttl-sec¶

question/text¶

question/tags¶

question/urgency¶

delivery/scope¶

delivery/response-channel-id¶

follow-ups/allowed¶

request/exposure-mode¶

room-policy/profile¶

responder/min-reputation¶

models/require¶

models/exclude¶

languages¶

reward/mode¶

procurement/max-price-amount¶

procurement/price-currency¶

procurement/max-wait-sec¶

signature¶

policy_annotations¶

Definition Semantics¶

$defs.signature¶

`schema/v`¶

`question/id`¶

`created-at`¶

`sender/node-id`¶

`sender/participant-id`¶

`sender/federation-id`¶

`sender/pod-user-id`¶

`sender/public-nym`¶

`author/nym`¶

`auth/nym-certificate`¶

`auth/nym-signature`¶

`ttl-sec`¶

`question/text`¶

`question/tags`¶

`question/urgency`¶

`delivery/scope`¶

`delivery/response-channel-id`¶

`follow-ups/allowed`¶

`request/exposure-mode`¶

`room-policy/profile`¶

`responder/min-reputation`¶

`models/require`¶

`models/exclude`¶

`languages`¶

`reward/mode`¶

`procurement/max-price-amount`¶

`procurement/price-currency`¶

`procurement/max-wait-sec`¶

`signature`¶

`policy_annotations`¶

`$defs.signature`¶