Pre-Export Validation — Export System

Validation Checks

Pre-export validation runs synchronously before any dependency resolution or serialization. If any check fails, the export is aborted with a 400 Bad Request response listing all failures (not just the first).

1. Request Validation

Check	Rule	Error Code
Package name	Required, 1–100 characters, no special characters except hyphens and spaces	`InvalidPackageName`
Package type	Must be one of the 5 valid enum values	`InvalidPackageType`
Version	Must be valid SemVer: `major.minor.patch`	`InvalidVersion`
Artifact IDs	Array must have at least 1 element, max 50 root artifact IDs per export	`ArtifactIdsMissing` / `TooManyRootArtifacts`
Tenant ID	Must be a valid, active tenant ID	`InvalidTenantId`

2. Authorization Validation

Check	Rule	Error Code
Permission scope	Caller must have `installhub:export` permission	`InsufficientPermission`
Tenant access	Caller must have access to the specified tenantId	`TenantAccessDenied`
Artifact ownership	All specified artifact IDs must belong to the caller's tenant	`TenantMismatch`

3. Artifact Existence Validation

Check	Rule	Error Code
Existence	All specified artifact IDs must exist in the tenant	`ArtifactNotFound`
Status	Artifacts must be in Published or Active state (not Draft, Archived, or Deleted)	`ArtifactNotExportable`
Completeness	Artifacts must not have dangling references (e.g., a workflow node pointing to a deleted form)	`IncompleteArtifact`

4. Dependency Graph Validation

Check	Rule	Error Code
Circular dependency	The artifact reference graph must be a DAG (no cycles)	`CircularDependency`
Cross-tenant references	No artifact may reference an artifact from a different tenant	`CrossTenantReference`
Dependency depth	Maximum dependency depth is 10 levels (prevents pathological graphs)	`DependencyDepthExceeded`
Total artifact count	Maximum 500 artifacts in a single bundle (including auto-resolved)	`BundleSizeExceeded`

5. Version Conflict Validation

Check	Rule	Error Code
Version uniqueness	A package with the same name + version must not already exist for this tenant	`VersionConflict`

Validation Error Response Format

HTTP 400 Bad Request
{
  "error": "ValidationFailed",
  "message": "Export request failed validation. See 'errors' for details.",
  "errors": [
    {
      "code":    "ArtifactNotFound",
      "field":   "artifactIds[0]",
      "message": "Artifact 'proc-9999' does not exist in tenant 'tenant-7f3a'"
    },
    {
      "code":    "InvalidVersion",
      "field":   "version",
      "message": "Version 'v2.1' is not valid SemVer. Expected format: major.minor.patch (e.g., 2.1.0)"
    }
  ]
}

Validation vs. Security Scanning

Pre-export validation checks that the export request is well-formed and the artifacts are complete. It is not a security scan. Security scanning (expression injection, CVE checks) runs separately on the bundle before import. See Guide 8: Security Scanning for details.

All Errors Returned at Once Validation does not stop at the first error — it runs all checks and returns all failures together. This allows you to fix all issues in one iteration rather than discovering them one by one.

Draft Artifacts Cannot Be Exported

Artifacts in Draft state cannot be exported. This prevents distributing incomplete or untested automation. Publish the artifact first, then run the export.

{
  "error": "ArtifactNotExportable",
  "message": "Artifact 'proc-1001' (EmployeeOnboarding) is in Draft state. Publish it before exporting.",
  "artifactId": "proc-1001",
  "currentStatus": "Draft",
  "requiredStatus": "Published"
}

← Export History