---
title: "Schema Reference"
description: "Generated JSON Schemas for the generic resource API: envelope, metadata, controller status map, Organization, and ResourceDefinition."
---

import JsonSchema from '../../../components/JsonSchema.astro';

These schemas are generated from the Rust types in `crates/rise-resource-api/` and are byte-identical across runs. They are regenerated and verified in CI via:

```bash
mise run resource:schema:generate
mise run resource:schema:check
```

The raw JSON files live under `/operator-docs/schemas/` (linked from each section). Tooling can consume them directly: JSON Schema Draft 2020-12.

## Generic envelope

The wire envelope for any resource — built-in or external. `spec` and `status` are generic (kind-specific shapes are validated by typed validators for built-ins and JSON Schema for external custom resources).

<JsonSchema file="resource-envelope.schema.json" title="Resource" />

## Resource metadata

Standard metadata fields common to every resource. The fields `uid`, `revision`, `discriminator`, and `deletionTimestamp` are server-controlled (rejected on create; only `revision` is required on update).

<JsonSchema file="resource-metadata.schema.json" title="ResourceMetadata" />

## Controller status map

The shape of `status` for kinds that surface controller-owned status. Each entry under `controllers` is keyed by the controller's `identity_id` (a Kubernetes-style controller ID, e.g. `controller.example.com` or `controller.example.com/my-controller`).

<JsonSchema file="controller-status-map.schema.json" title="ControllerStatusMap" />

## Organization

The built-in `Organization` resource — root-scoped (`apiVersion: rise.dev/v1alpha1`, `kind: Organization`). `spec.deploymentControllerClass` is the controller identifier that owns this org's deployments; the Kubernetes controller reconciles only orgs whose value matches its configured `controller_class_name`. The default organization additionally carries an annotation `kubernetes.rise.dev/namespace-prefix` that the Kubernetes controller uses to build per-project namespace names.

<JsonSchema file="organization.schema.json" title="Organization" />

## ResourceDefinition

The built-in `ResourceDefinition` resource that registers custom resource kinds. Identity fields (`group`, `kind`, `plural`, `parent`) become immutable once instances exist. See [Custom Resources](./custom-resources) for the registration flow and version lifecycle.

<JsonSchema file="resource-definition.schema.json" title="ResourceDefinition" />

## Backend settings and `rise.toml`

These are generated by separate commands (`backend config-schema`, `backend rise-toml-schema`), not by `backend schemas generate`. They are kept separate to avoid two code paths for the same artifact.

- [Backend settings schema](/operator-docs/schemas/backend-settings.schema.json)
- `rise.toml` schema: `docs/user/public/schemas/rise-toml-v1.schema.json` — served by the user docs site at `/schemas/rise-toml-v1.schema.json`
