Release and application schemas

Use run402 up --check for local validation and run402 up --plan for gateway planning. Schema checks cannot prove authorization, capacity or activation. These tables describe authoring JSON; SDK types can use different casing.

Run402 ReleaseSpec v1

Download schema. Authoring schema for Run402 deploy manifests. Use run402 up for complete application workflows. Project selection may be supplied by an explicit CLI target, app-local link or approved –name creation; the SDK requires a resolved project before gateway planning. SDK-native ReleaseSpec uses project; CLI/MCP manifests may use project_id.

root

Property	Shape	Required	Description
`$schema`	`string`	no	Editor metadata only. Manifest adapters strip this before deploy planning.
`x-run402-omitted_features`	`array`	no	App-kit evidence metadata for humans/agents. Manifest adapters preserve it in the loaded manifest and strip it before deploy planning.
`project`	`string`	no	SDK-native project id.
`project_id`	`string`	no	CLI/MCP-friendly project id, normalized to ReleaseSpec.project.
`idempotency_key`	`string`	no	See the downloadable schema for constraints.
`idempotencyKey`	`string`	no	See the downloadable schema for constraints.
`base`	`#/$defs/base`	no	See the downloadable schema for constraints.
`database`	`#/$defs/database`	no	See the downloadable schema for constraints.
`secrets`	`#/$defs/secrets`	no	See the downloadable schema for constraints.
`functions`	`#/$defs/functions`	no	See the downloadable schema for constraints.
`site`	`#/$defs/site`	no	See the downloadable schema for constraints.
`assets`	`#/$defs/assets`	no	See the downloadable schema for constraints.
`subdomains`	`#/$defs/subdomains`	no	See the downloadable schema for constraints.
`routes`	`oneOf`	no	See the downloadable schema for constraints.
`checks`	`array`	no	See the downloadable schema for constraints.
`i18n`	`oneOf`	no	See the downloadable schema for constraints.
`verify`	`#/$defs/verify`	no	Authoring-only post-apply HTTP verification, run by `run402 up` after a successful apply and rerunnable with `run402 up verify`. Stripped before deploy planning (never part of the wire ReleaseSpec).

base

{
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "release"
      ],
      "properties": {
        "release": {
          "enum": [
            "current",
            "empty"
          ]
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "release_id"
      ],
      "properties": {
        "release_id": {
          "type": "string"
        }
      }
    }
  ]
}

database

Property	Shape	Required	Description
`migrations`	`array`	no	See the downloadable schema for constraints.
`expose`	`object`	no	Authorization/expose manifest. See https://run402.com/schemas/manifest.v1.json for its schema.
`zero_downtime`	`boolean`	no	See the downloadable schema for constraints.

migration

Property	Shape	Required	Description
`id`	`string`	no	Versioned immutable migration id, e.g. 001_init. Same id plus same checksum noops; same id plus different SQL is MIGRATION_CHECKSUM_MISMATCH. Use name instead for generated/idempotent SQL whose identity should track content changes.
`name`	`string`	no	Content-tracked migration name for generated/idempotent SQL. The SDK compiles this to _<sha256(sql)[0:16]>; changed content applies once under a new id and identical re-deploys noop. SQL declared with name MUST be idempotent because it re-runs whenever content changes against a database where prior versions may already exist.
`checksum`	`string`	no	See the downloadable schema for constraints.
`sql`	`string`	no	See the downloadable schema for constraints.
`sql_ref`	`#/$defs/contentRef`	no	See the downloadable schema for constraints.
`sql_path`	`string`	no	See the downloadable schema for constraints.
`sql_file`	`string`	no	See the downloadable schema for constraints.
`transaction`	`schema`	no	See the downloadable schema for constraints.

secrets

Property	Shape	Required	Description
`require`	`array`	no	See the downloadable schema for constraints.
`delete`	`array`	no	See the downloadable schema for constraints.

functions

Property	Shape	Required	Description
`replace`	`object`	no	See the downloadable schema for constraints.
`patch`	`object`	no	See the downloadable schema for constraints.

functionSpec

