ZitadelDocs

Create new schema

Create a new schema. The optional `$id` field is the JSON Schema document URI used to identify the schema in future requests (GitOps-stable identity, not a free-form resource primary key). When `$id` is omitted, the server generates a `sch_*` URL. When provided, `$id` must be unique within the project and should ideally be a valid URI pointing at where the schema can be accessed. The schema can either be a concrete schema, e.g. a user schema, or a schema-url which will be resolved by the server.

POST
/schemas

Create a new schema. The optional $id field is the JSON Schema document URI used to identify the schema in future requests (GitOps-stable identity, not a free-form resource primary key). When $id is omitted, the server generates a sch_* URL. When provided, $id must be unique within the project and should ideally be a valid URI pointing at where the schema can be accessed.

The schema can either be a concrete schema, e.g. a user schema, or a schema-url which will be resolved by the server.

Authorization

oauth2 schema.write
headerAuthorizationBearer <token>

Scope: schema.write

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$
team_id?string

The unique identifier of the team

Match^[a-zA-Z0-9_-]+$

Request Body

application/json
  1. body

The meta-schema a customer's user schema document is validated against. The generated user-schema.json adds allOf: [{$ref: draft-2020-12}], which cannot live here because code generators choke on it.

$schema?string

The JSON Schema version used for this schema.

objectType?string

The type of user this schema describes. This is a customer chosen name.

Lengthlength <= 256
kind*string

Discriminator value for a user schema create request.

metaSchema*string

The user Schema version used for this schema.

Formaturi
Lengthlength <= 1024
x-auth-methods*

A list of authentication methods supported by the user definition.

Properties1 <= properties
x-identifier?string

Path of the leaf property whose value identifies a user (nested leaves are addressed by their dot-joined attribute path). The property must carry x-unique "project". Required when an auth method needing identifier-first dispatch (password) is enabled. Passkey is exempt: discoverable credentials identify the user through the assertion itself, so passkey-only and API-managed schemas may designate nothing; flows using identifier-first passkey are validated at the flow level instead.

Length1 <= length
x-display?array<>

Ordered leaf property paths whose values, joined with a space, render the user's display name.

Items1 <= items
properties?

A map of additional properties for the user definition, where the key is the property name and the value is the property schema

[key: string]?any

Response Body

The schema was created successfully

application/json
  1. response
id*string

The ID of the created schema

curl -X POST 'https://example.com/schemas?project_id=string' \  -H 'Content-Type: application/json' \  -d '{  "title": "ExampleUserSchema",  "$schema": "https://raw.githubusercontent.com/zitadel/nextgen/refs/heads/main/api/openapi/endpoints/schemas/user-schema.json",  "kind": "user-schema",  "type": "object",  "description": "This is an example of a user schema definition.",  "objectType": "human-user",  "x-auth-methods": {    "password": {      "enabled": false    },    "passkey": {      "enabled": true    }  },  "required": [    "email",    "password"  ],  "properties": {    "email": {      "type": "string",      "format": "email",      "description": "The user'\''s email address."    },    "password": {      "type": "string",      "minLength": 8,      "description": "The user'\''s password, which must be at least 8 characters long."    },    "firstName": {      "type": "string",      "description": "The user'\''s first name."    },    "lastName": {      "type": "string",      "description": "The user'\''s last name."    },    "address": {      "type": "object",      "description": "The user'\''s address information.",      "properties": {        "street": {          "type": "string",          "description": "The street address."        },        "houseNumber": {          "type": "string",          "description": "The house number of the address."        },        "city": {          "type": "string",          "description": "The city of the address."        },        "postalCode": {          "type": "string",          "description": "The postal code of the address."        },        "country": {          "type": "string",          "description": "The country of the address."        }      }    }  }}'
{  "id": "sch_abcd1234_efgh5678"}