Przejdź do treści

Retrieval Request v1

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

Machine-readable schema for scope-aware retrieval of archived artifacts.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema/v yes const: 1 Schema version.
request/id yes string Stable retrieval request identifier.
requested-at yes string Timestamp of the retrieval attempt.
requester/node-id yes string Node or gateway actor requesting access.
package/id no string Requested archival package identifier.
artifact/id no string Requested artifact identifier when package id is not known.
access/scope yes enum: private-retained, federation-vault, public-vault Scope under which the requester expects the retrieval to be authorized.
authorization/basis yes enum: local-owner, federation-policy, public-access, curator-review, audit Reason why the requester believes access is allowed.
retrieval/purpose yes enum: local-recovery, serving, curation, training, audit, replay Declared purpose of retrieval.
proof/context-ref no string Optional external proof or audit context reference.
policy_annotations no object Optional implementation-local annotations that do not change the core retrieval semantics.

Conditional Rules

Rule 1

When:

{
  "properties": {
    "access/scope": {
      "const": "private-retained"
    }
  },
  "required": [
    "access/scope"
  ]
}

Then:

{
  "properties": {
    "authorization/basis": {
      "enum": [
        "local-owner",
        "curator-review",
        "audit"
      ]
    }
  }
}

Field Semantics

schema/v

  • Required: yes
  • Shape: const: 1

Schema version.

request/id

  • Required: yes
  • Shape: string

Stable retrieval request identifier.

requested-at

  • Required: yes
  • Shape: string

Timestamp of the retrieval attempt.

requester/node-id

  • Required: yes
  • Shape: string

Node or gateway actor requesting access.

package/id

  • Required: no
  • Shape: string

Requested archival package identifier.

artifact/id

  • Required: no
  • Shape: string

Requested artifact identifier when package id is not known.

access/scope

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

Scope under which the requester expects the retrieval to be authorized.

authorization/basis

  • Required: yes
  • Shape: enum: local-owner, federation-policy, public-access, curator-review, audit

Reason why the requester believes access is allowed.

retrieval/purpose

  • Required: yes
  • Shape: enum: local-recovery, serving, curation, training, audit, replay

Declared purpose of retrieval.

proof/context-ref

  • Required: no
  • Shape: string

Optional external proof or audit context reference.

policy_annotations

  • Required: no
  • Shape: object

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