Path policy

Path policies are a powerful feature for governing content within your Media Library. They allow you to apply specific rules and configurations at a folder level, ensuring that your assets are managed consistently and securely across different teams and use-cases.

Think of a path policy as a set of rules you can attach to any folder. Once attached, these rules automatically apply to all files and subfolders within it. This enables you to create a robust, scalable governance framework that adapts to your organization's needs, from enforcing metadata standards for product assets to protecting critical marketing banners from accidental changes.

You can create and manage path policies in the dashboard. Give the policy a name and description, configure the behavior of custom metadata fields, and optionally add custom JavaScript for the upload and validate functions.

To apply a path policy to a specific folder, either select the folder from the autocomplete menu on the path policy page, or right-click on any folder and select the policy name from the dropdown.

1. A folder can have only one path policy assigned at a time.
2. When a path policy is applied to a folder, it automatically cascades to all of its subfolders. The effective path policy for any folder is determined by the nearest parent folder that has a policy assigned.
3. If a folder is moved or deleted, the path policy becomes ineffective. You must reapply it to the new location.

Path policies allow you to solve common governance challenges by creating folder-level rules for your assets. You can enforce metadata standards, automate parts of the upload process, and protect critical assets from unintended changes.

Here are some of the key problems you can solve:

• Enforce consistent metadata across different teams: Different teams often have different metadata requirements. For example, your marketing team might need fields like campaign and target_audience, while your product team might need product_id and version. By assigning separate folders to each team, you can configure required fields, read-only status, and default values at the folder level instead of forcing one global rule.
• Standardize file uploads: Use the upload function to enforce naming conventions, restrict file types, prevent overwrites, set default statuses (like “draft”), or enable automated AI tagging and background removal during upload.
• Protect critical assets: Use the validate function to block modifications, deletions, or renaming of important files and folders.

Select the fields from the list, and for each field you can configure the following options:

• Required: The field must always be filled in.
• Read only: The field’s value is fixed and cannot be modified by users.
• Default value: A pre-filled value that is applied if no other value is provided.

These settings override the global configuration for custom metadata fields, giving you fine-grained, folder-level control. Custom metadata settings apply to files within the folder. They do not apply to folders themselves.

Only the custom metadata fields selected in the policy will be available for assets within the folder, both in the Media Library and through the API. If no fields are selected, it effectively disables custom metadata for that folder, and you won't be able to apply any custom metadata to assets within it.

The possibilities with path policies are almost limitless. For example, you can:

1. Automate transformations on upload — e.g., apply background removal, enable AI auto-tagging, or generate captions.
2. Restrict uploads to specific users based on their email addresses.
3. Protect AI tags by preventing specific tags from being removed.
4. Enforce version history so that file or folder copies always include previous versions.
5. Control asset movement by blocking files or folders from being moved or copied out of a specific location.
6. Require cache purging whenever files or folders are renamed.

Below are some practical examples with code snippets to show how you can implement path policies.

You can use the upload function to validate and modify upload requests before they are processed. This is perfect for enforcing organizational standards at the point of upload.

The following upload function ensures that all files uploaded to the assigned folder follow a strict product-id_variant-name.jpg pattern and are no larger than 5MB.

function handler(operation, payload, user) {
  // Enforce filename pattern: product-id_variant.jpg
  const validNameRegex = /^[a-z0-9-]+_[a-z0-9]+\.[a-z]{3,4}$/;
  if (!validNameRegex.test(payload.fileName)) {
    throw new Error(
      "Invalid filename. Must follow the pattern 'product-id_variant.ext'."
    );
  }

  // Restrict file type to JPEG/PNG and size to 5MB
  payload.checks = '"file.mime" IN ["image/jpeg","image/png"] && "file.size" <= 5242880';
  
  return payload;
}

You can automate content analysis and metadata generation by enabling AI-powered extensions during upload. The extensions parameter in the upload function allows you to apply features like auto-tagging and captioning.

The following upload function enables AWS Rekognition for auto-tagging, along with an AI-powered caption generator. This ensures that all assets uploaded to the folder are automatically tagged and described, saving manual effort and improving searchability.

function handler(operation, payload, user) {
  // AI-powered auto-tagging and description
  payload.extensions = JSON.stringify([
    {
      name: "aws-auto-tagging",
      maxTags: 10,
      minConfidence: 80,
    },
    {
      name: "ai-auto-description",
    },
  ]);

  return payload;
}

To protect existing files in a specific folder from being overwritten, you can disable overwriting and ensure a unique filename is always used for new uploads.

function handler(operation, payload, user) {
  payload.overwriteFile = "false";
  payload.useUniqueFileName = "true";
  return payload;
}

You can ensure all assets uploaded to a specific folder are initially unpublished or in a "draft" state. This is useful for content that requires review before going live.

function handler(operation, payload, user) {
  payload.isPublished = "false";
  return payload;
}

For large teams, protecting critical, live assets from accidental changes is vital. You can use the validate function to block potentially destructive operations like deletions or overwrites on specific assets or entire folders.

By applying a path policy to a folder containing critical assets (e.g., a /live-banners folder), you can prevent any modifications or deletions within that entire folder. The following validate function blocks any DeleteFile and UpdateFile operations, effectively making all assets within the folder read-only.

function handler(operation, payload, user) {
  if (operation === "DeleteFile" || operation === "UpdateFile") {
    throw new Error(
      "Files in this folder are protected and cannot be modified or deleted."
    );
  }
}

To maintain a strict folder and file structure, you can block rename operations.

function handler(operation, payload, user) {
  if (operation === "RenameFile" || operation === "RenameFolder") {
    throw new Error("Renaming files or folders is not allowed in this directory.");
  }
}

