# Zzup Manifest Format (.manifest.json)

## Overview

The Zzup manifest is a JSON file that must be included at the root of every Zzup-compatible OCI image. This manifest describes the image's properties, including the source directory containing files to be extracted, the recommended target directory, and metadata about the image.

## Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Zzup Manifest",
  "description": "Schema for Zzup-compatible OCI images",
  "type": "object",
  "required": ["schema", "name", "sourceDir"],
  "properties": {
    "schema": {
      "type": "string",
      "description": "Version of the manifest schema format, NOT the package version"
    },
    "name": {
      "type": "string",
      "description": "Name of the package"
    },
    "description": {
      "type": "string",
      "description": "Description of what the package provides"
    },
    "sourceDir": {
      "type": "string",
      "description": "Source directory inside the image containing files to extract"
    },
    "targetDir": {
      "type": "string",
      "description": "Recommended target directory (can be overridden in zzup.yaml)"
    },
    "author": {
      "type": "string",
      "description": "Author or maintainer of the package"
    },
    "homepage": {
      "type": "string",
      "description": "URL to package homepage or documentation"
    }
  }
}
```

## Example

```json
{
  "schema": "1.0",
  "name": "zondax-make",
  "description": "Zondax Make system utilities",
  "sourceDir": ".make",
  "targetDir": ".make",
  "author": "Zondax AG",
  "homepage": "https://zondax.ch"
}
```

## Implementation Notes

1. **Required Fields**:

   - `schema`: Schema version (currently 1.0) - this indicates the manifest schema format version, NOT the package version
   - `name`: Name of the package (should match the image name)
   - `sourceDir`: Path within the container to extract files from

2. **Optional Fields**:

   - `targetDir`: If not specified in the Zzup configuration or manifest, defaults to the image's name
   - `description`: Recommended for clarity
   - `author`, `homepage`: Metadata for documentation

3. **File Location**:
   The `.manifest.json` file must be placed at the root of the image filesystem.

## Error Handling

If a Zzup-compatible image does not contain a valid `.manifest.json` file at its root, the Zzup tool will report an error and refuse to install or update the image.

## Overriding Manifest Settings

Settings in the zzup.yaml configuration file override corresponding settings in the manifest. This allows for local customization while keeping the manifest as the baseline configuration.