Skip to main content

Operator Configuration Specification

This document provides a detailed introduction to the configuration structure and specifications of GeniSpace operators, including input/output schema definitions, configuration parameter management, and other core concepts.

Configuration Structure Overview​

Each operator contains the following main configuration sections:

{
  "name": "Operator Name",
  "identifier": "operator-id",
  "description": "Operator Description",
  "type": "operator",  // or "agent"
  "inputPorts": [ /* input port definitions */ ],
  "outputPorts": [ /* output port definitions */ ],
  "inputSchema": { /* input data structure definition */ },
  "outputSchema": { /* output data structure definition */ },
  "configuration": {
    "schema": { /* user configuration item definitions */ },
    "values": { /* default configuration values */ }
  },
  "systemConfiguration": {
    "schema": { /* system configuration item definitions */ },
    "values": { /* system configuration values */ }
  },
  "metadata": {
    "origin": "built-in" | "custom",
    "runtime": {
      // Shipped runtimes: "worker" (all built-ins) and "rest-api" (custom HTTP).
      // "container" / "mcp" are roadmap and not shipped in the current build.
      "type": "worker" | "rest-api",
      "config": {}
    }
  }
}

Operator Type Configuration​

Agent Operator Configuration​

Agent operators have a special configuration structure that includes AI model-related settings:

{
  "type": "agent",
  "name": "Medical Beauty Marketing Pro",
  "description": "Intelligent marketing expert specializing in the medical aesthetics industry",
  "promptTemplate": "Please write a Xiaohongshu promotional post for [{{product}}], key selling points: {{features}}, target audience: {{target}}, usage scenario: {{scenario}}. Highlight {{key_benefit}} and address the {{pain_point}} issue",
  "systemPrompt": "You are an expert in medical aesthetics marketing on Xiaohongshu, following these guidelines:\n1. Content complies with Xiaohongshu community standards, using language styles preferred by young women\n2. Use scenario-based descriptions with emoji symbols\n3. Include relevant hashtags (#MedicalAestheticsTrends #SkincareBlackTech)\n4. Highlight product ingredients/technology advantages related to user pain points\n5. Avoid prohibited advertising terms, using an experience-sharing format\n6. Provide customized recommendations based on user segments (age/skin type/spending capacity)",
  "inputPorts": [
    {
      "name": "memory",
      "type": "boolean",
      "label": "Enable Conversation History Memory",
      "required": false
    },
    {
      "name": "product",
      "type": "string",
      "label": "Product Name",
      "required": false
    },
    {
      "name": "features",
      "type": "string",
      "label": "Product Features",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "answer",
      "type": "string",
      "label": "Generated Content"
    }
  ],
  "model": {
    "id": "3638ac90-902e-424c-84fd-a100d9e97b43",
    "identifier": "deepseek-v3",
    "name": "DeepSeek-V3",
    "apiType": "openai",
    "modelType": "text",
    "systemConfiguration": {
      "model": "deepseek-v3",
      "apiKey": "sk-xxx",
      "apiUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "provider": "alibaba"
    }
  }
}

Worker Operator Configuration​

Configuration structure for Worker operators:

{
  "type": "operator",
  "name": "Email Sender",
  "identifier": "email",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "Recipient",
      "required": true
    },
    {
      "name": "subject",
      "type": "string",
      "label": "Email Subject",
      "required": false
    },
    {
      "name": "html",
      "type": "string",
      "label": "HTML Body",
      "required": false
    },
    {
      "name": "text",
      "type": "string",
      "label": "Plain-Text Body",
      "required": false
    },
    {
      "name": "content",
      "type": "string",
      "label": "Body (fallback for html/text)",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "Send Status"
    },
    {
      "name": "messageId",
      "type": "string",
      "label": "Message ID"
    }
  ],
  "metadata": {
    "origin": "built-in",
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}
Email body and attachments

The built-in email operator requires only to. Provide at least one of html, text, or content for the message body (when only content is set, the worker maps it to both the HTML and text parts). subject is optional and defaults to "No Subject". Attachments are not implemented by the worker — there is no attachments port.

API Operator Configuration​

Configuration structure for API operators:

