> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devset.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schemas API: Register and Manage Message Schemas

> Create, retrieve, update, and delete JSON and Protobuf message schemas so Devset can validate and deserialize broker messages during workflow execution.

The Schemas API provides a local schema registry for Devset. You register a schema once — either as a JSON Schema document or a Protobuf definition — and Devset uses it to validate message payloads and deserialize broker messages during workflow simulation and execution. All endpoints are relative to `http://localhost:8082`.

***

## POST /schemas

Create a new schema. Devset supports two schema types: `json` for JSON Schema documents and `protobuf` for Protocol Buffer definitions.

<ParamField body="id" type="string" required>
  A unique identifier for this schema, such as `order-created` or `payment-processed`.
</ParamField>

<ParamField body="version" type="integer">
  A numeric version for this schema, such as `1` or `2`.
</ParamField>

<ParamField body="type" type="string" required>
  The schema format. Accepted values: `json`, `protobuf`.
</ParamField>

<ParamField body="schema" type="object | string" required>
  The schema definition. For `json`, provide a JSON Schema object. For `protobuf`, provide the raw `.proto` file content as a string.
</ParamField>

<ParamField body="descriptor" type="string">
  **Protobuf only.** A Base64-encoded `FileDescriptorSet` binary. Provide this when your `.proto` file imports other files and you want Devset to resolve them offline.
</ParamField>

<ParamField body="protobufRootMessage" type="string">
  **Protobuf only.** The fully-qualified name of the root message type to use for deserialization, such as `com.example.OrderCreated`.
</ParamField>

<Tabs>
  <Tab title="JSON Schema">
    **Request example**

    ```json theme={null}
    {
      "id": "order-created",
      "version": 1,
      "type": "json",
      "schema": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "amount": { "type": "number" },
          "status": { "type": "string" }
        },
        "required": ["id", "amount", "status"]
      }
    }
    ```
  </Tab>

  <Tab title="Protobuf">
    **Request example**

    ```json theme={null}
    {
      "id": "order-created-proto",
      "version": 1,
      "type": "protobuf",
      "schema": "syntax = \"proto3\";\npackage com.example;\nmessage OrderCreated {\n  string id = 1;\n  double amount = 2;\n  string status = 3;\n}",
      "protobufRootMessage": "com.example.OrderCreated"
    }
    ```
  </Tab>
</Tabs>

**Response — 201 Created**

```json theme={null}
{
  "id": "order-created",
  "version": 1,
  "type": "json",
  "schema": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "amount": { "type": "number" },
      "status": { "type": "string" }
    },
    "required": ["id", "amount", "status"]
  }
}
```

<ResponseField name="id" type="string">
  The identifier of the newly created schema.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number that was stored.
</ResponseField>

<ResponseField name="type" type="string">
  The schema format: `json` or `protobuf`.
</ResponseField>

<ResponseField name="schema" type="object | string">
  The stored schema definition.
</ResponseField>

***

## GET /schemas

List all schemas registered in Devset. The response contains summary information for each schema, including its full definition.

**Response — 200 OK**

```json theme={null}
[
  {
    "id": "order-created",
    "version": 1,
    "type": "json",
    "schema": {
      "type": "object",
      "properties": {
        "id": { "type": "string" }
      }
    }
  },
  {
    "id": "order-created-proto",
    "version": 1,
    "type": "protobuf",
    "schema": "syntax = \"proto3\"; ...",
    "protobufRootMessage": "com.example.OrderCreated"
  },
  {
    "id": "payment-processed",
    "version": 2,
    "type": "json",
    "schema": {}
  }
]
```

<ResponseField name="id" type="string">
  The unique schema identifier.
</ResponseField>

<ResponseField name="version" type="integer">
  The version number for this schema.
</ResponseField>

<ResponseField name="type" type="string">
  The schema format: `json` or `protobuf`.
</ResponseField>

<ResponseField name="schema" type="object | string">
  The schema definition.
</ResponseField>

<ResponseField name="descriptor" type="string | null">
  **Protobuf only.** The Base64-encoded `FileDescriptorSet`, if one was provided.
</ResponseField>

<ResponseField name="protobufRootMessage" type="string | null">
  **Protobuf only.** The fully-qualified root message name, if one was provided.
</ResponseField>

***

## PUT /schemas/{schemaId}

Replace an existing schema entirely. You must provide the full schema body — partial updates are not supported. Devset overwrites the stored definition and returns the updated schema.

**Path parameters**

<ParamField path="schemaId" type="string" required>
  The `id` of the schema to replace.
</ParamField>

<ParamField body="id" type="string" required>
  Must match the `schemaId` path parameter.
</ParamField>

<ParamField body="version" type="integer">
  The updated version number.
</ParamField>

<ParamField body="type" type="string" required>
  The schema format: `json` or `protobuf`.
</ParamField>

<ParamField body="schema" type="object | string" required>
  The updated schema definition.
</ParamField>

<ParamField body="descriptor" type="string">
  **Protobuf only.** Updated Base64-encoded `FileDescriptorSet`.
</ParamField>

<ParamField body="protobufRootMessage" type="string">
  **Protobuf only.** Updated root message type name.
</ParamField>

**Request example**

```json theme={null}
{
  "id": "order-created",
  "version": 2,
  "type": "json",
  "schema": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "amount": { "type": "number" },
      "status": { "type": "string" },
      "currency": { "type": "string" }
    },
    "required": ["id", "amount", "status", "currency"]
  }
}
```

**Response — 200 OK**

```json theme={null}
{
  "id": "order-created",
  "version": 2,
  "type": "json",
  "schema": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "amount": { "type": "number" },
      "status": { "type": "string" },
      "currency": { "type": "string" }
    },
    "required": ["id", "amount", "status", "currency"]
  }
}
```

***

## DELETE /schemas/{schemaId}

Permanently delete a schema. This cannot be undone.

**Path parameters**

<ParamField path="schemaId" type="string" required>
  The `id` of the schema to delete.
</ParamField>

**Response — 204 No Content**

An empty `204 No Content` response confirms successful deletion.

<Warning>
  Deleting a schema that is actively referenced by a workflow stage may cause validation errors the next time that workflow runs. Remove schema references from your workflows before deleting the schema.
</Warning>