.config-schema.json

{
    "$schema": "https://json-schema.org/draft-07/schema",
    "$id": "https://raw.githubusercontent.com/openfga/openfga/refs/heads/main/.config-schema.json",
    "properties": {
        "maxTuplesPerWrite": {
            "description": "The maximum allowed number of tuples per Write transaction.",
            "type": "integer",
            "default": 100,
            "x-env-variable": "OPENFGA_MAX_TUPLES_PER_WRITE"
        },
        "maxTypesPerAuthorizationModel": {
            "description": "The maximum allowed number of type definitions per authorization model.",
            "type": "integer",
            "default": 100,
            "x-env-variable": "OPENFGA_MAX_TYPES_PER_AUTHORIZATION_MODEL"
        },
        "maxAuthorizationModelSizeInBytes": {
            "description": "The maximum size in bytes allowed for persisting an Authorization Model (default is 256KB).",
            "type": "integer",
            "default": 262144,
            "x-env-variable": "OPENFGA_MAX_AUTHORIZATION_MODEL_SIZE_IN_BYTES"
        },
        "maxConcurrentReadsForCheck": {
            "description": "The maximum allowed number of concurrent reads in a single Check query (default is MaxUint32).",
            "type": "integer",
            "default": 4294967295,
            "x-env-variable": "OPENFGA_MAX_CONCURRENT_READS_FOR_CHECK"
        },
        "maxConcurrentReadsForListObjects": {
            "description": "The maximum allowed number of concurrent reads in a single ListObjects query (default is MaxUint32).",
            "type": "integer",
            "default": 4294967295,
            "x-env-variable": "OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_OBJECTS"
        },
        "maxConcurrentReadsForListUsers": {
            "description": "The maximum allowed number of concurrent reads in a single ListUsers query (default is MaxUint32).",
            "type": "integer",
            "default": 4294967295,
            "x-env-variable": "OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_USERS"
        },
        "maxConcurrentChecksPerBatchCheck": {
            "description": "The maximum number of checks that can be processed concurrently in a batch check request.",
            "type": "integer",
            "default": 50,
            "x-env-variable": "OPENFGA_MAX_CONCURRENT_CHECKS_PER_BATCH_CHECK"
        },
        "maxChecksPerBatchCheck": {
            "description": "The maximum number of tuples allowed in a BatchCheck request.",
            "type": "integer",
            "default": 50,
            "x-env-variable": "OPENFGA_MAX_CHECKS_PER_BATCH_CHECK"
        },
        "maxConditionEvaluationCost": {
            "description": "The maximum cost for CEL condition evaluation before a request returns an error (default is 100).",
            "type": "integer",
            "default": 100,
            "x-env-variable": "OPENFGA_MAX_CONDITION_EVALUATION_COST"
        },
        "changelogHorizonOffset": {
            "description": "The offset (in minutes) from the current time. Changes that occur after this offset will not be included in the response of ReadChanges.",
            "type": "integer",
            "default": 0,
            "x-env-variable": "OPENFGA_CHANGELOG_HORIZON_OFFSET"
        },
        "resolveNodeLimit": {
            "description": "Maximum resolution depth to attempt before throwing an error (defines how deeply nested an authorization model can be before a query errors out).",
            "type": "integer",
            "default": 25,
            "x-env-variable": "OPENFGA_RESOLVE_NODE_LIMIT"
        },
        "resolveNodeBreadthLimit": {
            "description": "Defines how many nodes on a given level can be evaluated concurrently in a Check resolution tree.",
            "type": "integer",
            "default": 10,
            "x-env-variable": "OPENFGA_RESOLVE_NODE_BREADTH_LIMIT"
        },
        "listObjectsDeadline": {
            "description": "The timeout deadline for serving ListObjects requests",
            "type": "string",
            "format": "duration",
            "default": "3s",
            "x-env-variable": "OPENFGA_LIST_OBJECTS_DEADLINE"
        },
        "listObjectsMaxResults": {
            "description": "The maximum results to return in the non-streaming ListObjects API response. If 0, all results can be returned",
            "type": "integer",
            "minimum": 0,
            "default": 1000,
            "x-env-variable": "OPENFGA_LIST_OBJECTS_MAX_RESULTS"
        },
        "listObjectsPipelineEnabled": {
            "description": "Enables the ListObjects pipeline optimization algorithm, which can significantly improve the latency of ListObjects requests. When enabled, the server will attempt to resolve intermediate nodes in the ListObjects resolution tree concurrently. This optimization is most effective for workloads with large and complex authorization models, but may not suit all cases. Can be disabled if it causes increased resource usage.",
            "type": "boolean",
            "default": true,
            "x-env-variable": "OPENFGA_LIST_OBJECTS_PIPELINE_ENABLED"
        },
        "listUsersDeadline": {
            "description": "The timeout deadline for serving ListUsers requests. If 0s, there is no deadline",
            "type": "string",
            "format": "duration",
            "default": "3s",
            "x-env-variable": "OPENFGA_LIST_USERS_DEADLINE"
        },
        "listUsersMaxResults": {
            "description": "The maximum results to return in ListUsers API response. If 0, all results can be returned",
            "type": "integer",
            "minimum": 0,
            "default": 1000,
            "x-env-variable": "OPENFGA_LIST_USERS_MAX_RESULTS"
        },
        "readChangesMaxPageSize": {
            "description": "The maximum page size allowed for ReadChanges API requests",
            "type": "integer",
            "minimum": 1,
            "default": 100,
            "x-env-variable": "OPENFGA_READ_CHANGES_MAX_PAGE_SIZE"
        },
        "requestDurationDatastoreQueryCountBuckets": {
            "description": "Datastore query count buckets used to label the histogram metric for measuring request duration.",
            "type": "array",
            "items": {
                "minimum": 0,
                "type": "integer"
            },
            "minItems": 1,
            "default": [50, 200],
            "x-env-variable": "OPENFGA_REQUEST_DURATION_DATASTORE_QUERY_COUNT_BUCKETS"
        },
        "requestDurationDispatchCountBuckets": {
            "description": "Dispatch count buckets used to label the histogram metric for measuring request duration.",
            "type": "array",
            "items": {
                "minimum": 0,
                "type": "integer"
            },
            "minItems": 1,
            "default": [50, 200],
            "x-env-variable": "OPENFGA_REQUEST_DURATION_DISPATCH_COUNT_BUCKETS"
        },
        "contextPropagationToDatastore": {
            "description": "Propagate a requests context to the datastore implementation. Settings this parameter can result in connection pool draining on request aborts and timeouts.",
            "type": "boolean",
            "default": false,
            "x-env-variable": "OPENFGA_CONTEXT_PROPAGATION_TO_DATASTORE"
        },
        "experimentals": {
            "description": "a comma-separated list of experimental features to enable",
            "type": "array",
            "items": {
                "type": "string",
                "enum": ["enable-check-optimizations", "enable-list-objects-optimizations", "enable-access-control", "datastore_throttling", "pipeline_list_objects", "authzen"]
            },
            "default": ["pipeline_list_objects"],
            "x-env-variable": "OPENFGA_EXPERIMENTALS"
        },
        "authzen": {
            "type": "object",
            "properties": {
                "baseURL": {
                    "description": "The canonical absolute base URL published in AuthZEN discovery metadata. It may include an optional path prefix.",
                    "type": "string",
                    "default": "",
                    "x-env-variable": "OPENFGA_AUTHZEN_BASE_URL"
                }
            }
        },
        "accessControl": {
            "description": "the configuration needed for the access control store",
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "Enable/disable the access control store.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_ACCESS_CONTROL_ENABLED"
                },
                "storeId": {
                    "description": "The storeId to be used for the access control store.",
                    "type": "string",
                    "default": "",
                    "x-env-variable": "OPENFGA_ACCESS_CONTROL_STORE_ID"
                },
                "modelId": {
                    "description": "The modelId to be used for the access control store.",
                    "type": "string",
                    "default": "",
                    "x-env-variable": "OPENFGA_ACCESS_CONTROL_MODEL_ID"
                }
            }
        },
        "playground": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "Enable/disable the OpenFGA Playground. The Playground can only be run when the authentication method is set to 'none'. Note that the built-in Playground is intended for local development and testing purposes, and is not recommended for production use. It has been deprecated and will be removed in a subsequent release.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_PLAYGROUND_ENABLED"
                },
                "port": {
                    "description": "Deprecated: The port to serve the local OpenFGA Playground on. Use 'addr' instead.",
                    "type": "integer",
                    "default": 3000,
                    "deprecated": true,
                    "x-env-variable": "OPENFGA_PLAYGROUND_PORT"
                },
                "addr": {
                    "description": "The host:port address to serve the local OpenFGA Playground on.",
                    "type": "string",
                    "default": "",
                    "x-env-variable": "OPENFGA_PLAYGROUND_ADDR"
                }
            }
        },
        "profiler": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "Enabled/disable pprof profiling.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_PROFILER_ENABLED"
                },
                "addr": {
                    "description": "The host:port address to serve the pprof profiler server on.",
                    "type": "string",
                    "default": ":3001",
                    "x-env-variable": "OPENFGA_PROFILER_ADDR"
                }
            }
        },
        "datastore": {
            "type": "object",
            "properties": {
                "engine": {
                    "description": "The datastore engine that will be used for persistence.",
                    "type": "string",
                    "enum": ["memory", "postgres", "mysql", "sqlite"],
                    "default": "memory",
                    "x-env-variable": "OPENFGA_DATASTORE_ENGINE"
                },
                "uri": {
                    "description": "The connection uri to use to connect to the datastore (for any engine other than 'memory').",
                    "type": "string",
                    "examples": [
                        "postgres://user:pass@host:port/datastore?opts",
                        "user:pass@tcp(mysql-host:port)/datastore?parseTime=true&other-opts",
                        "file:/path/to/sqlite.db"
                    ],
                    "x-env-variable": "OPENFGA_DATASTORE_URI"
                },
                "secondaryUri": {
                    "description": "The connection uri to use to connect to the secondary datastore (for postgres only).",
                    "type": "string",
                    "examples": [
                        "postgres://user:pass@host:port/datastore?opts"
                    ],
                    "x-env-variable": "OPENFGA_DATASTORE_SECONDARY_URI"
                },
                "username": {
                    "description": "The connection username to connect to the datastore (overwrites any username provided in the connection uri).",
                    "type": "string",
                    "x-env-variable": "OPENFGA_DATASTORE_USERNAME"
                },
                "secondaryUsername": {
                    "description": "The connection username to connect to the secondary datastore (overwrites any username provided in the connection uri).",
                    "type": "string",
                    "x-env-variable": "OPENFGA_DATASTORE_SECONDARY_USERNAME"
                },
                "password": {
                    "description": "The connection password to connect to the datastore (overwrites any password provided in the connection uri).",
                    "type": "string",
                    "x-env-variable": "OPENFGA_DATASTORE_PASSWORD"
                },
                "secondaryPassword": {
                    "description": "The connection password to connect to the secondary datastore (overwrites any password provided in the connection uri).",
                    "type": "string",
                    "x-env-variable": "OPENFGA_DATASTORE_SECONDARY_PASSWORD"
                },
                "maxCacheSize": {
                    "description": "The maximum number of authorization models that will be cached in memory",
                    "type": "integer",
                    "default": 100000,
                    "x-env-variable": "OPENFGA_DATASTORE_MAX_CACHE_SIZE"
                },
                "maxTypesystemCacheSize": {
                    "description": "The maximum number of type system models that will be cached in memory",
                    "type": "integer",
                    "default": 100000,
                    "x-env-variable": "OPENFGA_DATASTORE_MAX_TYPESYSTEM_CACHE_SIZE"
                },
                "maxOpenConns": {
                    "description": "The maximum number of open connections to the datastore.",
                    "type": "integer",
                    "default": "30",
                    "x-env-variable": "OPENFGA_DATASTORE_MAX_OPEN_CONNS"
                },
                "minOpenConns": {
                    "description": "The minimum number of open connections to the datastore. This is only available for PostgreSQL.",
                    "type": "integer",
                    "default": "0",
                    "x-env-variable": "OPENFGA_DATASTORE_MIN_OPEN_CONNS"
                },
                "maxIdleConns": {
                    "description": "the maximum number of connections to the datastore in the idle connection pool.",
                    "type": "integer",
                    "default": "10",
                    "x-env-variable": "OPENFGA_DATASTORE_MAX_IDLE_CONNS"
                },
                "minIdleConns": {
                    "description": "the minimum number of connections to the datastore in the idle connection pool. This is only available for PostgreSQL.",
                    "type": "integer",
                    "default": "0",
                    "x-env-variable": "OPENFGA_DATASTORE_MIN_IDLE_CONNS"
                },
                "connMaxIdleTime": {
                    "description": "the maximum amount of time a connection to the datastore may be idle",
                    "type": "string",
                    "format": "duration",
                    "default": "0s",
                    "x-env-variable": "OPENFGA_DATASTORE_CONN_MAX_IDLE_TIME"
                },
                "connMaxLifetime": {
                    "description": "the maximum amount of time a connection to the datastore may be reused",
                    "type": "string",
                    "format": "duration",
                    "default": "0s",
                    "x-env-variable": "OPENFGA_DATASTORE_CONN_MAX_LIFETIME"
                },
                "metrics": {
                    "type": "object",
                    "properties": {
                        "enabled": {
                            "description": "enable/disable sql metrics for the datastore",
                            "type": "boolean",
                            "default": false,
                            "x-env-variable": "OPENFGA_DATASTORE_METRICS_ENABLED"
                        }
                    }
                }
            }
        },
        "authn": {
            "type": "object",
            "properties": {
                "method": {
                    "description": "The authentication method to use.",
                    "type": "string",
                    "enum": ["none", "preshared", "oidc"],
                    "default": "none",
                    "x-env-variable": "OPENFGA_AUTHN_METHOD"
                },
                "preshared": {
                    "description": "One or more preshared keys to use for authentication. This must be set if `authn.method=preshared'.",
                    "$ref": "#/definitions/preshared"
                },
                "oidc": {
                    "description": "The OIDC provider specific settings. This must be set if 'authn.method=oidc'.",
                    "$ref": "#/definitions/oidc"
                }

            }
        },
        "grpc": {
            "type": "object",
            "properties": {
                "addr": {
                    "description": "The host:port address to serve the grpc server on.",
                    "type": "string",
                    "default": "0.0.0.0:8081",
                    "x-env-variable": "OPENFGA_GRPC_ADDR"
                },
                "maxRecvMsgBytes": {
                    "description": "The maximum size, in bytes, of a received gRPC message.",
                    "type": "integer",
                    "default": 616448,
                    "minimum": 1,
                    "x-env-variable": "OPENFGA_GRPC_MAX_RECV_MSG_BYTES"
                },
                "tls": {
                    "type": "object",
                    "properties": {
                        "enabled": {
                            "description": "Enables or disables transport layer security (TLS).",
                            "type": "boolean",
                            "default": false,
                            "x-env-variable": "OPENFGA_GRPC_TLS_ENABLED"
                        },
                        "cert": {
                            "description": "The (absolute) file path of the certificate to use for the TLS connection.",
                            "type": "string",
                            "x-env-variable": "OPENFGA_GRPC_TLS_CERT"
                        },
                        "key": {
                            "description": "The (absolute) file path of the TLS key that should be used for the TLS connection.",
                            "type": "string",
                            "x-env-variable": "OPENFGA_GRPC_TLS_KEY"
                        }
                    },
                    "required": ["enabled", "cert", "key"]
                }
            }
        },
        "http": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "Enables or disables the OpenFGA HTTP server. If this is set to true then 'grpc.enabled' must be set to true.",
                    "type": "boolean",
                    "default": true,
                    "x-env-variable": "OPENFGA_HTTP_ENABLED"
                },
                "addr": {
                    "description": "The host:port address to serve the HTTP server on.",
                    "type": "string",
                    "default": "0.0.0.0:8080",
                    "x-env-variable": "OPENFGA_HTTP_ADDR"
                },
                "tls": {
                    "type": "object",
                    "properties": {
                        "enabled": {
                            "description": "Enables or disables transport layer security (TLS).",
                            "type": "boolean",
                            "default": false,
                            "x-env-variable": "OPENFGA_HTTP_TLS_ENABLED"
                        },
                        "cert": {
                            "description": "The (absolute) file path of the certificate to use for the TLS connection.",
                            "type": "string",
                            "x-env-variable": "OPENFGA_HTTP_TLS_CERT"
                        },
                        "key": {
                            "description": "The (absolute) file path of the TLS key that should be used for the TLS connection.",
                            "x-env-variable": "OPENFGA_HTTP_TLS_KEY"
                        }
                    },
                    "required": ["enabled", "cert", "key"]
                },
                "upstreamTimeout": {
                    "description": "The timeout duration for proxying HTTP requests upstream to the grpc endpoint.",
                    "type": "string",
                    "default": "3s",
                    "x-env-variable": "OPENFGA_HTTP_UPSTREAM_TIMEOUT"
                },
                "corsAllowedOrigins": {
                    "description": "List of allowed origins for CORS requests",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "default": ["*"],
                    "x-env-variable": "OPENFGA_HTTP_CORS_ALLOWED_ORIGINS"
                },
                "corsAllowedHeaders": {
                    "description": "List of allowed headers for CORS requests",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "default": ["*"],
                    "x-env-variable": "OPENFGA_HTTP_CORS_ALLOWED_HEADERS"
                }
            }
        },
        "log": {
            "type": "object",
            "properties": {
                "format": {
                    "description": "The log format to output logs in. For production we recommend 'json' format.",
                    "type": "string",
                    "enum": ["text", "json"],
                    "default": "text",
                    "x-env-variable": "OPENFGA_LOG_FORMAT"
                },
                "level": {
                    "description": "The log level to set. For production we recommend 'info' format.",
                    "type": "string",
                    "enum": ["none", "debug", "info", "warn", "error", "panic", "fatal"],
                    "default": "info",
                    "x-env-variable": "OPENFGA_LOG_LEVEL"
                },
                "timestampFormat": {
                    "description": "The timestamp format to use for the log output.",
                    "type": "string",
                    "enum": ["Unix", "ISO8601"],
                    "default": "Unix",
                    "x-env-variable": "OPENFGA_LOG_TIMESTAMP_FORMAT"
                }
            }
        },
        "trace": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "Enable tracing.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_TRACE_ENABLED"
                },
                "otlp": {
                    "type": "object",
                    "properties": {
                        "endpoint": {
                            "description": "The grpc endpoint of the trace collector",
                            "type": "string",
                            "default": "0.0.0.0:4317",
                            "x-env-variable": ["OPENFGA_TRACE_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT"]
                        },
                        "tls": {
                            "type": "object",
                            "properties": {
                                "enabled": {
                                    "description": "Whether to use TLS connection for the trace collector",
                                    "type": "boolean",
                                    "default": false,
                                    "x-env-variable": "OPENFGA_TRACE_OTLP_TLS_ENABLED"
                                }
                            }
                        }
                    }
                },
                "sampler": {
                    "description": "The sampler to use for tracing. Controls how sampling decisions are made. Defaults to 'traceidratio' for backward compatibility (note: the OpenTelemetry spec default is 'parentbased_always_on'). Unrecognized values produce a warning (when tracing is enabled) and fall back to 'traceidratio'.",
                    "type": "string",
                    "enum": ["always_on", "always_off", "traceidratio", "parentbased_always_on", "parentbased_always_off", "parentbased_traceidratio"],
                    "default": "traceidratio",
                    "x-env-variable": ["OPENFGA_TRACE_SAMPLER", "OTEL_TRACES_SAMPLER"]
                },
                "sampleRatio": {
                    "description": "The fraction of traces to sample. 1 means all, 0 means none.",
                    "type": "number",
                    "default": "0.2",
                    "x-env-variable": ["OPENFGA_TRACE_SAMPLE_RATIO", "OTEL_TRACES_SAMPLER_ARG"]
                },
                "serviceName": {
                    "description": "The service name included in sampled traces.",
                    "type": "string",
                    "default": "openfga",
                    "x-env-variable": ["OPENFGA_TRACE_SERVICE_NAME", "OTEL_SERVICE_NAME"]
                },
                "resourceAttributes": {
                    "description": "Key-value pairs to be used as resource attributes",
                    "type": "string",
                    "default": "",
                    "x-env-variable": "OTEL_RESOURCE_ATTRIBUTES"
                }
            }
        },
        "metrics": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable/disable prometheus metrics on the '/metrics' endpoint",
                    "type": "boolean",
                    "default": true,
                    "x-env-variable": "OPENFGA_METRICS_ENABLED"
                },
                "addr": {
                    "description": "the host:port address to serve the prometheus metrics server on",
                    "type": "string",
                    "default": "0.0.0.0:2112",
                    "x-env-variable": "OPENFGA_METRICS_ADDR"
                },
                "enableRPCHistograms": {
                    "description": "enables prometheus histogram metrics for RPC latency distributions",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_METRICS_ENABLE_RPC_HISTOGRAMS"
                }
            }
        },
        "checkCache": {
            "type": "object",
            "properties": {
                "limit": {
                    "description": "the size limit (in items) of the cache for Check (queries and iterators)",
                    "type": "integer",
                    "default": "10000",
                    "x-env-variable": "OPENFGA_CHECK_CACHE_LIMIT"
                }
            }
        },
        "checkIteratorCache": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable caching of datastore iterators. The key is a string representing a database query, and the value is a list of tuples. Each iterator is the result of a database query, for example usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator. If the request's consistency is HIGHER_CONSISTENCY, this cache is not used.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_CHECK_ITERATOR_CACHE_ENABLED"
                },
                "maxResults": {
                    "description": "if caching of datastore iterators of Check requests is enabled, this is the limit of tuples to cache per key",
                    "type": "integer",
                    "default": "10000",
                    "x-env-variable": "OPENFGA_CHECK_ITERATOR_CACHE_MAX_RESULTS"
                },
                "ttl": {
                    "description": "if caching of datastore iterators of Check requests is enabled, this is the TTL of each value",
                    "type": "string",
                    "format": "duration",
                    "default": "10s",
                    "x-env-variable": "OPENFGA_CHECK_ITERATOR_CACHE_TTL"
                }
            }
        },
        "checkQueryCache": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable caching of Check requests. The key is a string representing a query, and the value is a boolean. For example, if you have a relation `define viewer: owner or editor`, and the query is Check(user:anne, viewer, doc:1), we'll evaluate the `owner` relation and the `editor` relation and cache both results: (user:anne, viewer, doc:1) -> allowed=true and (user:anne, owner, doc:1) -> allowed=true. The cache is stored in-memory; the cached values are overwritten on every change in the result, and cleared after the configured TTL. This flag improves latency, but turns Check and ListObjects into eventually consistent APIs. If the request's consistency is HIGHER_CONSISTENCY, this cache is not used.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_ENABLED"
                },
                "limit": {
                    "description": "DEPRECATED use OPENFGA_CHECK_CACHE_LIMIT. If caching of Check and ListObjects calls is enabled, this is the size limit (in items) of the cache",
                    "type": "integer",
                    "default": "10000",
                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_LIMIT"
                },
                "ttl": {
                    "description": "if caching of Check and ListObjects is enabled, this is the TTL of each value",
                    "type": "string",
                    "format": "duration",
                    "default": "10s",
                    "x-env-variable": "OPENFGA_CHECK_QUERY_CACHE_TTL"
                }
            }
        },
        "cacheController": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable invalidation of check query cache and iterator cache based on recent tuple writes. Invalidation is triggered by Check and List Objects requests, which periodically check the datastore's changelog table for writes and invalidate cache entries earlier than recent writes. Invalidations from Check requests are rate-limited by cache-controller-ttl, whereas List Objects requests invalidate every time if list objects iterator cache is enabled.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_CACHE_CONTROLLER_ENABLED"
                },
                "ttl": {
                    "description": "if cache controller is enabled, this is the minimum time interval for Check requests to trigger cache invalidation. List Objects requests may trigger invalidation even sooner if list objects iterator cache is enabled.",
                    "type": "string",
                    "format": "duration",
                    "default": "10s",
                    "x-env-variable": "OPENFGA_CACHE_CONTROLLER_TTL"
                }
            }
        },
        "cacheTTLJitterPercentage": {
            "description": "A percentage (0-100) of the base TTL added as random jitter to each cache entry's TTL, spreading out expirations to prevent thundering herd effects. For example, a value of 10 with a base TTL of 10s means each entry gets a TTL between 10s and 11s.",
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 0,
            "x-env-variable": "OPENFGA_CACHE_TTL_JITTER_PERCENTAGE"
        },
        "checkDispatchThrottling": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable throttling when check request's number of dispatches is high",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_CHECK_DISPATCH_THROTTLING_ENABLED"
                },
                "frequency": {
                    "description": "the frequency period that the deprioritized throttling queue is evaluated for a check request. A higher value will result in more aggressive throttling",
                    "type": "string",
                    "format": "duration",
                    "default": "10µs",
                    "x-env-variable": "OPENFGA_CHECK_DISPATCH_THROTTLING_FREQUENCY"
                },
                "threshold": {
                    "description": "define the number of recursive operations to occur before getting throttled for a check request",
                    "type": "integer",
                    "default": "100",
                    "x-env-variable": "OPENFGA_CHECK_DISPATCH_THROTTLING_THRESHOLD"
                },
                "maxThreshold": {
                    "description": "define the maximum dispatch threshold beyond above which requests will be throttled. 0 will use the 'dispatchThrottling.threshold' value as maximum",
                    "type": "integer",
                    "default": "0",
                    "x-env-variable": "OPENFGA_CHECK_DISPATCH_THROTTLING_MAX_THRESHOLD"
                }
            }
        },
        "listObjectsIteratorCache": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable caching of datastore iterators in ListObjects. The key is a string representing a database query, and the value is a list of tuples. Each iterator is the result of a database query, for example usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator. If the request's consistency is HIGHER_CONSISTENCY, this cache is not used.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_ITERATOR_CACHE_ENABLED"
                },
                "maxResults": {
                    "description": "if caching of datastore iterators of ListObjects requests is enabled, this is the limit of tuples to cache per key",
                    "type": "integer",
                    "default": "10000",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_ITERATOR_CACHE_MAX_RESULTS"
                },
                "ttl": {
                    "description": "if caching of datastore iterators of ListObjects requests is enabled, this is the TTL of each value",
                    "type": "string",
                    "format": "duration",
                    "default": "10s",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_ITERATOR_CACHE_TTL"
                }
            }
        },
        "listObjectsDispatchThrottling": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable throttling when ListObjects request's number of dispatches is high. Only applies when pipeline is disabled.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_ENABLED"
                },
                "frequency": {
                    "description": "the frequency period that the deprioritized throttling queue is evaluated for a ListObjects request. A higher value will result in more aggressive throttling",
                    "type": "string",
                    "format": "duration",
                    "default": "10µs",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_FREQUENCY"
                },
                "threshold": {
                    "description": "define the number of recursive operations to occur before getting throttled for a ListObjects request",
                    "type": "integer",
                    "default": "100",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_THRESHOLD"
                },
                "maxThreshold": {
                    "description": "define the maximum dispatch threshold beyond above which requests will be throttled for a ListObjects request. 0 will use the 'dispatchThrottling.threshold' value as maximum",
                    "type": "integer",
                    "default": "0",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_MAX_THRESHOLD"
                }
            }
        },
        "listUsersDispatchThrottling": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enable throttling when list users request's number of dispatches is high",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_LIST_USERS_DISPATCH_THROTTLING_ENABLED"
                },
                "frequency": {
                    "description": "the frequency period that the deprioritized throttling queue is evaluated for a list users request. A higher value will result in more aggressive throttling",
                    "type": "string",
                    "format": "duration",
                    "default": "10µs",
                    "x-env-variable": "OPENFGA_LIST_USERS_DISPATCH_THROTTLING_FREQUENCY"
                },
                "threshold": {
                    "description": "define the number of recursive operations to occur before getting throttled for a list users request",
                    "type": "integer",
                    "default": "100",
                    "x-env-variable": "OPENFGA_LIST_USERS_DISPATCH_THROTTLING_THRESHOLD"
                },
                "maxThreshold": {
                    "description": "define the maximum dispatch threshold beyond above which requests will be throttled for a list users request. 0 will use the 'dispatchThrottling.threshold' value as maximum",
                    "type": "integer",
                    "default": "0",
                    "x-env-variable": "OPENFGA_LIST_USERS_DISPATCH_THROTTLING_MAX_THRESHOLD"
                }
            }
        },
        "checkDatastoreThrottle": {
            "type": "object",
            "properties": {
                "threshold": {
                    "description": "define the number of datastore requests allowed before being throttled. A value of 0 means throttling is disabled.",
                    "type": "integer",
                    "default": 0,
                    "x-env-variable": "OPENFGA_CHECK_DATASTORE_THROTTLE_THRESHOLD"
                },
                "duration": {
                    "description": "defines the time for which the datastore request will be suspended for being throttled.",
                    "type": "string",
                    "format": "duration",
                    "default": "0s",
                    "x-env-variable": "OPENFGA_CHECK_DATASTORE_THROTTLE_DURATION"
                }
            }
        },
        "listObjectsDatastoreThrottle": {
            "type": "object",
            "properties": {
                "threshold": {
                    "description": "define the number of datastore requests allowed before being throttled. A value of 0 means throttling is disabled.",
                    "type": "integer",
                    "default": 0,
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DATASTORE_THROTTLE_THRESHOLD"
                },
                "duration": {
                    "description": "defines the time for which the datastore request will be suspended for being throttled.",
                    "type": "string",
                    "format": "duration",
                    "default": "0s",
                    "x-env-variable": "OPENFGA_LIST_OBJECTS_DATASTORE_THROTTLE_DURATION"
                }
            }
        },
        "listUsersDatastoreThrottle": {
            "type": "object",
            "properties": {
                "threshold": {
                    "description": "define the number of datastore requests allowed before being throttled. A value of 0 means throttling is disabled.",
                    "type": "integer",
                    "default": 0,
                    "x-env-variable": "OPENFGA_LIST_USERS_DATASTORE_THROTTLE_THRESHOLD"
                },
                "duration": {
                    "description": "defines the time for which the datastore request will be suspended for being throttled.",
                    "type": "string",
                    "format": "duration",
                    "default": "0s",
                    "x-env-variable": "OPENFGA_LIST_USERS_DATASTORE_THROTTLE_DURATION"
                }
            }
        },
        "sharedIterator": {
            "type": "object",
            "properties": {
                "enabled": {
                    "description": "enabling sharing of datastore iterators with different consumers. Each iterator is the result of a database query, for example usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator.",
                    "type": "boolean",
                    "default": false,
                    "x-env-variable": "OPENFGA_SHARED_ITERATOR_ENABLED"
                },
                "limit": {
                    "description": "if shared-iterator-enabled is enabled, this is the limit of the number of iterators that can be shared.",
                    "type": "integer",
                    "default": 1000000,
                    "x-env-variable": "OPENFGA_SHARED_ITERATOR_LIMIT"
                }
            }
        },
        "requestTimeout": {
            "description": "The timeout duration for a request.",
            "type": "string",
            "format": "duration",
            "default": "3s",
            "x-env-variable": "OPENFGA_REQUEST_TIMEOUT"
        },
        "shutdownTimeout": {
            "description": "The timeout duration for a graceful shutdown.",
            "type": "string",
            "format": "duration",
            "default": "10s",
            "x-env-variable": "OPENFGA_SHUTDOWN_TIMEOUT"
        },
        "planner": {
            "type": "object",
            "properties": {
                "initialGuess": {
                    "description": "The initial guess for the planners estimation.",
                    "type": "string",
                    "format": "duration",
                    "default": "10ms",
                    "x-env-variable": "OPENFGA_PLANNER_INITIAL_GUESS"
                },
                "evictionThreshold": {
                    "description": "How long a planner key can be unused before being evicted.",
                    "format": "duration",
                    "default": "0",
                    "x-env-variable": "OPENFGA_PLANNER_EVICTION_THRESHOLD"
                },
                "cleanupInterval": {
                    "description": "How often the planner checks for stale keys.",
                    "type": "string",
                    "format": "duration",
                    "default": "0",
                    "x-env-variable": "OPENFGA_PLANNER_CLEANUP_INTERVAL"
                }
            }
        }
    },
    "definitions": {
        "oidc": {
            "type": "object",
            "properties": {
                "issuer": {
                    "description": "The OIDC issuer (authorization server) signing the tokens.",
                    "type": "string",
                    "x-env-variable": "OPENFGA_AUTHN_OIDC_ISSUER"
                },
                "audience": {
                    "description": "The OIDC audience of the tokens being signed by the authorization server.",
                    "type": "string",
                    "x-env-variable": "OPENFGA_AUTHN_OIDC_AUDIENCE"
                },
                "issuerAliases": {
                    "description": "the OIDC issuer DNS aliases that will be accepted as valid when verifying the `iss` field of the JWTs.",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "x-env-variable": "OPENFGA_AUTHN_OIDC_ISSUER_ALIASES"
                },
                "subjects": {
                    "description": "the OIDC subject names that will be accepted as valid when verifying the `sub` field of the JWTs. If empty, every `sub` will be allowed",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "x-env-variable": "OPENFGA_AUTHN_OIDC_SUBJECTS"
                },
                "clientIdClaims": {
                    "description": "the OIDC client id claims that will be used to parse the clientID - configure in order of priority (first is highest). Defaults to [`azp`, `client_id`]",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "x-env-variable": "OPENFGA_AUTHN_OIDC_CLIENT_ID_CLAIMS"
                }
            },
            "required": ["issuer", "audience"]
        },
        "preshared": {
            "type": "object",
            "properties": {
                "keys": {
                    "description": "List of preshared keys used for authentication",
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minItems": 1,
                    "x-env-variable": "OPENFGA_AUTHN_PRESHARED_KEYS"
                }
            },
            "required": ["keys"]
        }
    }
}