{
  "type": "operator",
  "name": "Email Sender Plus",
  "identifier": "email-operator",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "Recipient",
      "required": true
    },
    {
      "name": "cc",
      "type": "array",
      "label": "CC",
      "required": false
    },
    {
      "name": "bcc",
      "type": "array",
      "label": "BCC",
      "required": false
    },
    {
      "name": "subject",
      "type": "string",
      "label": "Subject",
      "required": true
    },
    {
      "name": "text",
      "type": "string",
      "label": "Text Content",
      "required": false
    },
    {
      "name": "html",
      "type": "string",
      "label": "HTML Content",
      "required": false
    },
    {
      "name": "attachment_files",
      "type": "array",
      "label": "Attachment Files",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "Send Status"
    },
    {
      "name": "data",
      "type": "object",
      "label": "Response Data"
    }
  ],
  "metadata": {
    "origin": "custom",
    "runtime": {
      "type": "rest-api",
      "config": {
        "serverUrl": "https://api.genispace.ai",
        "method": "POST",
        "endpoint": "https://api.genispace.ai/njs-operators/message/email_operator",
        "timeout": 30000,
        "retryPolicy": {
          "maxAttempts": 3,
          "intervalMs": 1000
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Input Schema​

The Input Schema defines the input data structure accepted by an operator, based on the JSON Schema standard.

Agent Input Schema​

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "memory": {
        "type": "boolean",
        "default": false,
        "description": "Enable conversation history memory"
      },
      "target": {
        "type": "string",
        "description": "Target audience"
      },
      "context": {
        "type": "boolean",
        "default": false,
        "description": "Enable knowledge base content"
      },
      "product": {
        "type": "string",
        "description": "Product name"
      },
      "features": {
        "type": "string",
        "description": "Product features"
      },
      "internet": {
        "type": "boolean",
        "default": false,
        "description": "Enable internet search"
      },
      "scenario": {
        "type": "string",
        "description": "Usage scenario"
      },
      "pain_point": {
        "type": "string",
        "description": "User pain point"
      },
      "key_benefit": {
        "type": "string",
        "description": "Key benefit"
      }
    }
  }
}

Basic Structure​

{
  "type": "object",
  "required": ["param1"],
  "properties": {
    "param1": {
      "type": "string",
      "title": "Parameter 1",
      "description": "Description of Parameter 1",
      "isPort": true
    },
    "param2": {
      "type": "number",
      "title": "Parameter 2",
      "description": "Description of Parameter 2",
      "default": 100,
      "minimum": 0,
      "maximum": 1000
    }
  }
}

Supported Data Types​

1. String Type (string)​

{
  "type": "string",
  "title": "Text Input",
  "description": "Please enter text content",
  "minLength": 1,
  "maxLength": 1000,
  "pattern": "^[a-zA-Z0-9]+$",
  "default": "default value"
}

2. Number Type (number/integer)​

{
  "type": "number",
  "title": "Numeric Input",
  "description": "Please enter a number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.1,
  "default": 50
}

3. Boolean Type (boolean)​

{
  "type": "boolean",
  "title": "Toggle Option",
  "description": "Whether to enable this feature",
  "default": false
}

4. Array Type (array)​

{
  "type": "array",
  "title": "List Data",
  "description": "Data list",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

5. Object Type (object)​

{
  "type": "object",
  "title": "Configuration Object",
  "description": "Complex configuration object",
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "value": {
      "type": "number",
      "title": "Value"
    }
  },
  "required": ["name"]
}

Port Identification​

Use the isPort attribute to indicate whether a field is a workflow connection port:

{
  "param1": {
    "type": "string",
    "title": "Input Data",
    "isPort": true,  // Identified as a port, connectable in workflows
    "description": "Data from upstream nodes"
  },
  "config1": {
    "type": "string",
    "title": "Configuration Parameter",
    "isPort": false, // Not a port, used only as a configuration parameter
    "description": "Operator configuration parameter"
  }
}

Default Value Settings​

Default values can be set for input parameters:

{
  "properties": {
    "timeout": {
      "type": "number",
      "title": "Timeout",
      "description": "Request timeout in seconds",
      "default": 30,
      "minimum": 1,
      "maximum": 300
    },
    "retryCount": {
      "type": "integer",
      "title": "Retry Count",
      "description": "Number of retries on failure",
      "default": 3,
      "minimum": 0,
      "maximum": 10
    }
  }
}

Output Schema​

The Output Schema defines the output data structure produced by an operator.

Agent Output Schema​

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "string",
        "label": "Generated Content",
        "description": "AI-generated response content"
      }
    }
  }
}

