> ## 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.

# Manage JSON and Protobuf Schemas in the Schema Repo

> Create, edit, and organise JSON Schema and Protobuf definitions in Devset's Schema Repo for use in workflows, the Flow Builder, and Message Dispatch.

The Schema Repo is Devset's central registry for message schema definitions. Store your JSON Schema and Protobuf schemas here, then reference them by `schemaId` anywhere in Devset — the Flow Builder uses them to power field autocomplete and the Function Studio field tree, while Message Dispatch uses them to validate JSON payloads and encode Protobuf messages before dispatch. Open the Schema Repo at [http://localhost:8082/schema-repo](http://localhost:8082/schema-repo).

## Adding a JSON Schema

<Steps>
  <Step title="Create a new schema">
    In the Schema Repo, click **Create**. A new schema entry opens in the edit panel on the right side of the screen.
  </Step>

  <Step title="Set the schema ID">
    Enter a unique `schemaId` for this schema. This is the identifier you will reference in the Flow Builder (via the Payload Editor) and in Message Dispatch's Schema section. Choose a name that clearly describes the message type, such as `order-placed` or `user-registered`.
  </Step>

  <Step title="Paste the JSON Schema">
    The edit panel defaults to JSON Schema mode. Paste or write your JSON Schema definition into the editor. Here is an example:

    ```json theme={null}
    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "$id": "order-placed",
      "type": "object",
      "required": ["orderId", "customerId", "total"],
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Unique identifier for the order."
        },
        "customerId": {
          "type": "string",
          "description": "Identifier of the customer who placed the order."
        },
        "total": {
          "type": "number",
          "description": "Total value of the order in the specified currency."
        },
        "currency": {
          "type": "string",
          "default": "USD"
        }
      }
    }
    ```
  </Step>

  <Step title="Save the schema">
    Click **Save**. The schema appears in the left sidebar under the **JSON** group, listed by its `schemaId`.
  </Step>
</Steps>

## Adding a Protobuf Schema

<Steps>
  <Step title="Create a new schema">
    Click **Create** to open a new schema entry in the edit panel.
  </Step>

  <Step title="Set the schema ID and select Protobuf">
    Enter a unique `schemaId`, then switch the schema type selector to **Protobuf**. The edit panel switches to a `.proto` file editor.
  </Step>

  <Step title="Write or paste the .proto definition">
    Enter your Protobuf message definition. Here is an example:

    ```protobuf theme={null}
    syntax = "proto3";

    package devset.events;

    message OrderPlaced {
      string order_id    = 1;
      string customer_id = 2;
      double total       = 3;
      string currency    = 4;

      repeated OrderItem items = 5;
    }

    message OrderItem {
      string sku = 1;
      int32  qty = 2;
    }
    ```
  </Step>

  <Step title="Save the schema">
    Click **Save**. The schema appears in the left sidebar under the **Protobuf** group.
  </Step>
</Steps>

## Searching the Schema Sidebar

The left sidebar groups schemas by type: **JSON** schemas appear at the top, **Protobuf** schemas below. Use the **search bar** at the top of the sidebar to filter schemas by name. Results narrow as you type, making it quick to find a schema in a large registry.

## How Schemas Are Used Across Devset

Schemas stored in the Schema Repo integrate with the rest of Devset in two main ways:

<CardGroup cols={2}>
  <Card title="Flow Builder & Function Studio" icon="diagram-project">
    Set the `schemaId` in the workflow's DSL (via the Payload Editor in the canvas) to attach a schema to a workflow. The canvas editor and Stage Inspector use the schema to suggest valid field names, and the Function Studio field tree is populated from the schema's property structure — so you click to pick fields rather than type them by hand.
  </Card>

  <Card title="Message Dispatch" icon="paper-plane">
    Select a schema in the Schema section of a dispatch request. JSON schemas validate the payload before it is sent. Protobuf schemas encode the JSON payload into binary wire format using the linked `.proto` definition.
  </Card>
</CardGroup>

## Editing a Schema

Click any schema in the sidebar to load it into the edit panel. Make your changes in the editor and click **Save**. Updates take effect immediately — any workflow or dispatch request referencing that `schemaId` will use the updated definition on the next run or send.

<Warning>
  Editing a schema's structure (for example, removing a required field) can break workflows or dispatch requests that depend on those fields. Review all references to the `schemaId` before making breaking changes.
</Warning>

## Deleting a Schema

Select the schema in the sidebar and click **Delete**. Confirm the deletion in the dialog that appears.

<Warning>
  Deleting a schema is permanent. Any workflows or dispatch requests that reference the deleted `schemaId` will lose their schema linkage. Update or re-link those references before deleting a schema that is in active use.
</Warning>