EN Reference Operation Models

Operations, SQL, endpoints and parameter fields

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

These tables were generated from the Pydantic models and JSON Schema at the pinned commit. Usage guides: SQL RPC, Python hooks.

“Required” means the field must be present in JSON; acceptance of null is a separate type rule. A Model() default creates that model using its documented defaults. Empty lists/objects are created separately for each instance. — means no default or no constraint for that column.

Cross-field validators apply in addition to the table: permission/public selection, URL/host safety, tenant/owner columns, cache/idempotency/transaction combinations, schema collisions and safe regex. JSON Schema validation alone does not replace forge validate. Unknown fields are rejected through extra="forbid".

OperationConfig

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	—
path	string | null	No	null	—
method	enum ["GET","POST","PUT","PATCH","DELETE"]	No	"POST"	—
database	string	No	"primary"	—
public	boolean	No	false	—
permission	string | null	No	null	—
transaction	boolean	No	true	—
input_schema	object | null	No	null	—
parameters	list[RequestParameterSpec]	No	[]	—
statements	list[SQLStatementConfig]	No	[]	—
allow_ddl	boolean	No	false	—
idempotency	boolean	No	false	—
idempotency_ttl_seconds	integer	No	86400	min=60; max=31536000
idempotency_cleanup_batch_size	integer	No	1000	min=10; max=50000
idempotency_max_response_bytes	integer	No	262144	min=1024; max=16777216
cache	OperationCacheConfig	No	OperationCacheConfig()	—
invalidate_resources	list[string]	No	[]	—
invalidate_operations	list[string]	No	[]	—
summary	string | null	No	null	—
description	string | null	No	null	—
tags	list[string]	No	[]	—
deprecated	boolean	No	false	—
background_hooks	list[string]	No	[]	—
dependencies	list[string]	No	[]	—

SQLStatementConfig

Field	Type	Required	Default	Schema constraints
sql	string	Yes	—	—
mode	enum ["execute","fetch_one","fetch_all","scalar"]	No	"execute"	—
params	object	No	{}	—
result_name	string | null	No	null	—
max_rows	integer	No	1000	min=1; max=100000
require_rowcount_min	integer | null	No	null	min=0
require_rowcount_max	integer | null	No	null	min=0

OperationCacheConfig

Field	Type	Required	Default	Schema constraints
enabled	boolean	No	false	—
ttl_seconds	integer	No	15	min=1
stale_ttl_seconds	integer | null	No	null	min=0
vary_by_principal	boolean	No	true	—

CustomEndpointConfig

Field	Type	Required	Default	Schema constraints
path	string	Yes	—	—
method	string	No	"GET"	—
public	boolean	No	false	—
permission	string | null	No	null	—
handler	string	Yes	—	—
summary	string | null	No	null	—
description	string | null	No	null	—
tags	list[string]	No	[]	—
deprecated	boolean	No	false	—
include_in_schema	boolean	No	true	—
input_schema	object | null	No	null	—
input_mode	enum ["json","form","text","bytes","none"]	No	"json"	—
parameters	list[RequestParameterSpec]	No	[]	—
dependencies	list[string]	No	[]	—
background_hooks	list[string]	No	[]	—
response	ResponseSpec	No	ResponseSpec()	—
openapi_extra	object | null	No	null	—

DependencySpec

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	—
callable	string	Yes	—	—
use_cache	boolean	No	true	—

RequestParameterSpec

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	—
location	enum ["query","header","cookie","path"]	No	"query"	—
type	enum ["string","integer","number","boolean"]	No	"string"	—
required	boolean	No	false	—
default	Any	No	null	—
description	string | null	No	null	—
enum	list[Any] | null	No	null	—
minimum	number | null	No	null	—
maximum	number | null	No	null	—
min_length	integer | null	No	null	min=0
max_length	integer | null	No	null	min=0
pattern	string | null	No	null	—

ResponseSpec

Field	Type	Required	Default	Schema constraints
kind	enum ["json","text","html","redirect","stream","file","empty"]	No	"json"	—
media_type	string | null	No	null	—
headers	dict[str, string]	No	{}	—
filename	string | null	No	null	—
status_code	integer | null	No	null	—

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/config.py
• main/schemas/project.schema.json
• main/framework/validation.py

---

English home · All English pages · Version maintenance