Skip to content

Artifact Manifest

This document defines the canonical artifact manifest used within the Oryvin ecosystem.

The artifact manifest is the metadata record that describes an artifact produced by a workflow and published through DropBoxMini. It is used by producers such as Orchestrator, validated by DropBoxMini, and referenced by downstream systems that retrieve or process artifacts.

The purpose of the manifest is to make artifact meaning explicit. Consumers should not need to infer system ownership, version, or artifact content from filenames alone.

Purpose

The artifact manifest exists to support several goals:

  • define a canonical metadata structure for artifacts
  • allow producers to describe artifacts consistently
  • allow DropBoxMini to validate artifacts predictably
  • support traceability of artifact origin and purpose
  • make downstream retrieval and processing simpler

This document defines the initial manifest model used by the artifact contract.

Canonical manifest structure

A manifest is represented as a JSON document.

Example:

{
  "artifact_id": "20260315-001",
  "system": "weic",
  "type": "patch",
  "version": "0358",
  "producer": "orchestrator",
  "created_utc": "2026-03-15T15:30:00Z",
  "description": "WEIC patch delivery",
  "files": [
    {
      "path": "payload/weic_0358_patch.zip",
      "size": 183920
    }
  ]
}

Required fields

The following fields are required in the initial manifest model.

Field Type Purpose
artifact_id string unique artifact identifier
system string owning system such as weic, orchestrator, or infrastructure
type string artifact category such as patch, build, doc, or config
version string patch number, build identifier, or version label
producer string publishing system, typically orchestrator
created_utc string artifact creation timestamp in UTC
description string human-readable description
files array list of files included in the artifact

All required fields must be present for the manifest to be accepted.

File entries

The files array describes the payload files contained in the artifact bundle.

Example:

"files": [
  {
    "path": "payload/weic_0358_patch.zip",
    "size": 183920
  },
  {
    "path": "payload/release-notes.txt",
    "size": 4120
  }
]

Each file entry should include:

Field Type Purpose
path string relative path within the artifact bundle
size number file size in bytes

The file list allows consumers and validators to understand the contents of the artifact package.

Allowed artifact types

The initial manifest model supports a limited set of artifact categories.

Type Purpose
patch source changes, overlays, or code patch deliveries
build compiled application outputs
doc generated documentation or publication bundles
config configuration or deployment payloads

Additional types may be added later, but the initial schema should remain intentionally small.

Validation rules

The initial validation model should apply the following rules:

  • required fields must be present
  • artifact_id must be a non-empty string
  • system must be a non-empty string
  • type must be one of the allowed artifact categories
  • version must be a non-empty string
  • producer must be a non-empty string
  • created_utc must be a valid UTC timestamp
  • description must be a non-empty string
  • files must be present and contain at least one file entry
  • each file entry must contain a valid path
  • each file entry must contain a numeric size

The validation model is intentionally strict enough to make artifacts predictable while still remaining simple to implement.

Timestamp format

The created_utc value should use an ISO 8601 UTC timestamp.

Example:

2026-03-15T15:30:00Z

Using a single canonical timestamp format simplifies validation and comparison.

Artifact identifier guidance

The manifest requires a unique artifact_id.

Recommended initial pattern:

YYYYMMDD-NNN

Example:

20260315-001

Alternative identifier formats may be introduced later, but the initial model should remain simple and human-readable.

Version guidance

The version field identifies the artifact revision within the owning system.

Examples:

0358
20260315.1
v1.0.0

The exact version pattern may vary by system, but it must always be explicit and non-empty.

Optional future fields

Future versions of the manifest may include additional metadata such as:

Field Purpose
checksum payload integrity metadata
workflow_id producing workflow identifier
environment target or source environment
signature artifact signing metadata
channel release channel such as test or production

These are intentionally excluded from the initial required model so the contract can be implemented quickly.

Relationship to artifact packaging

The manifest describes the contents of an artifact bundle.

Typical bundle structure:

artifact.zip
├─ manifest.json
└─ payload/

The manifest should be included with the artifact so that validation and retrieval remain self-contained.

Responsibilities

Producers should

  • generate a valid manifest
  • ensure the manifest matches the payload
  • include all required metadata
  • use supported artifact types

DropBoxMini should

  • validate manifest structure
  • reject invalid manifests
  • use manifest metadata to determine storage behavior
  • expose stored artifacts predictably

This separation keeps manifest generation and manifest validation consistent across the platform.

Relationship to the Oryvin plan

The artifact manifest is a small but critical part of the broader Oryvin lifecycle.

Documented intent
        ↓
Workflow execution
        ↓
Artifact creation
        ↓
Manifest generation
        ↓
DropBoxMini validation and storage
        ↓
Target retrieval and consumption

Without a clear manifest, the artifact pipeline remains ambiguous. With it, the pipeline becomes implementable.