InstallHub
Package Validation
Before any artifact is touched, the import engine runs three layers of validation: ZIP structure, manifest schema, and checksum integrity. Any failure at this stage blocks the import.
Validation Layers
Layer 1 — ZIP Structure Validation
| Check | Failure |
|---|---|
| File is a valid ZIP archive | InvalidZip |
manifest.json exists at root | ManifestMissing |
README.md exists at root | ReadmeMissing |
| No forbidden file types (.exe, .dll, .sh, .bat) | ForbiddenContent |
| No path traversal patterns (../) | PathTraversalDetected |
| No nested ZIP files | NestedArchiveDetected |
| All artifact paths declared in manifest are present in ZIP | ArtifactFileMissing |
| No extra files in artifacts/ not declared in manifest | UndeclaredArtifact |
Layer 2 — Manifest Schema Validation
| Check | Failure |
|---|---|
manifestVersion is a supported value | UnsupportedManifestVersion |
| All required fields are present and non-empty | ManifestFieldMissing |
version is valid SemVer | InvalidVersion |
packageType is a valid enum value | InvalidPackageType |
exportedAt is a valid ISO 8601 datetime | InvalidDatetime |
artifacts array has at least 1 item | EmptyArtifactList |
installOrder contains all artifact IDs | IncompleteInstallOrder |
Every artifacts[].type is a valid artifact type | UnknownArtifactType |
Layer 3 — Checksum Integrity
| Check | Failure |
|---|---|
| Per-artifact hash matches each file's bytes | ArtifactHashMismatch |
| Bundle checksum matches all artifact bytes in install order | BundleChecksumMismatch |
Platform Version Check
After schema validation, the import engine compares the manifest's platformVersion to the target platform:
// manifest.platformVersion = "4.2.0"
// target platform = "4.1.5"
// Result: Warning (not blocking)
{
"warning": "PlatformVersionMismatch",
"message": "This package was created on platform 4.2.0 but the target is 4.1.5. Some features may not be available.",
"packagePlatformVersion": "4.2.0",
"targetPlatformVersion": "4.1.5"
}Package Dependency Check
The engine checks that every package listed in packageDependencies is installed in the target tenant at a compatible version. Missing or incompatible dependencies block the import:
{
"error": "MissingPackageDependency",
"missing": [
{ "packageName": "BizFirstGO.HRBase", "requiredMinVersion": "1.0.0", "installedVersion": null }
]
}Validation Error Format
HTTP 400 Bad Request
{
"error": "ValidationFailed",
"message": "Package validation failed. Fix the errors below and retry.",
"errors": [
{
"layer": "ZipStructure",
"code": "ArtifactFileMissing",
"message": "File 'artifacts/forms/form-2005.json' declared in manifest but not found in ZIP"
},
{
"layer": "ManifestSchema",
"code": "InvalidVersion",
"message": "version '2.1' is not valid SemVer — expected major.minor.patch"
}
]
}
All Errors Returned Together
The engine runs all validation layers before returning. You get a complete list of all issues at once rather than discovering them one by one.