Comprehensive guide to schema definitions for typed validation, defaults, enums, and metadata in .envx files.

.envx Schema Syntax

The .envx schema section enables you to define metadata, validation rules, and typing for your environment variables. This elevates environment configurations from simple key-value pairs to strongly typed, validated, and self-documented declarations.

What is Schema?

Schema blocks appear after all variable assignments and use the following syntax:

[VARIABLE_NAME]
type = "string"       # Required type: string, number, boolean, enum, url, email
required = true       # Optional; if true, variable must be set or have a default
default = "value"     # Optional default fallback value
description = """     # Optional multiline documentation
Detailed description for this variable.
"""
values = ["a", "b"]   # Allowed values array, only valid for enum type
deprecated = false    # Optional flag to mark variable deprecated

Example Schema Block

[KEY]
type = "enum"
required = true
default = "dev"
values = ["dev", "prod"]
description = """  
Selects the environment mode.  
Allowed values are "dev" for development and "prod" for production.
"""

This example:

Enforces KEY to be one of "dev" or "prod".
Requires KEY to be present (or have the default "dev").
Provides helpful documentation for developers and editor tooling.

Supported Schema Properties

Property	Type	Description
`type`	string	Data type: `string`, `number`, `boolean`, `enum`, `url`, `email`.
`required`	boolean	If `true`, variable must be assigned or have a default value.
`default`	any	Default value if none provided.
`description`	string	Rich, multiline documentation, shown in editors and docs.
`values`	string array	List of allowed values (only for `enum` type).
`deprecated`	boolean	Flags variable as deprecated; tooling can warn about usage.

Detailed Property Explanation

`type`

Specifies the expected data type. Validation ensures assigned values match this type.

Examples:

[NODE_ENV]
type = "enum"
values = ["production", "development", "test"]
default = "development"
required = true

`required`

When true, the variable must be defined or have a default. Missing variables cause validation errors.

`default`

A fallback value if the variable is not explicitly set.

`description`

Supports triple-quoted multiline strings for detailed inline documentation.

`values`

Defines allowed strings for enum-typed variables.

`deprecated`

Marks the variable as deprecated, useful for notifying teams and preventing usage in new code.

Best Practices

Always place schema definitions after all variable assignments.
Use schema to document variables and improve developer experience.
Prefer enums for variables with limited valid options.
Set required for critical variables to enforce configuration completeness.
Use deprecated to gracefully phase out variables.

Complete Example

# Variable assignments
APP_ENV="production"
LOG_LEVEL="debug"

# Schema definitions
[APP_ENV]
type = "enum"
values = ["production", "development", "test"]
default = "development"
required = true
description = """
Defines the application environment mode.
"""

[LOG_LEVEL]
type = "string"
default = "info"
description = """
Sets the logging verbosity level.
"""

[FEATURE_FLAG]
type = "boolean"
default = false
description = """
Enables or disables the experimental feature.
"""

By leveraging .envx schema definitions, you enforce consistent, validated, and well-documented environment variables — reducing runtime errors and improving team collaboration.

Schema Reference