Basic Structure​

{
  "type": "object",
  "properties": {
    "result": {
      "type": "object",
      "title": "Processing Result",
      "description": "Result data from operator execution",
      "properties": {
        "status": {
          "type": "string",
          "title": "Status",
          "enum": ["success", "error"]
        },
        "data": {
          "type": "object",
          "title": "Data",
          "description": "Actual result data"
        },
        "message": {
          "type": "string",
          "title": "Message",
          "description": "Execution message or error information"
        }
      }
    },
    "metadata": {
      "type": "object",
      "title": "Metadata",
      "description": "Metadata about the execution process",
      "properties": {
        "executionTime": {
          "type": "number",
          "title": "Execution Time",
          "description": "Operator execution duration in milliseconds"
        },
        "timestamp": {
          "type": "string",
          "title": "Timestamp",
          "format": "date-time"
        }
      }
    }
  }
}

Conditional Output​

For operators with conditional branches, multiple output ports can be defined:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "object",
      "title": "Success Output",
      "description": "Output when processing succeeds",
      "isPort": true
    },
    "error": {
      "type": "object",
      "title": "Error Output",
      "description": "Output when processing fails",
      "isPort": true
    }
  }
}

Configuration Management​

Operator configuration is divided into two levels: operator-level configuration and method-level configuration.

Operator-Level Configuration​

Operator-level configuration is global configuration that affects the entire operator's behavior:

{
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "Server URL",
          "description": "Base URL of the API server",
          "required": true,
          "format": "uri"
        },
        "timeout": {
          "type": "number",
          "title": "Global Timeout",
          "description": "Request timeout in milliseconds",
          "default": 30000,
          "minimum": 1000,
          "maximum": 300000
        },
        "headers": {
          "type": "array",
          "title": "Global Headers",
          "description": "Global headers applied to all requests",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "title": "Header Name"
              },
              "value": {
                "type": "string",
                "title": "Header Value"
              }
            },
            "required": ["key", "value"]
          }
        },
        "retryPolicy": {
          "type": "object",
          "title": "Global Retry Policy",
          "properties": {
            "maxAttempts": {
              "type": "number",
              "title": "Max Retry Attempts",
              "default": 3,
              "minimum": 0,
              "maximum": 10
            },
            "intervalMs": {
              "type": "number",
              "title": "Retry Interval",
              "description": "Retry interval in milliseconds",
              "default": 1000,
              "minimum": 100
            }
          }
        }
      }
    },
    "values": {
      "serverUrl": "",
      "timeout": 30000,
      "headers": [
        {"key": "Content-Type", "value": "application/json"}
      ],
      "retryPolicy": {
        "maxAttempts": 3,
        "intervalMs": 1000
      }
    }
  }
}

Method-Level Configuration​

Each operator method can have its own specific configuration:

{
  "methods": [
    {
      "name": "Get User Info",
      "identifier": "get-user",
      "configuration": {
        "schema": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "title": "Request Method",
              "enum": ["GET", "POST", "PUT", "DELETE"],
              "default": "GET",
              "required": true
            },
            "endpoint": {
              "type": "string",
              "title": "Endpoint Path",
              "description": "Endpoint path relative to the server URL",
              "required": true,
              "pattern": "^/"
            },
            "caching": {
              "type": "object",
              "title": "Caching Configuration",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "title": "Enable Caching",
                  "default": false
                },
                "ttlSeconds": {
                  "type": "number",
                  "title": "Cache Duration",
                  "description": "Cache validity period in seconds",
                  "default": 3600,
                  "minimum": 60
                }
              }
            },
            "headers": {
              "type": "array",
              "title": "Method-Specific Headers",
              "description": "Headers applied only to this method",
              "items": {
                "type": "object",
                "properties": {
                  "key": {"type": "string"},
                  "value": {"type": "string"}
                }
              }
            }
          }
        },
        "values": {
          "method": "GET",
          "endpoint": "/api/users/{id}",
          "caching": {
            "enabled": true,
            "ttlSeconds": 1800
          },
          "headers": []
        }
      }
    }
  ]
}

System Configuration​

System configuration consists of internal settings invisible to users, used for storing sensitive information and system-level parameters.

Operator-Level System Configuration​