Property	Shape	Required	Description
`runtime`	`schema`	no	See the downloadable schema for constraints.
`source`	`#/$defs/fileEntry`	no	See the downloadable schema for constraints.
`files`	`#/$defs/fileSet`	no	See the downloadable schema for constraints.
`entrypoint`	`string`	no	See the downloadable schema for constraints.
`config`	`object`	no	See the downloadable schema for constraints.
`schedule`	`oneOf`	no	See the downloadable schema for constraints.
`deps`	`array`	no	See the downloadable schema for constraints.
`triggers`	`array`	no	See the downloadable schema for constraints.
`requireAuth`	`boolean`	no	See the downloadable schema for constraints.
`require_auth`	`boolean`	no	See the downloadable schema for constraints.
`requireRole`	`oneOf`	no	See the downloadable schema for constraints.
`require_role`	`oneOf`	no	See the downloadable schema for constraints.
`class`	`schema`	no	See the downloadable schema for constraints.
`capabilities`	`array`	no	See the downloadable schema for constraints.

functionTrigger

Property	Shape	Required	Description
`id`	`string`	yes	See the downloadable schema for constraints.
`type`	`string`	yes	See the downloadable schema for constraints.

functionRequireRole

Property	Shape	Required	Description
`table`	`string`	yes	See the downloadable schema for constraints.
`id_column`	`string`	yes	See the downloadable schema for constraints.
`role_column`	`string`	yes	See the downloadable schema for constraints.
`allowed`	`array`	yes	See the downloadable schema for constraints.
`cache_ttl`	`integer`	no	See the downloadable schema for constraints.
`on_deny`	`schema`	no	See the downloadable schema for constraints.
`sign_in_path`	`string`	no	See the downloadable schema for constraints.

site

{
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "replace"
      ],
      "properties": {
        "replace": {
          "oneOf": [
            {
              "$ref": "#/$defs/fileSet"
            },
            {
              "$ref": "#/$defs/localDirRef"
            }
          ]
        },
        "public_paths": {
          "$ref": "#/$defs/sitePublicPaths"
        },
        "embedding": {
          "$ref": "#/$defs/siteEmbedding"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "patch"
      ],
      "properties": {
        "patch": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "put": {
              "oneOf": [
                {
                  "$ref": "#/$defs/fileSet"
                },
                {
                  "$ref": "#/$defs/localDirRef"
                }
              ]
            },
            "delete": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "public_paths": {
          "$ref": "#/$defs/sitePublicPaths"
        },
        "embedding": {
          "$ref": "#/$defs/siteEmbedding"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "public_paths": {
          "$ref": "#/$defs/sitePublicPaths"
        },
        "embedding": {
          "$ref": "#/$defs/siteEmbedding"
        }
      },
      "anyOf": [
        {
          "required": [
            "public_paths"
          ]
        },
        {
          "required": [
            "embedding"
          ]
        }
      ]
    }
  ]
}

sitePublicPaths

{
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode"
      ],
      "properties": {
        "mode": {
          "const": "implicit"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode",
        "replace"
      ],
      "properties": {
        "mode": {
          "const": "explicit"
        },
        "replace": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/publicStaticPath"
          }
        }
      }
    }
  ]
}

publicStaticPath

Property	Shape	Required	Description
`asset`	`string`	yes	Release static asset path, not a public URL.
`cache_class`	`#/$defs/staticCacheClass`	no	See the downloadable schema for constraints.

staticCacheClass

{
  "type": "string",
  "description": "Known values: html, immutable_versioned, revalidating_asset. Unknown future strings may be returned by observability APIs and should be preserved."
}

subdomains

Property	Shape	Required	Description
`set`	`array`	no	See the downloadable schema for constraints.
`add`	`array`	no	See the downloadable schema for constraints.
`remove`	`array`	no	See the downloadable schema for constraints.

routes

Property	Shape	Required	Description
`replace`	`array`	yes	See the downloadable schema for constraints.

route

