Variable Validation and Policy Help

Set Policies

Set policies determine when and how environment variables are applied during the build process:

force Force

Always overwrite existing environment value, regardless of what was set before.

immediate Immediate (Default)

Set the variable if it is currently unset (first-wins strategy). This is the default behavior.

lazy Lazy

Applied after all layers are processed (last-wins strategy). Useful for defaults that can be overridden.

skip Skip

Never set the variable. Useful for optional variables or when you want to disable a variable.

Policy Aliases:
true/yes/1/y → immediate
false/no/0/n → skip

Validation Types

Basic Types

bool - Must be: true/false, 1/0, yes/no, y/n (case insensitive)

capacity

capacity - Storage capacity in binary units (1024-based)
BINARY CAPACITY UNITS:
capacity must be specified with binary (1024-based) units for storage devices
8K / 8KiB (8 × 1024 bytes = 8,192 bytes)
128M / 128MiB (128 × 1024² bytes = 134,217,728 bytes)
4G / 4GiB (4 × 1024³ bytes = 4,294,967,296 bytes)
2T / 2TiB (2 × 1024⁴ bytes)
Supported units: K, M, G, T (short form)
KiB, MiB, GiB, TiB (explicit binary)
Rejected units: KB, MB, GB, TB (decimal 1000-based)
PLAIN NUMBERS (no suffix):
Accepted with requirements:
Minimum: 512 (typical sector size in bytes)
Binary alignment: must be 512, 1024, 2048, 4096, etc.
Examples:
512
4MiB
8G
This validator is designed for storage device capacity where binary
units align with filesystem blocks, sectors, and hardware reality.

value1,value2,value3

value1,value2,value3 - Must be one of the listed values
(Tip: For a single allowed value, either add a trailing comma
e.g. "syft," or use the keywords: prefix as shown below.)
Examples:
development,staging,production - Environment names
small,medium,large - Size options
debug,info,warn,error - Log levels
KEYWORDS:
keywords:word1,word2,word3 - Must be one of the listed alphanumeric keywords
Keywords can contain: letters (a-z, A-Z), numbers (0-9), underscore (_), hyphen (-)
Examples:
keywords:frontend,backend,database - Application components
keywords:cpu-intensive,io-bound - Workload types
keywords:dev,test,staging,prod - Environment shortcuts

int

int - Must be a valid integer
int:MIN-MAX - Integer within range (inclusive)
Examples:
int:1-100 - Integer from 1 to 100
int:1024-65535 - Port numbers
int:0-255 - Byte values

regex:PATTERN

regex:PATTERN - Must match regular expression
Examples:
regex:^[a-zA-Z0-9.-]+$ - Hostname format
regex:^[0-9]{3}-[0-9]{2}$ - Format like 123-45
regex:^(http|https):// - URLs starting with http/https

size

size - Size with optional unit (bytes, k/m/g/s) or percentage
SIZES:
size can be specified in one of the following formats
12345 (bytes)
20k / 20K (kilobytes, multiples of 1024)
128M / 128m (megabytes)
1G / 4g (gigabytes)
512s (sectors, multiples of 512)
50% (percentage; any positive integer)

string

string - Must be a non-empty string (required)
string-or-unset - Must be non-empty string or unset (null)
string-or-empty - Must be any string (may be empty) but not unset

Placeholders

Auto-substituted in variable values:

${FILENAME} - layer metadata file name
${DIRECTORY} - directory containing the file
${FILEPATH} - absolute path to the file
Escape with \${NAME} to keep the literal text.

Example Variable Definitions

# Port number validation
X-Env-Var-port-Valid: int:1024-65535

# Environment selection
X-Env-Var-env-Valid: development,staging,production

# Hostname validation
X-Env-Var-hostname-Valid: regex:^[a-zA-Z0-9.-]+$

# Boolean flag
X-Env-Var-debug-Valid: bool

# Component selection with keywords
X-Env-Var-component-Valid: keywords:frontend,backend,database