Implementation:PrefectHQ Prefect Settings Schema

Knowledge Sources	PrefectHQ_Prefect Prefect Docs JSON Schema
Domains	Configuration, Settings, Schema_Validation
Last Updated	2026-02-09 22:00 GMT

Overview

JSON Schema definition documenting all Prefect settings with types, defaults, descriptions, and corresponding `PREFECT_*` environment variable names.

Description

The settings.schema.json file is the canonical reference for every configurable Prefect setting. It defines nested setting groups including APISettings (url, key, auth_string), ServerSettings (host, port, database), CLISettings, LoggingSettings, WorkerSettings, RunnerSettings, TasksSettings, and many more. Each property specifies its JSON type, default value, human-readable description, and the corresponding `PREFECT_*` environment variable via the `supported_environment_variables` annotation. This enables IDE validation, programmatic settings discovery, and documentation generation.

Usage

Reference this schema when configuring Prefect via settings files, when building tooling that needs to discover available settings, or when generating settings documentation. The schema is auto-generated by `scripts/generate_settings_schema.py`.

Code Reference

Source Location

• Repository: PrefectHQ_Prefect
• File: schemas/settings.schema.json
• Lines: 1-2928

Signature

{
    "$defs": {
        "APISettings": {
            "description": "Settings for interacting with the Prefect API",
            "properties": {
                "url": {
                    "type": ["string", "null"],
                    "default": null,
                    "description": "The URL of the Prefect API.",
                    "supported_environment_variables": ["PREFECT_API_URL"]
                },
                "key": {
                    "type": ["string", "null"],
                    "supported_environment_variables": ["PREFECT_API_KEY"]
                }
            }
        },
        "ServerSettings": { ... },
        "LoggingSettings": { ... },
        "CLISettings": { ... }
    }
}

Import

# Not importable; used for IDE validation and documentation generation
# Generated by:
python scripts/generate_settings_schema.py

I/O Contract

Inputs

Name	Type	Required	Description
$defs	object	Yes	Schema definitions for all setting groups
APISettings	object	Yes	API connection settings (url, key, auth_string)
ServerSettings	object	Yes	Server runtime settings (host, port, database URL)
LoggingSettings	object	Yes	Logging configuration (level, format, extra_loggers)
supported_environment_variables	array	No	PREFECT_* env var names mapped to each setting

Outputs

Name	Type	Description
Validation results	boolean	Whether a settings file conforms to the schema
Settings reference	documentation	Complete settings reference with env var mappings

Usage Examples

Discovering Settings via Environment Variables

# Common settings and their environment variables (from the schema):

# API connection
export PREFECT_API_URL="https://api.prefect.cloud/api/accounts/.../workspaces/..."
export PREFECT_API_KEY="pnu_..."

# Server configuration
export PREFECT_SERVER_API_HOST="0.0.0.0"
export PREFECT_SERVER_API_PORT="4200"

# Logging
export PREFECT_LOGGING_LEVEL="DEBUG"

# Results
export PREFECT_RESULTS_DEFAULT_SERIALIZER="json"

Programmatic Settings Access

from prefect.settings import get_current_settings

settings = get_current_settings()
print(settings.api.url)
print(settings.server.api.host)
print(settings.logging.level)

Related Pages

• Environment:PrefectHQ_Prefect_Python_Runtime_Environment