Skip to navigation
AppsFlowAIAgents and projects

Configure a decorator's JSON schema

A decorator’s JSON schema lets you refine how an agent uses a tool’s inputs, beyond what the tool’s own schema provides. For example, you can set a default value, restrict allowed values, or limit which fields the agent can use. This is more reliable than pasting example payloads into the prompt.

See the following examples for ideas.

Before you begin

  • Know how to create or clone a decorator. This guide assumes you’re already at the Schema field on the Create Decorator page. For that procedure, see Schema decorators.
  • Know your starting schema. Every change below builds on what’s already in the Schema, so review it before you add a default, restriction, or removal. When you create a new decorator, that’s the tool’s original schema. When you clone one, it’s the schema of the decorator you cloned.
  • Have a working familiarity with JSON schemas. The Schema field uses the same type system as the JSON Schema standard. If you haven’t written a schema by hand before, start with that guide. It covers the same type, properties, required, and description keywords referenced below.
  • Have permission to create a decorator for the tool. For the specific permissions, see Access control.

Understand decorator schemas

A decorator’s Schema is a single JSON code editor with search and copy-to-clipboard actions built into its toolbar.

When you create a new decorator, Itential pre-populates this field with the tool’s own JSON schema, which is the same schema already defined for that adapter, application, or integration method. It can include details beyond basic types, such as pattern, title, or examples, if that schema includes them.

For more information about working with schemas, see Schema decorators.

Examples

Assign a default value to an input field

Set a default when the tool consistently expects the same value for a field. This reduces how often the agent has to reason about a parameter it doesn’t have strong context for, and prevents empty submissions.

1

Open Create Decorator, either by creating a new decorator or by cloning an existing one.

2

Locate the property definition for the field you want to default in the Schema field.

3

Add a default keyword to that property, set to the value you want.

4

Click Save Decorator.

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "default": "amer-east"
    }
  }
}

A default only applies when the agent omits the field. It doesn’t stop the agent from sending a different value. To constrain what the agent can send, use enum, described next.

Restrict the allowed values for an input field

Use enum to give the agent a closed list of valid values instead of an open string or number field. This prevents the agent from guessing at a value that isn’t valid for the tool.

1

Open Create Decorator, either by creating a new decorator or by cloning an existing one.

2

Locate the property definition for the field you want to restrict in the Schema field.

3

Add an enum array listing every value you want to allow.

4

Click Save Decorator.

{
  "type": "object",
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  }
}

You can combine enum with default on the same property. In the example above, adding "default": "medium" gives the agent a fallback while still limiting it to the three listed values.

Restrict the agent to specific input fields

Some tools expose several optional fields that you don’t want the agent using, even though the underlying tool supports them. This is different from marking a field required. required only guarantees a field always has a value; it doesn’t stop the agent from also using other optional fields still in the schema.

Removing a property from a decorator’s schema doesn’t remove it from the tool itself. It only limits what the agent sees as an input option.

To limit which fields the agent can use:

1

Open Create Decorator, either by creating a new decorator or by cloning an existing one.

2

In the Schema field, remove the property definitions for any fields you don’t want the agent to use. The schema starts as a copy, either of the tool’s full set of properties or of the cloned decorator’s, so this usually means deleting entries rather than adding restrictions to nothing.

3

Add the fields that must always have a value to the required array.

4

(Optional) Set "additionalProperties": false at the schema level. This blocks the agent from sending any field beyond what you explicitly define, even if the tool itself would accept it.

5

Click Save Decorator.

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    }
  },
  "required": ["hostname"],
  "additionalProperties": false
}

Add a description to clarify what an input field is for

A tool’s original schema may give an input field a generic or missing description. The agent then knows a field’s type, but not what the value represents or where it should come from. Update the description keyword for a property to spell that out directly, for example by pointing the agent to the right upstream source for a value instead of leaving it to guess.

1

Open Create Decorator, either by creating a new decorator or by cloning an existing one.

2

Locate the property definition for the input field you want to clarify in the Schema field.

3

Add or update the description value with specific, task-relevant guidance, such as what the value represents or where the agent should get it from.

4

Click Save Decorator.

{
  "type": "object",
  "properties": {
    "zone_id": {
      "type": "string",
      "description": "The DNS zone identifier returned by the zone lookup tool. Don't use the zone name here."
    }
  }
}

Unlike enum or required, a property’s description doesn’t restrict or validate what the agent sends. It only shapes how the agent interprets the field, so pair it with the techniques above when you need enforcement rather than guidance.

This is the description keyword on an individual property inside the schema. It isn’t the same as the Override Tool Description field, which describes what the tool as a whole does.

Troubleshoot a schema change

The agent still sends a field you removed. Saving creates the decorator but doesn’t apply it. Confirm the decorator you saved is the active one for that tool, and that you haven’t assigned a different decorator since.

The agent sends a value outside your enum list. Confirm you defined the enum array on the property itself rather than at the root of the schema, and that you saved the decorator after adding it.

You want to undo a change you already saved. You can’t change a saved decorator, so reassign the earlier decorator if one exists, or clone the current one and correct the copy.