JSON Schemas

JSON Schemas

This page documents all JSON schemas used by the RCL compiler for validation and tooling support.

Available Schemas

All schemas are served from https://rcl.rcsagents.io/schemas/ and can be used in $schema properties for validation.

Core Output Schemas

RCL Output Schema

• URL: https://rcl.rcsagents.io/schemas/rcl-output.schema.json
• Description: Main schema for RCL compiler output combining agent, flows, and messages
• Usage: Complete compilation output validation

{
  "$schema": "https://rcl.rcsagents.io/schemas/rcl-output.schema.json",
  "agent": { /* ... */ },
  "flows": { /* ... */ },
  "messages": { /* ... */ }
}

Conversation State Machine (CSM) Schema

• URL: https://rcl.rcsagents.io/schemas/csm/machine-definition.schema.json
• Description: Schema for conversation state machines used in flows
• Usage: Flow validation and state machine definitions

{
  "$schema": "https://rcl.rcsagents.io/schemas/csm/machine-definition.schema.json",
  "id": "MainFlow",
  "initial": "Welcome",
  "states": { /* ... */ }
}

Component Schemas

Agent Configuration Schema

• URL: https://rcl.rcsagents.io/schemas/agent-config.schema.json
• Description: Schema for RCS Business Messaging agent configuration
• Usage: Agent metadata and configuration validation

Agent Message Schema

• URL: https://rcl.rcsagents.io/schemas/agent-message.schema.json
• Description: Schema for RCS Business Messaging agent messages
• Usage: Message content and suggestion validation

RCL Document Schemas

RCL Document Schema

• URL: https://rcl.rcsagents.io/schemas/rcl-document.schema.json
• Description: Schema for complete RCL document structure
• Usage: RCL file validation

RCL Agent Section Schema

• URL: https://rcl.rcsagents.io/schemas/rcl-agent-section.schema.json
• Description: Schema for RCL agent section
• Usage: Agent section validation in RCL files

RCL Flow Section Schema

• URL: https://rcl.rcsagents.io/schemas/rcl-flow-section.schema.json
• Description: Schema for RCL flow section
• Usage: Flow section validation in RCL files

RCL Messages Section Schema

• URL: https://rcl.rcsagents.io/schemas/rcl-messages-section.schema.json
• Description: Schema for RCL messages section
• Usage: Messages section validation in RCL files

Schema Structure Overview

Main Output Structure

The RCL compiler produces output following this structure:

{
  "$schema": "https://rcl.rcsagents.io/schemas/rcl-output.schema.json",
  "agent": {
    "name": "AgentName",
    "displayName": "Display Name",
    "config": { /* Agent configuration */ },
    "defaults": { /* Default values */ }
  },
  "flows": {
    "FlowId": {
      "$schema": "https://rcl.rcsagents.io/schemas/csm/machine-definition.schema.json",
      "id": "FlowId",
      "initial": "InitialState",
      "states": { /* State definitions */ }
    }
  },
  "messages": {
    "MessageId": {
      "type": "text|richCard|carousel",
      "text": "Message content",
      "suggestions": [ /* Suggestions array */ ]
    }
  }
}

Flow (CSM) Structure

Flows use the Conversation State Machine format:

{
  "id": "MainFlow",
  "initial": "Welcome",
  "states": {
    "Welcome": {
      "transitions": [
        {
          "pattern": "order_coffee",
          "target": "OrderCoffee",
          "context": { "category": "order" }
        },
        {
          "pattern": ":default",
          "target": "Welcome"
        }
      ],
      "meta": {
        "messageId": "WelcomeMessage"
      }
    }
  }
}

Message Structure

Messages use a simplified, flat structure:

{
  "type": "richCard",
  "title": "Welcome",
  "description": "How can we help you?",
  "suggestions": [
    {
      "type": "reply",
      "text": "Order Coffee",
      "postbackData": "order_coffee"
    }
  ],
  "messageTrafficType": "PROMOTION"
}

Using Schemas in Development

IDE Integration

Add $schema properties to your JSON files for validation and autocomplete:

{
  "$schema": "https://rcl.rcsagents.io/schemas/rcl-output.schema.json",
  // Your content here...
}

Validation Tools

Use JSON Schema validators to check compliance:

# Using ajv-cli
npx ajv validate -s https://rcl.rcsagents.io/schemas/rcl-output.schema.json -d output.json

# Using jsonschema (Python)
jsonschema -i output.json https://rcl.rcsagents.io/schemas/rcl-output.schema.json

Schema Versioning

Schemas are versioned and backward compatibility is maintained where possible:

• Breaking changes will result in new schema URLs
• Non-breaking additions may be made to existing schemas
• Deprecated fields will be marked but maintained for compatibility

Contributing

Schema files are located in:

• /schemas/ - Main schemas
• /packages/csm/schema/ - CSM-specific schemas

When updating schemas:

1. Ensure backward compatibility
2. Update documentation
3. Run validation tests
4. Update examples