Skip to content

Publish App Schema Version

POST
/apps/{app_id}/schema-versions

Publish a declared object schema and materialize it across consented tenants.

422 with every validation problem at once, so a builder fixes their whole schema in one round trip rather than one error per attempt.

A publish that resolves to an EXISTING version still returns 201 with created: false — the resource named by the response exists either way, and the flag is what tells a caller nothing changed.

Authorizations

Parameters

Path Parameters

app_id
required
string

Header Parameters

X-Org-Id
Any of:
string

Request Body required

A schema publish carries ONLY declared objects.

Not a whole graph8.app.yaml: frontend/backend are deploy-time build config (M6-5) and have no bearing on what a tenant’s cb_* tables receive. Accepting them here would let a Dockerfile edit re-materialize every tenant.

object
objects
required

Declared custom objects, in graph8.app.yaml objects: shape.

Array

Responses

201

Successful Response

object
data
required

The version, plus whether it was newly created and how the fan-out went.

object
created
required

False when an identical schema was already published — the retry no-op.

boolean
materialization
required

How the fan-out went, as counts. Never tenant ids — see module docstring.

object
failed
integer
ready
integer
skipped

Tenants already materialized on this exact digest.

integer
total
integer
version
required

One published (or draft) object-schema version.

object
app_id
required
string
created_at
Any of:
string format: date-time
deprecated_at
Any of:
string format: date-time
digest
required

SHA-256 of the canonical schema. Re-publishing the same schema resolves here.

string
manifest

The stored canonical schema. Self-describing, so the version needs no other source.

object
key
additional properties
any
published_at
Any of:
string format: date-time
schema_version_id
required
string
status
required
string
version
required

Human-facing ordinal. Nothing keys on it; the digest is the identity.

integer
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string