07 - Folder Variables

Purpose

Folder variables allow reusable values in request URLs without introducing cloud environment systems.

Primary use case:

• Replacing URL placeholders like {{baseUrl}} using local folder-scoped variable files.

Variable File Format

Variables are stored in folder config YAML files:

• .apifreeman-folder.yaml
• legacy read fallback: .anti-postman-folder.yaml

Document shape:

• schemaVersion: 1
• kind: folder
• variables: key/value array

See 12-file-format-reference for concrete examples.

Inheritance Model

Resolution is hierarchical:

1. Start at root folder config
2. Apply each nested ancestor folder config in path order
3. Child values override parent values for same key

Example:

• root defines baseUrl=https://api.prod
• nested folder defines baseUrl=https://api.staging
• requests in nested folder resolve to staging value

Resolution Timing

URL variable replacement occurs in Electron main process before sending request.

Functionally:

• If contextFolderPath exists and URL contains {{...}}, variables are resolved.
• If placeholder has no matching variable, placeholder text is left unchanged.

Placeholder Syntax

Supported placeholder pattern:

• {{variableName}}

Variable name character class in current regex:

• letters
• numbers
• underscore
• hyphen

Where Variables Come From

1. Manual folder variable writes (current internal flow)
2. Import pipeline writes (for example OpenAPI import writes baseUrl variable at collection folder)

Typical Usage Pattern

1. Organize requests under service folder.
2. Set folder variable baseUrl for that service.
3. Save URLs as {{baseUrl}}/path.
4. Switch value in one place for environment changes.

Limitations

• Variable interpolation currently applies to URL, not full request body/headers.
• No expression language or nested interpolation.
• No encrypted secret vault in current implementation.