ZIP Structure — Package Format

Complete ZIP Layout

{packageName}-{version}.zip          ← File name convention
├── manifest.json                      ← REQUIRED — always at ZIP root
├── README.md                          ← REQUIRED — human-readable description
└── artifacts/                         ← REQUIRED — artifact container directory
    ├── workflows/                     ← Present if package contains workflows
    │   ├── {processId}.json           ← One file per ProcessDefinition
    │   └── {threadId}.json            ← One file per ThreadDefinition
    ├── forms/                         ← Present if package contains forms
    │   └── {formId}.json              ← One file per AtlasForm
    ├── rules/                         ← Present if package contains rule sets
    │   └── {ruleId}.json              ← One file per RuleSet
    ├── entities/                      ← Present if package contains entity schemas
    │   └── {entityId}.json            ← One file per EntitySchema
    └── apps/                          ← Present if package contains apps
        └── {appId}.json               ← One file per AppDefinition

File Naming Rules

Location	Naming Convention	Example
ZIP file name	`{name}-{version}.zip` (lowercase, hyphens)	`employee-onboarding-2.1.0.zip`
ProcessDefinition	`artifacts/workflows/{id}.json`	`artifacts/workflows/proc-1001.json`
ThreadDefinition	`artifacts/workflows/{id}.json`	`artifacts/workflows/thread-2002.json`
AtlasForm	`artifacts/forms/{id}.json`	`artifacts/forms/form-2005.json`
RuleSet	`artifacts/rules/{id}.json`	`artifacts/rules/rule-305.json`
EntitySchema	`artifacts/entities/{id}.json`	`artifacts/entities/ent-44.json`
AppDefinition	`artifacts/apps/{id}.json`	`artifacts/apps/app-88.json`

Required Files

The import engine validates the presence of these files before processing any content. Missing any of them results in immediate rejection:

manifest.json — must exist at the ZIP root (not in a subdirectory)
README.md — must exist at the ZIP root
Every file path listed in manifest.artifacts[].file must be present in the ZIP

Forbidden Content

The import engine rejects packages containing these patterns:

Files outside the artifacts/ directory (other than manifest.json and README.md)
Files in artifacts/ that are not declared in the manifest
Executable files (.exe, .dll, .sh, .bat, scripts) anywhere in the ZIP
Nested ZIP files or archives
Symbolic links or absolute paths
Files with path traversal patterns (../)

Path Traversal Prevention The import engine uses a safe ZIP extractor that rejects any entry whose resolved path falls outside the extraction directory. Path traversal via ../ or absolute paths causes immediate rejection and security scan failure.

File Encoding

All JSON files must be UTF-8 encoded (no BOM)
README.md must be UTF-8 encoded
JSON files must be valid JSON (the import engine uses strict parsing — trailing commas and comments are not permitted)

ZIP Compression

File	Compression	Reason
`manifest.json`	None (stored)	Fast access without decompressing the whole archive
Artifact JSON files	Deflate (Optimal)	JSON is highly compressible — typically 75% size reduction
`README.md`	Deflate (Optimal)	Text compresses well

Structure Validation Sequence

ZIP Integrity

Verify the ZIP is not corrupted (valid ZIP central directory).

manifest.json Presence

Confirm manifest.json exists at the root. Fail immediately if absent.

README.md Presence

Confirm README.md exists at the root.

Forbidden Content Scan

Scan all entry paths for forbidden patterns (executable extensions, path traversal, nested archives).

Artifact Manifest Cross-Reference

Verify every file in artifacts/ is declared in the manifest, and every manifest entry has a corresponding file in the ZIP.

← Overview Next: Manifest Schema →