Property	Shape	Required	Description
`pattern`	`string`	yes	See the downloadable schema for constraints.
`methods`	`array`	no	See the downloadable schema for constraints.
`target`	`oneOf`	yes	See the downloadable schema for constraints.
`pricing`	`#/$defs/routePricing`	no	See the downloadable schema for constraints.
`acknowledge_readonly`	`schema`	no	Durable acknowledgement for intentional read-only final-wildcard function routes. Valid only when target.type is function, pattern ends in /*, and methods are limited to GET/HEAD.

routePricing

Property	Shape	Required	Description
`mode`	`schema`	yes	See the downloadable schema for constraints.
`amount_usd_micros`	`integer`	yes	See the downloadable schema for constraints.
`pay_to`	`schema`	yes	See the downloadable schema for constraints.
`networks`	`array`	no	Omit to accept production mainnet only. Include testnet explicitly for testnet payments.

functionRouteTarget

Property	Shape	Required	Description
`type`	`schema`	yes	See the downloadable schema for constraints.
`name`	`string`	yes	See the downloadable schema for constraints.

staticRouteTarget

Property	Shape	Required	Description
`type`	`schema`	yes	See the downloadable schema for constraints.
`file`	`string`	yes	Relative materialized release static asset path, not a public path.

smokeCheck

{
  "type": "object",
  "additionalProperties": true
}

i18n

Property	Shape	Required	Description
`defaultLocale`	`string`	yes	Default locale tag. MUST be byte-identical to one entry in locales[].
`locales`	`array`	yes	Supported locale tags. Non-empty, max 50 entries. Tags are opaque — only the safety regex is enforced (no BCP-47 semantic validation).
`detect`	`array`	no	Walked in order; first match wins. Defaults to [‘accept-language’] when omitted, max 10 entries; [] is allowed and means ‘always default’. Sources: ‘accept-language’ and ‘cookie:’ (RFC 6265 cookie-name grammar).
`unknownLocalePolicy`	`string`	no	What to do when a detect-source signal does not match locales[]. ‘reject’ (default, backwards-compatible) falls through to the next detect source then to defaultLocale. ‘pass-through’ returns the lowercased, trimmed signal value verbatim — letting the consumer’s app DB decide whether translations exist for the tag. Capability i18n-unknown-locale-policy (issue #413).

fileSet

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/$defs/fileEntry"
  }
}

localDirRef

Property	Shape	Required	Description
`__source`	`schema`	yes	See the downloadable schema for constraints.
`path`	`string`	yes	Local directory path resolved by the SDK/CLI from the manifest directory and stripped before the apply request.

fileEntry

{
  "oneOf": [
    {
      "type": "string"
    },
    {
      "$ref": "#/$defs/contentRef"
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path"
      ],
      "properties": {
        "path": {
          "type": "string"
        },
        "content_type": {
          "type": "string"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "data"
      ],
      "properties": {
        "data": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "$ref": "#/$defs/contentRef"
            }
          ]
        },
        "encoding": {
          "enum": [
            "utf-8",
            "base64"
          ]
        },
        "content_type": {
          "type": "string"
        }
      }
    }
  ]
}

contentRef

Property	Shape	Required	Description
`sha256`	`string`	yes	See the downloadable schema for constraints.
`size`	`integer`	yes	See the downloadable schema for constraints.
`content_type`	`string`	no	See the downloadable schema for constraints.
`contentType`	`string`	no	Legacy SDK ContentRef spelling accepted by the normalizer; prefer content_type in manifests.
`integrity`	`string`	no	See the downloadable schema for constraints.

assets

Property	Shape	Required	Description
`put`	`array`	no	See the downloadable schema for constraints.
`delete`	`array`	no	Asset keys to remove at activation.
`sync`	`#/$defs/assetSync`	no	See the downloadable schema for constraints.

assetPutEntry

Property	Shape	Required	Description
`key`	`string`	yes	Asset key under the project’s asset namespace (no leading slash).
`source`	`#/$defs/fileEntry`	no	SDK-input form. Mutually exclusive with sha256/size_bytes; the SDK normalizer hashes + uploads via /content/v1/plans.
`sha256`	`string`	no	Pre-uploaded CAS reference (wire form). Mutually exclusive with source.
`size_bytes`	`integer`	no	Required when using the wire form (sha256 set).
`content_type`	`string`	no	See the downloadable schema for constraints.
`visibility`	`schema`	no	See the downloadable schema for constraints.
`immutable`	`boolean`	no	See the downloadable schema for constraints.

assetSync

Property	Shape	Required	Description
`prefix`	`string`	yes	Prefix under which destructive sync operates.
`prune`	`schema`	yes	See the downloadable schema for constraints.
`confirm`	`object`	no	Confirmation token echoed back from a prior plan; required to commit a destructive sync.

verify

Property	Shape	Required	Description
`http`	`array`	no	See the downloadable schema for constraints.

verifyHttpCheck

Property	Shape	Required	Description
`id`	`string`	yes	See the downloadable schema for constraints.
`path`	`string`	no	Request path resolved against the project public origin.
`url`	`string`	no	See the downloadable schema for constraints.
`expect`	`object`	no	See the downloadable schema for constraints.
`expected_status`	`integer`	no	Snake-case alias for expect.status.
`retries`	`integer`	no	See the downloadable schema for constraints.

siteEmbedding

{
  "description": "Framing opt-in using platform catalog keys, never origins. Remote validation checks the current catalog. Null resets to deny; omission carries prior state.",
  "oneOf": [
    {
      "type": "null"
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "frame_ancestors"
      ],
      "properties": {
        "frame_ancestors": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_-]*$"
          }
        }
      }
    }
  ]
}

Run402AppSpec

Download schema. Canonical run402.json app installation manifest consumed by run402 up.

root

Property	Shape	Required	Description
`$schema`	`schema`	yes	See the downloadable schema for constraints.
`spec_version`	`schema`	yes	See the downloadable schema for constraints.
`app`	`object`	yes	See the downloadable schema for constraints.
`project`	`object`	yes	See the downloadable schema for constraints.
`resources`	`object`	no	See the downloadable schema for constraints.
`secrets`	`object`	no	See the downloadable schema for constraints.
`build`	`object`	no	See the downloadable schema for constraints.
`release`	`object`	yes	Release node content. Project selection, build, resources, secret source metadata, lifecycle, and verify stay in the app install graph.
`lifecycle`	`object`	no	See the downloadable schema for constraints.
`verify`	`object`	no	See the downloadable schema for constraints.

logicalName

{
  "type": "string",
  "pattern": "^[a-z][a-z0-9_]*$"
}

mailbox

Property	Shape	Required	Description
`slug`	`string`	no	See the downloadable schema for constraints.
`roles`	`array`	no	See the downloadable schema for constraints.
`description`	`string`	no	See the downloadable schema for constraints.

webhook

Property	Shape	Required	Description
`mailbox`	`#/$defs/logicalName`	yes	See the downloadable schema for constraints.
`url`	`string`	yes	See the downloadable schema for constraints.
`events`	`array`	yes	See the downloadable schema for constraints.
`enabled`	`boolean`	no	See the downloadable schema for constraints.
`signing`	`object`	no	See the downloadable schema for constraints.

userSecret

Property	Shape	Required	Description
`required`	`boolean`	no	See the downloadable schema for constraints.
`source_env`	`string`	no	See the downloadable schema for constraints.
`description`	`string`	no	See the downloadable schema for constraints.

buildCommand

Property	Shape	Required	Description
`id`	`string`	yes	See the downloadable schema for constraints.
`argv`	`array`	no	See the downloadable schema for constraints.
`shell`	`string`	no	See the downloadable schema for constraints.
`cwd`	`string`	no	See the downloadable schema for constraints.

releaseDatabase

Property	Shape	Required	Description
`migrations`	`array`	no	See the downloadable schema for constraints.
`expose`	`schema`	no	See the downloadable schema for constraints.
`zero_downtime`	`boolean`	no	See the downloadable schema for constraints.

migration

Property	Shape	Required	Description
`id`	`string`	no	Versioned immutable migration id, e.g. 001_init. Same id plus same checksum noops; same id plus different SQL is MIGRATION_CHECKSUM_MISMATCH. Use name instead for generated/idempotent SQL whose identity should track content changes.
`name`	`string`	no	Content-tracked migration name for generated/idempotent SQL. The SDK compiles this to _<sha256(sql)[0:16]>; changed content applies once under a new id and identical re-deploys noop. SQL declared with name MUST be idempotent because it re-runs whenever content changes against a database where prior versions may already exist.
`checksum`	`string`	no	See the downloadable schema for constraints.
`sql`	`string`	no	See the downloadable schema for constraints.
`sql_ref`	`#/$defs/contentRef`	no	See the downloadable schema for constraints.
`sql_path`	`string`	no	See the downloadable schema for constraints.
`sql_file`	`string`	no	See the downloadable schema for constraints.
`transaction`	`schema`	no	See the downloadable schema for constraints.

contentRef

Property	Shape	Required	Description
`sha256`	`string`	yes	See the downloadable schema for constraints.
`size`	`integer`	yes	See the downloadable schema for constraints.
`contentType`	`string`	no	See the downloadable schema for constraints.
`integrity`	`string`	no	See the downloadable schema for constraints.

httpVerify

Property	Shape	Required	Description
`id`	`string`	yes	See the downloadable schema for constraints.
`path`	`string`	no	See the downloadable schema for constraints.
`url`	`string`	no	See the downloadable schema for constraints.
`expect`	`object`	yes	See the downloadable schema for constraints.
`retries`	`integer`	no	See the downloadable schema for constraints.

Run402 Manifest v1

Download schema. Declarative authorization contract for a Run402 project. Describes tables, views and RPCs reachable through PostgREST and their RLS policy templates. Author under database.expose in a release manifest and deploy with run402 up; direct HTTP integrations use POST /projects/v1/admin/:id/expose.

root

Property	Shape	Required	Description
`$schema`	`string`	no	Optional schema URL for editor tooling. Ignored at apply time.
`version`	`schema`	yes	Manifest schema version. Must be “1” for this schema.
`tables`	`array`	no	Tables reachable via /rest/v1/*. Entries with expose:false are documentation-only.
`views`	`array`	no	Security-invoker views projecting columns from a base table.
`rpcs`	`array`	no	Postgres functions callable via /rest/v1/rpc/*, with explicit EXECUTE grants.

identifier

{
  "type": "string",
  "pattern": "^[a-z_][a-z0-9_]{0,62}$",
  "description": "Lowercase SQL identifier: [a-z_] followed by up to 62 of [a-z0-9_]."
}

role

{
  "type": "string",
  "pattern": "^[a-z_][a-z0-9_]{0,62}$",
  "description": "Postgres role name. Expected values: anon, authenticated, service_role, project_admin."
}

columnOrStar

{
  "oneOf": [
    {
      "$ref": "#/definitions/identifier"
    },
    {
      "type": "string",
      "const": "*"
    }
  ],
  "description": "A column identifier, or \"*\" for all columns."
}

table

Property	Shape	Required	Description
`name`	`#/definitions/identifier`	yes	See the downloadable schema for constraints.
`expose`	`boolean`	yes	See the downloadable schema for constraints.
`policy`	`schema`	no	See the downloadable schema for constraints.
`owner_column`	`#/definitions/identifier`	no	See the downloadable schema for constraints.
`force_owner_on_insert`	`boolean`	no	See the downloadable schema for constraints.
`live`	`boolean`	no	See the downloadable schema for constraints.
`i_understand_this_is_unrestricted`	`boolean`	no	See the downloadable schema for constraints.
`custom_sql`	`string`	no	See the downloadable schema for constraints.

view

Property	Shape	Required	Description
`name`	`#/definitions/identifier`	yes	See the downloadable schema for constraints.
`base`	`#/definitions/identifier`	yes	See the downloadable schema for constraints.
`select`	`array`	yes	See the downloadable schema for constraints.
`filter`	`string`	no	See the downloadable schema for constraints.
`security_invoker`	`boolean`	no	Always coerced to true on apply. Recorded as-given for GET roundtrip fidelity.
`expose`	`boolean`	no	See the downloadable schema for constraints.

rpc

Property	Shape	Required	Description
`name`	`#/definitions/identifier`	yes	See the downloadable schema for constraints.
`signature`	`string`	yes	Parenthesized argument list, e.g. “(user_id uuid)” or “()”. No semicolons.
`grant_to`	`array`	yes	See the downloadable schema for constraints.