{
  "systemConfiguration": {
    "schema": {
      "type": "api",
      "properties": {
        "internalServerUrl": {
          "type": "string",
          "title": "Internal Server URL",
          "description": "Internal API server address",
          "required": true
        },
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "description": "System-level API key",
          "format": "password",
          "required": true
        },
        "rateLimiting": {
          "type": "object",
          "title": "Rate Limiting Configuration",
          "properties": {
            "requestsPerSecond": {
              "type": "number",
              "title": "Requests Per Second",
              "default": 10
            },
            "burstSize": {
              "type": "number",
              "title": "Burst Size",
              "default": 20
            }
          }
        }
      }
    },
    "values": {
      "internalServerUrl": "https://internal-api.example.com",
      "apiKey": "system-secret-key",
      "rateLimiting": {
        "requestsPerSecond": 10,
        "burstSize": 20
      }
    }
  }
}

Method-Level System Configuration​

{
  "methods": [
    {
      "systemConfiguration": {
        "schema": {
          "type": "api",
          "properties": {
            "internalEndpoint": {
              "type": "string",
              "title": "Internal Endpoint Path",
              "required": true
            },
            "authToken": {
              "type": "string",
              "title": "Authentication Token",
              "format": "password"
            }
          }
        },
        "values": {
          "internalEndpoint": "/internal/users",
          "authToken": "method-specific-token"
        }
      }
    }
  ]
}

Configuration Type Details​

Configuration Differences by Execution Type​

API Type Operators​

{
  "metadata": {
    "runtime": {
      "type": "rest-api",
      "config": {
        "serverUrl": "https://api.genispace.ai",
        "method": "POST",
        "endpoint": "/njs-operators/message/email_operator",
        "timeout": 30000,
        "retryPolicy": {
          "maxAttempts": 3,
          "intervalMs": 1000
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Worker Type Operators​

{
  "metadata": {
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

MCP Type Operators (roadmap — not shipped)​

Not available in the current build

The MCP runtime is not shipped. The snippet below illustrates the intended configuration shape only.

{
  "systemConfiguration": {
    "schema": {
      "type": "mcp",
      "properties": {
        "serverUrl": {"type": "string", "required": true},
        "model": {"type": "string", "required": true},
        "apiKey": {"type": "string", "format": "password"},
        "timeout": {"type": "number", "default": 60000}
      }
    }
  }
}

Container Type Operators (roadmap / enterprise — not shipped)​

Not available in the current build

The Container runtime is not shipped. The snippet below illustrates the intended configuration shape only.

{
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {"type": "string", "required": true},
        "registry": {
          "type": "object",
          "properties": {
            "url": {"type": "string"},
            "username": {"type": "string"},
            "password": {"type": "string", "format": "password"}
          }
        },
        "resources": {
          "type": "object",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    }
  }
}

Configuration Validation​

Schema Validation Rules​

  1. Required Field Validation: Use the required array to specify required fields
  2. Data Type Validation: Strictly validate field data types
  3. Format Validation: Use the format attribute to validate specific formats (e.g., email, uri, date-time)
  4. Range Validation: Use minimum, maximum, minLength, maxLength, etc.
  5. Enumeration Validation: Use enum to restrict allowed values
  6. Regex Validation: Use pattern for regular expression validation

Example Validation Configuration​

{
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "Email Address"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://",
      "title": "URL"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "title": "Port Number"
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending"],
      "title": "Status"
    }
  },
  "required": ["email", "url"]
}

Best Practices​

1. Schema Design Principles​

  • Clear Naming: Use meaningful field names and titles
  • Detailed Descriptions: Provide clear descriptions for each field
  • Reasonable Defaults: Provide sensible default values for optional fields
  • Appropriate Validation: Add necessary validation rules without being overly restrictive

2. Configuration Layering​

  • Operator-Level Configuration: Global, common configuration
  • Method-Level Configuration: Configuration specific to a particular method
  • User Configuration: Parameters visible and configurable by users
  • System Configuration: Sensitive internal configurations used by the system

3. Backward Compatibility​

  • Adding Fields: Always provide default values
  • Modifying Fields: Maintain backward compatibility; consider using new field names
  • Removing Fields: Mark as deprecated rather than deleting directly

4. Security Considerations​

  • Sensitive Information: Use format: "password" to mark sensitive fields
  • Input Validation: Strictly validate all input data
  • Access Control: Differentiate access permissions between user and system configurations