Retrieval Response v1

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

Machine-readable schema for archivist or vault responses to retrieval requests.

Governing Basis

• doc/project/30-stories/story-003.md
• doc/project/50-requirements/requirements-003.md
• doc/project/40-proposals/012-learning-outcomes-and-archival-contracts.md

Project Lineage

Requirements

• doc/project/50-requirements/requirements-002.md
• doc/project/50-requirements/requirements-003.md
• doc/project/50-requirements/requirements-004.md
• doc/project/50-requirements/requirements-005.md

Stories

• doc/project/30-stories/story-001.md
• doc/project/30-stories/story-002.md
• doc/project/30-stories/story-003.md
• doc/project/30-stories/story-004.md

Fields

Field	Required	Shape	Description
schema/v	yes	const: 1	Schema version.
request/id	yes	string	Retrieval request identifier being answered.
responded-at	yes	string	Response timestamp.
responder/node-id	yes	string	Archivist or gateway node that answered the retrieval request.
status	yes	enum: found, denied, unavailable, tombstoned	Top-level retrieval result.
package/id	no	string	Archival package identifier returned on successful retrieval.
artifact/id	no	string	Artifact identifier returned on successful retrieval.
publication/scope	no	enum: private-retained, federation-vault, public-vault	Scope under which the returned artifact is exposed.
payload/ref	no	string	Stable content or blob reference returned to the requester.
integrity/proof	no	ref: #/$defs/integrityProof
reason/code	no	string	Short machine-readable reason for non-successful retrieval.
reason/text	no	string	Optional human-readable explanation of denial or unavailability.
expires-at	no	string	Optional expiry timestamp of the returned retrieval grant or link.
policy_annotations	no	object	Optional implementation-local annotations that do not change the core retrieval semantics.

Definitions

Definition	Shape	Description
integrityProof	object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "status": {
      "const": "found"
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "package/id",
    "artifact/id",
    "publication/scope",
    "payload/ref",
    "integrity/proof"
  ]
}

Rule 2

When:

{
  "properties": {
    "status": {
      "enum": [
        "denied",
        "unavailable",
        "tombstoned"
      ]
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "reason/code"
  ]
}

Field Semantics

schema/v

• Required: yes
• Shape: const: 1

Schema version.

request/id

• Required: yes
• Shape: string

Retrieval request identifier being answered.

responded-at

• Required: yes
• Shape: string

Response timestamp.

responder/node-id

• Required: yes
• Shape: string

Archivist or gateway node that answered the retrieval request.

status

• Required: yes
• Shape: enum: found, denied, unavailable, tombstoned

Top-level retrieval result.

package/id

• Required: no
• Shape: string

Archival package identifier returned on successful retrieval.

artifact/id

• Required: no
• Shape: string

Artifact identifier returned on successful retrieval.

publication/scope

• Required: no
• Shape: enum: private-retained, federation-vault, public-vault

Scope under which the returned artifact is exposed.

payload/ref

• Required: no
• Shape: string

Stable content or blob reference returned to the requester.

integrity/proof

• Required: no
• Shape: ref: #/$defs/integrityProof

reason/code

• Required: no
• Shape: string

Short machine-readable reason for non-successful retrieval.

reason/text

• Required: no
• Shape: string

Optional human-readable explanation of denial or unavailability.

expires-at

• Required: no
• Shape: string

Optional expiry timestamp of the returned retrieval grant or link.

policy_annotations

• Required: no
• Shape: object

Optional implementation-local annotations that do not change the core retrieval semantics.

Definition Semantics

$defs.integrityProof

• Shape: object