The upload function is a user-defined JavaScript function that runs before a file upload is executed. Use it to validate and/or modify the upload request body. Only the fields you modify are changed, everything else stays the same.

function handler(operation, payload, user) {
  // Validate and/or modify fields on payload (all values are strings)
  return payload; // return the (optionally) modified payload
}

• operation is always set to Upload.
• payload matches the Upload API request specification. All fields are available except the file buffer and the auth-related properties (token, expire, signature and publicKey). The folder field is read-only. Although payload is a JSON object, the Upload API uses multipart form data, so every value arrives as a string (including numbers, booleans, and nested JSON). If you modify any field, convert it back to a string before returning it.
• user is a JSON object with user details (userId, userName, userEmail) for dashboard uploads, and undefined for API-based uploads.

Checkout file upload related examples above to learn more.

The validate function is a user-defined JavaScript function that runs before any Media Library operation is performed. Use it to enforce rules by inspecting the request and throwing an error to reject invalid operations.

function handler(operation, payload, user) {
  // Inspect payload & operation
  // Throw an error to reject the request. No return value is needed.
  if (operation === 'DeleteFolder') {
      throw new Error("Folder deletion is not allowed under this policy.");
  }
}

• operation will be a string. Check the mapping below for all possible values.
• payload will be a valid JSON containing payload. It will vary based on the value of operation.
• user is a JSON object with user details (userId, userName, userEmail) for dashboard operations, and undefined for API-based operations.

The dashboard UI is built using public-facing DAM APIs. Every action in the dashboard maps to an API. The table below outlines each operation and the corresponding API, along with the payload schema.

{
  // ID of the file being updated
  fileId: string;
  // AI tag names to remove
  removeAITags?: string[];
  // Callback URL for async operations
  webhookUrl?: string;
  // Extension payloads. Check API ref
  extensions?: object[];
  // Full replacement list of tags
  tags?: string[];
  // "x,y,width,height"
  customCoordinates?: string;
  // Key–value map
  customMetadata?: { [k: string]: any };
  // New description
  description?: string;
  // Publication status. Check API ref
  publish?: object;
}

{
  // File ID to delete
  fileId: string;
}

{
  // Full path of the source file
  sourceFilePath: string;
  // Target folder path
  destinationPath: string;
  // Copy all versions
  includeFileVersions?: boolean;
}

{
  // Current full path of the file
  sourceFilePath: string;
  // Target folder path
  destinationPath: string;
}

{
  // Current full path of the file
  filePath: string;
  // New file name (without path)
  newFileName: string;
  // Purge cached variants
  purgeCache?: boolean;
}

{
  // File whose version will be deleted
  fileId: string;
  // Version ID to delete
  versionId: string;
}

{
  // File to restore a version for
  fileId: string;
  // Version ID to restore
  versionId: string;
}

{
  // Name of the new folder
  folderName: string;
  // Path where the folder will be created
  parentFolderPath: string;
}

{
  // Full path of the folder to delete
  folderPath: string;
}

{
  // Full path of the source folder
  sourceFolderPath: string;
  // Target parent path
  destinationPath: string;
  // Copy all file versions
  includeFileVersions?: boolean;
}

{
  // Current full path of the folder
  folderPath: string;
  // New folder name
  newFolderName: string;
  // Purge old assets cache
  purgeCache?: boolean;
}

{
  // Current full path of the folder
  sourceFolderPath: string;
  // Target parent path
  destinationPath: string;
}

{
  // File to tag
  fileId: string;
  // Tags to add
  tags: string[];
}

{
  // File to untag
  fileId: string;
  // Tags to remove
  tags: string[];
}

1. Runtime limits: Each function (Upload or Validate) must finish within 300 ms and use no more than 8 MB of memory. Exceeding either limit results in a 400 error.

2. Keep it simple: Functions cannot import external modules, make network requests, or perform other asynchronous operations. Only plain JavaScript logic is supported.

3. Syntax correctness: The JavaScript code inside the handler must be syntactically valid and follow the correct function signature. Invalid syntax or a mismatched signature will cause errors, blocking API calls and all operations on any folder where the policy is applied.

   ✅ Correct — The handler defines all required arguments (operation, payload, user) and is syntactically valid:

   Copy

    function handler(operation, payload, user) {
      // Your business logic
    }
   

   ❌ Incorrect — Missing an argument:

   Copy

   function handler(operation, payload) {
     if (!payload.fileName.contains("imagekit")) {
       // Your business logic
     }
   }
   

4. Error handling: If your function throws an error, the API responds with a 400 error containing the policy name and your error message. Whatever string you pass to new Error() becomes the message in the response.

   ✅ Correct

   Copy

   function handler(operation, payload, user) {
     if (!payload.fileName.contains("imagekit")) {
       throw new Error("I don't like this filename, change it.");
     }
   }
   

   ❌ Incorrect

   Copy

   function handler(operation, payload, user) {
     if (!payload.fileName.contains("imagekit")) {
       // Returning or console.log won't work
       return "I don't like this filename, change it.";
     }
   }
   

5. Single entry point: Each function type (Upload / Validate) must have exactly one top-level handler function. Multiple handlers are not supported.

6. Folder immutability in uploads: The payload.folder path cannot be modified within an Upload function.

7. Stringified upload body: All values in the payload of an Upload function are strings. If you modify a value, it must remain a string. Since the upload API uses multipart form data, every field is treated as a string.

8. Policy application: A folder can only have one policy. It cascades automatically to all subfolders, unless a subfolder has its own policy.

9. Metadata sync: If you update a global custom metadata field (e.g., change a dropdown list), you must manually update any path policies using that field to keep default values valid.

10. Field deletion: A custom metadata field cannot be deleted while it is referenced in any path policy.