Robo Platform — JSON Config Schemas

Plain-HTML developer documentation (bootstrap version, to be refined)
Generated by ChatGPT • Last edited: 2025‑12‑27

Overview

This document describes the JSON “structure files” used by the Robo platform. It is based on the provided JSON Schemas and best-guess semantics inferred from field names. Expect to iterate: as you learn real runtime behavior, update the descriptions and examples.

General conventions (assumed)
  • Identifiers / references are often strings like key, code, regulation_id, task_id, step_id.
  • “type” is a discriminator whenever present (e.g., integration, web-app, workflow, goal).
  • Files with additionalProperties: true are intentionally extensible; do not assume unknown fields are errors.
  • Arrays like workflows, regulations, integrations probably hold IDs/codes/keys to other assets.

Recommended repository layout (simple)

schemas/
  app.schema.json
  meta.schema.json
  integration.schema.json
  manifest.schema.json
  workflow.schema.json
  regulation.schema.json
  goal.schema.json

assets/              # your actual data/config JSONs
  apps/
  workflows/
  regulations/
  goals/
  integrations/
  packages/

docs/
  index.html         # this file

If you keep schema filenames stable, you can later auto-generate docs from the schemas and layer in custom descriptions.

Schema detection / discriminator

In practice you’ll want to decide which schema to validate against when a JSON file is loaded. Here is a safe, deterministic heuristic that matches the provided schemas.

Recommended discriminator algorithm (best guess) 
// Pseudocode — choose a schema for an arbitrary JSON object "obj"
if (obj.type === "web-app") return manifest.schema.json
if (obj.type === "integration") return integration.schema.json
if (obj.type === "workflow") return workflow.schema.json
if (obj.type === "goal") return goal.schema.json
if (obj.type === "regulation" || obj.type === "regulations") return regulation.schema.json

// Schemas without a "type" discriminator:
if ("defaultRoute" in obj) return app.schema.json          // required there
if ("key" in obj && "name" in obj && "version" in obj) return meta.schema.json

// Fallback:
return "unknown" // or validate against a generic schema / allow raw JSON

Why this works: manifest, integration, workflow, goal have a top-level type constraint. app and meta do not, so we use their required keys.

app.schema.json

Draft-07 • additionalProperties: true required: defaultRoute

Purpose (best guess)

Defines UI-facing metadata and navigation configuration for an app/package in the Robo platform. Used to build menus, set landing pages, and control initial setup gating.

How the runtime likely uses it

  • defaultRoute is the initial route/path to open when the app launches.
  • menu describes navigable entries (routes or nested groups).
  • requiresInitialSetup may hide the app until configured (or redirect to setup flow).
  • priority influences ordering in an app launcher / marketplace.
Field reference
Field Type Required Description (guess) Notes / constraints
defaultRoute string yes Default route/path to open on app start. Could be a frontend route like "/dashboard" or a named route key.
requiresInitialSetup boolean no Whether the app requires setup/config before use. Common behavior: redirect to wizard or block entry until setup completes.
priority integer no Ordering/importance indicator (higher = more prominent). Decide and document your convention (e.g., 0–100).
icon string no Icon identifier (name, URL, or asset path). If you use an icon set, standardize names (e.g., "ri-settings-3").
color string no Brand color for the app (hex or token). Example: "#3B82F6" or "primary".
description string no Human-readable app description. Useful for marketplace cards and tooltips.
tags string[] no Keywords for search/filtering. Example: ["finance","automation"].
menu object no Menu map of label → route or label → submenu object. Each property value is either:
  • string (route)
  • object whose values are strings (submenu: label → route)
* any no Additional custom fields. Extensible — unknown fields are allowed by schema.
Example 
{
  "defaultRoute": "/dashboard",
  "requiresInitialSetup": true,
  "priority": 50,
  "icon": "ri-rocket-2-line",
  "color": "#7C3AED",
  "description": "Automation and compliance hub for Robo packages.",
  "tags": ["automation", "compliance"],
  "menu": {
    "Dashboard": "/dashboard",
    "Workflows": "/workflows",
    "Compliance": {
      "Regulations": "/regulations",
      "Audit trail": "/audit"
    }
  },
  "custom": {
    "ownerTeam": "platform",
    "featureFlags": ["betaWorkflows"]
  }
}

meta.schema.json

Draft-07 • additionalProperties: true required: key, name, version

Purpose (best guess)

Describes a package/module at a catalog level: identity (key), display name, version, capabilities, referenced assets (workflows/documents/regulations/integrations), and availability/pricing.

“Determinant” fields (identification)

  • key is likely the stable internal identifier (used in references and filenames).
  • version indicates content compatibility and upgrade behavior.
  • type (if you later standardize it) could become a discriminator, but currently it is unconstrained.
Field reference
Field Type Required Description (guess) Notes / constraints
key string yes Stable unique identifier for the package. Recommend: lowercase, dash/underscore, no spaces (enforce later with pattern).
name string yes Human-readable display name. Shown in UI.
version string yes Package version (semantic or otherwise). Recommend SemVer (1.2.3) but schema doesn’t enforce it.
type string no Package type/category. Unconstrained; consider making this an enum later.
entry string no Entry reference (route, file path, module id, etc.). Often pairs with app.defaultRoute or manifest.entry_url.
workflows string[] no Workflow IDs/codes included in this package. Likely references workflow JSON files.
documents string[] no Document template IDs or document schema refs. Use a consistent ID strategy across documents.
regulations string[] no Regulation IDs included or supported. Likely references regulation_id or filenames.
integrations string[] no Integration IDs supported/required. Likely references integrations by their name or another ID you define.
modules string[] no Logical modules/features enabled by this package. Could map to UI modules or backend services.
plans string[] no Subscription plans / SKUs this package belongs to. If used for billing, clarify naming convention.
roboConnector boolean no Whether a connector component is present. Potentially controls UI placement or runtime permissions.
roboAssistant boolean no Whether an assistant/agent experience is enabled. Likely toggles AI features.
flowBeaconAi boolean no Whether FlowBeacon AI is supported. Guess: internal AI engine flag.
available boolean no Whether this package is available to users. Used to hide in catalogs/environments.
price.credits number no Cost in credits. Only “credits” is defined, other price fields allowed.
tags string[] no Search/filter tags. Use consistent taxonomy.
license string no License identifier (SPDX or internal). Consider standardizing to SPDX IDs later.
description string no Package description for UI/catalog.
* any no Custom package metadata. Extensible — unknown fields allowed.
Example 
{
  "key": "robo-compliance-suite",
  "name": "Robo Compliance Suite",
  "version": "1.4.0",
  "type": "suite",
  "entry": "/dashboard",
  "workflows": ["kyc-onboarding-v2", "vendor-risk-review"],
  "regulations": ["gdpr-eu-2016-679", "aml-5-eu"],
  "integrations": ["slack", "google-drive", "stripe"],
  "available": true,
  "price": { "credits": 1200 },
  "tags": ["compliance", "risk", "automation"],
  "license": "Commercial",
  "description": "Prebuilt workflows and regulations for compliance operations."
}

integration.schema.json

Draft-07 • type: integration additionalProperties: true required: type, name

Purpose (best guess)

Defines an external integration (provider/service) and its supported hooks/endpoints for Robo automations. Think “connector metadata + callable hooks”.

“Determinant” fields

  • type must be "integration" (strong discriminator).
  • name is the human label; consider adding a separate key later if you need stable IDs.
  • hooks[] are the actionable entry points (API methods/callbacks).
Field reference
Field Type Required Description (guess) Notes / constraints
type const "integration" yes Discriminator for integration documents. If this differs in legacy files, add a migration step.
name string yes Integration display name. Not guaranteed unique by schema; you may want uniqueness at runtime.
scope string no Permission scope string (OAuth scopes or internal permission set). Example: "read:files write:files" or "files:read".
support_url string no Support/help documentation URL for the integration. Schema does not require URL format; consider enforcing later.
auth_url string no Authorization endpoint / setup URL. Used to start OAuth or connect flow.
requirements string[] no Backend requirements/dependencies. Example: required secrets, packages, or runtime services.
front_requirements string[] no Frontend requirements/dependencies. Example: feature flags, UI modules.
ai boolean no Whether this integration provides AI-related capabilities. May affect routing to “agent” tools.
front boolean no Whether this integration has frontend/UI components.
payment boolean no Whether this integration handles payments/billing.
need_oauth boolean no Whether OAuth is required to use the integration. Used to gate hooks until connected.
hooks object[] no List of supported “hooks” (callable endpoints or event handlers). Each hook requires name, method, hook.
hooks[].name string yes* Hook name (human label). *Required within hook objects.
hooks[].method string yes* HTTP method or action verb (GET, POST, etc.). Consider standardizing to uppercase.
hooks[].hook string yes* Hook path or identifier. Could be URL path, event key, or internal hook id.
hooks[].description string no Human description of the hook.
hooks[].content any no Request/response schema, sample payload, or content negotiation. Unspecified; document your internal convention.
hooks[].action any no Runtime action mapping (e.g., controller/service call). Likely a structured object in real usage.
* any no Custom extension fields. Extensible — unknown fields allowed.
Example 
{
  "type": "integration",
  "name": "Slack",
  "scope": "chat:write channels:read",
  "support_url": "https://example.com/support/slack",
  "auth_url": "https://example.com/oauth/slack",
  "need_oauth": true,
  "front": true,
  "hooks": [
    {
      "name": "Post message",
      "description": "Send a message to a channel.",
      "method": "POST",
      "hook": "/slack/chat.postMessage",
      "content": {
        "input": { "channel": "string", "text": "string" }
      }
    }
  ]
}

manifest.schema.json

Draft-07 • type: web-app additionalProperties: false required: type, name, icon, entry_url

Purpose (best guess)

A strict manifest describing a deployable “Robo package” web application: how it launches, what it exposes, and what auxiliary services must be started.

Strict schema

Unlike most other schemas here, this one sets additionalProperties: false. That means any unknown top-level keys (or unknown keys inside strict objects) should fail validation.

Field reference
Field Type Required Description (guess) Notes / constraints
type const "web-app" yes Discriminator for web-app package manifests.
name string yes Package app name. minLength 1
description string no Optional description.
icon string yes Icon asset path or identifier. minLength 1
entry_url string yes Relative URL path where the app is served / starts. Must start with / (pattern ^/).
controllers object no Logical action → Symfony controller service mapping. Keys must match ^[A-Za-z0-9_.-]+$; values are non-empty strings.
bootstrap object no Declarative instructions to launch auxiliary services/shells and document env vars. Strict object; only services and environment allowed.
bootstrap.services object[] no Processes to launch alongside the web app. Each service requires id, type, command.
bootstrap.services[].type enum yes* Service kind. One of node-service, electron-shell, native-shell.
bootstrap.services[].command string yes* Command to execute. Example: "node server.js" or "./bin/worker".
bootstrap.services[].args string[] no Command args (if you prefer split command + args).
bootstrap.services[].cwd string no Working directory.
bootstrap.services[].env object no Static environment variables to set for the process. Keys must be uppercase env var names ^[A-Z_][A-Z0-9_]*$. Strict object.
bootstrap.services[].ready_when string no Log message/condition indicating readiness. Used for orchestration and health checks.
bootstrap.environment object no Documentation for env vars that must be provided at runtime. Each env var requires a description; optional required, default.
Example 
{
  "type": "web-app",
  "name": "Robo Desktop Shell",
  "description": "Electron-based desktop wrapper for Robo.",
  "icon": "assets/icon.png",
  "entry_url": "/",
  "controllers": {
    "workflow.run": "App\\Controller\\WorkflowController::run",
    "integration.hook": "App\\Controller\\IntegrationController::hook"
  },
  "bootstrap": {
    "services": [
      {
        "id": "worker",
        "type": "node-service",
        "description": "Background worker for async jobs",
        "command": "node",
        "args": ["./dist/worker.js"],
        "cwd": "./",
        "env": {
          "NODE_ENV": "production"
        },
        "ready_when": "Worker started"
      }
    ],
    "environment": {
      "DATABASE_URL": {
        "description": "Connection string for the database.",
        "required": true
      },
      "SENTRY_DSN": {
        "description": "Sentry DSN for error reporting.",
        "required": false
      }
    }
  }
}

workflow.schema.json

Draft-07 • type: workflow required: type, name, description, steps

Purpose (best guess)

Defines a workflow as an ordered (and possibly branching) set of steps. Steps can be manual, AI-assisted, frontend-driven, robotic, or service-driven.

Important “determinant” fields

  • type must be "workflow".
  • steps[] is the core execution graph. Transition fields (next, next_steps, roads) determine flow.
  • field_details[] and fields[] define data inputs/outputs the workflow expects.
  • need_project, need_client, need_payment are gating conditions.
Top-level fields
Field Type Required Description (guess) Notes / constraints
type enum ["workflow"] yes Discriminator for workflows.
name string yes Workflow name. Human-readable; use unique naming or pair with an external ID.
description string yes Workflow purpose / description.
version string | number no Workflow version (optional). Nullable true.
category string no Grouping/category label. Nullable true.
fields string[] no List of field names relevant to this workflow. Nullable true; may be legacy with field_details being richer.
field_details object[] no Detailed field schema for workflow inputs/outputs. Each requires: name, type, direction.
steps object[] yes Step graph definition. Each step requires at least name.
need_project boolean no Whether a project context must exist to run. Nullable true.
need_client boolean no Whether a client/customer context is required. Nullable true.
need_payment boolean no Whether payment is required before/during workflow. Nullable true.
Step fields (common)

The step object is large. Here are the most impactful fields you’ll likely care about when implementing engines and UIs.

Field Type Required Description (guess) Notes / constraints
steps[].name string yes* Human label for the step. *Required by schema.
steps[].id / steps[].step_id string no Stable identifier for referencing steps. Nullable true; choose one as canonical and migrate (recommend step_id or id consistently).
steps[].action string | null no Action key executed at this step. Could map to controller, service type, integration hook, or robot command.
steps[].group string no Step group for UI grouping or responsibility domain. Nullable true.
steps[].next string | null no Next step id (simple linear progression). If you use next_steps / roads, document precedence rules.
steps[].next_steps string[] no Possible next steps (branching). Nullable true. May be used with condition or user choice.
steps[].roads[] object[] no Explicit transitions (“roads”) with metadata (optional/cancelable/changeable). Each road has required type; optional to.
steps[].optional boolean no Whether the step can be skipped. Combine with all_needed/use_all semantics if present.
steps[].required_manual boolean no Requires manual handling by a user (not automated). Nullable true.
steps[].possible_ai, possible_frontend, possible_robots, possible_service boolean no Capabilities: which executor types can perform the step. Used for routing and UI badges.
steps[].actor.group string|null no Owning/assigned actor group. Nullable true; likely maps to roles/teams.
steps[].interaction.mode string no Interaction mode (e.g., chat, form, email, webhook). Nullable true; clarify supported modes in your system.
steps[].input_fields / output_fields string[] no Fields consumed/produced at this step. Connects to top-level field_details.
steps[].decorators[] object[] no Pluggable behavior wrappers. Each decorator requires name. Examples: validation, notifications, audit log.
steps[].condition string no Condition expression to enable step or choose path. Document expression language (e.g., JS, CEL, JSONPath).
steps[].parallel boolean no Whether the step may execute in parallel. Nullable true; defines concurrency behavior.
steps[].service_type string no Which internal service handles this step (if any). Nullable true; could map to “email-service”, “ocr-service”, etc.
Example 
{
  "type": "workflow",
  "name": "Vendor onboarding",
  "description": "Collect vendor data, run checks, and approve onboarding.",
  "version": "2.0",
  "category": "Procurement",
  "field_details": [
    { "name": "vendor_name", "type": "string", "direction": "input" },
    { "name": "vendor_email", "type": "string", "direction": "input" },
    { "name": "risk_score", "type": "number", "direction": "output", "aggregation": "max" }
  ],
  "need_client": true,
  "steps": [
    {
      "step_id": "collect",
      "name": "Collect vendor information",
      "action": "form.collectVendor",
      "possible_frontend": true,
      "output_fields": ["vendor_name", "vendor_email"],
      "next": "screen"
    },
    {
      "step_id": "screen",
      "name": "Screen vendor",
      "action": "service.vendorScreening",
      "possible_service": true,
      "input_fields": ["vendor_name", "vendor_email"],
      "output_fields": ["risk_score"],
      "roads": [
        { "type": "approve", "to": "approve", "optional": false, "cancelable": false, "changeable": false },
        { "type": "reject", "to": "reject", "optional": false, "cancelable": false, "changeable": false }
      ]
    },
    { "step_id": "approve", "name": "Approve vendor", "required_manual": true },
    { "step_id": "reject", "name": "Reject vendor", "required_manual": true }
  ]
}

regulation.schema.json

Draft-07 • type: regulation | regulations additionalProperties: (unspecified)

Purpose (best guess)

Defines a regulation (or regulation bundle) including applicability rules, requirements, tasks, audit rules, and AI-adaptive fields used for compliance automation and documentation.

Note

The provided schema does not declare a top-level required list, so most fields are optional. In reality you’ll likely enforce additional “business required” fields (e.g., title, jurisdiction, version).

Core metadata and applicability
Field Type Description (guess) Notes
type enum ["regulation","regulations"] Discriminator for regulation documents. Use "regulation" for a single rule set; reserve "regulations" for collections if needed.
regulation_id string Unique ID for referencing the regulation. Recommend stable slug.
templateId string Template identifier used to render documents/forms for this regulation. Guess: links to a document template in your system.
title string Display title.
description string Human summary of what the regulation requires.
jurisdiction string | {country, region?} Where the regulation applies. If object form, country is required.
jurisdiction_match string[] Match keys used to determine applicability (jurisdiction). Likely compared to company/project metadata.
sector_match string[] Match keys for sector applicability.
product_type_in string[] Allowed/target product types for applicability.
company_size string Company size band for applicability. Consider enum later (SMB, mid-market, enterprise).
industry string Industry label used for applicability and grouping.
version string Regulation version. May be legal version or internal content version.
effective_date date-time When regulation takes effect (timestamp). ISO date-time.
effective_from date When regulation takes effect (date only). ISO date.
updated_on date Last updated date.
scope object Structured scope: sectors, product categories, jurisdictions. Useful for UI filters and matching logic.
autofillRules {string: string} Map of field → autofill expression/value. Document expression language (templates, JSONPath, etc.).
Requirements, tasks, and certificates
Field Type Description (guess) Notes
requirements[] object[] Atomic compliance requirements. Each requires: id, description. Optional: check, frequency.
tasks[] object[] Operational tasks needed to meet requirements. Each requires: task_id, status. Dates: deadline (date-time), due_date (date).
recommended_tasks[] tasks[] items Suggested tasks (same shape as tasks). Use to pre-populate projects or recommend improvements.
linkedCertificates[] string[] IDs/names of certificates relevant to the regulation. Used for compliance evidence management.
certificate_management object Rules around certificate requirements and expiry enforcement. Fields include: required_certificates, expiry interval, auto block.
document_requirements[] string[] Document types/IDs required as evidence.
required_workflows[] string[] Workflow IDs that must be completed for compliance. Likely references workflow files or meta.workflows entries.
Audit rules, risks, and enforcement
Field Type Description (guess) Notes
audit_rules object Audit logging and security requirements. Includes log retention period, encryption requirements, MFA, role restrictions, etc.
audit_trail object Whether audit trail is enabled and record storage. Contains enabled and records[].
manual_override object Defines override mechanisms (checkbox, comment required). Used to allow exceptions with traceability.
risks[] object[] Identified risks and mitigation steps. May be used for risk scoring and auto-block behavior.
affected_components[] object[] System/components impacted by the regulation. Useful for impact analysis and change management.
obligations object Operational obligations (reporting frequency, payment due day, retention days).
AI-adaptive and intelligent flows
Field Type Description (guess) Notes
ai_adaptive_fields[] object[] Dynamic fields that can change requirements based on context. Fields include required_if, dynamic_suggestion, context_dependencies, options, validation, fallback, editable.
intelligent_flows[] object[] Event-driven flows: if event + conditions, then actions. Each requires: event, actions.
custom_flow object Custom task flow graph. Contains start_task and flow_steps.
Example 
{
  "type": "regulation",
  "regulation_id": "gdpr-eu-2016-679",
  "title": "GDPR (EU) 2016/679",
  "description": "General Data Protection Regulation.",
  "jurisdiction": { "country": "EU" },
  "sector_match": ["all"],
  "version": "2016/679",
  "effective_from": "2018-05-25",
  "requirements": [
    { "id": "gdpr-1", "description": "Maintain a record of processing activities.", "frequency": "annual" },
    { "id": "gdpr-2", "description": "Implement data subject request handling.", "frequency": "ongoing" }
  ],
  "audit_rules": {
    "log_all_document_changes": true,
    "log_retention_period_days": 365,
    "encryption_required": true,
    "access_control": {
      "role_restrictions": ["compliance_admin"],
      "multi_factor_authentication": true
    }
  },
  "ai_adaptive_fields": [
    {
      "field": "data_categories",
      "type": "string",
      "description": "What data categories are processed?",
      "options": ["personal", "sensitive", "financial"],
      "required": true,
      "editable": true
    }
  ]
}

goal.schema.json

Draft-07 • type: goal required: type, code, name, candidates, plan

Purpose (best guess)

Defines a high-level “goal” for an orchestrator/agent: the goal has candidate strategies (workflows, playbooks, other goals), a selection plan, optional context mapping, and success metrics.

“Determinant” fields

  • code is the stable identifier used for references (candidates[].ref).
  • candidates[] define what can be executed to satisfy the goal.
  • plan.strategy determines how candidates are selected.
Field reference
Field Type Required Description (guess) Notes / constraints
type enum ["goal"] yes Discriminator for goal documents.
code string yes Stable ID for the goal. Recommend slug format; used in references.
name string yes Human-readable goal name.
description string no Optional detailed description. Nullable true.
tags string[] no Tags for grouping/search. Nullable true.
context_map object no Parent context → child input mapping. Values may be literals, JSONPath-like references ($.path), or templates ({{var}}). Document your templating rules.
candidates object[] yes Candidate executables (goal/playbook/workflow) that can satisfy this goal. Each requires ref.
candidates[].ref string yes* Reference code of a goal/workflow/playbook. *Required within candidates.
candidates[].type enum ["goal","playbook","workflow"] no Optional explicit candidate type. If omitted, infer from referenced asset.
candidates[].inputs object no Preset inputs passed to the referenced candidate. Nullable true; schema allows arbitrary keys.
candidates[].required_inputs string[] no Inputs that must be provided before execution. Nullable true.
candidates[].selector object no Selection filter/constraints for when this candidate applies. Nullable true; custom structure.
candidates[].scorer object no Scoring config used to rank candidates. Nullable true; custom structure.
plan.strategy enum yes* How to select candidates. One of firstMatch, topN-by-score, portfolio.
plan.N integer no Number of candidates to select (for topN/portfolio strategies). Minimum 1; nullable true.
success_metrics[] object[] no Metrics used to evaluate goal success. Each requires: key, direction (up/down), target. Optional window (ISO duration).
Example 
{
  "type": "goal",
  "code": "onboard-vendor",
  "name": "Onboard a vendor",
  "description": "Select the best onboarding workflow for the current vendor context.",
  "tags": ["procurement", "onboarding"],
  "context_map": {
    "vendor.name": "$.vendor_name",
    "vendor.email": "$.vendor_email"
  },
  "candidates": [
    {
      "ref": "vendor-onboarding-v2",
      "type": "workflow",
      "required_inputs": ["vendor_name", "vendor_email"],
      "selector": { "if": ["$.country == 'DE'"] },
      "scorer": { "weights": { "speed": 0.3, "risk": 0.7 } }
    },
    {
      "ref": "vendor-onboarding-basic",
      "type": "workflow"
    }
  ],
  "plan": { "strategy": "topN-by-score", "N": 1 },
  "success_metrics": [
    { "key": "time_to_complete", "direction": "down", "target": "P2D" },
    { "key": "risk_score", "direction": "down", "target": 30 }
  ]
}

Next improvements you can do (easy wins):

  • Add a key (stable ID) to schemas that currently use only name (e.g., integrations).
  • Standardize expression languages for condition (workflow) and autofillRules (regulation).
  • Decide canonical step identifier (id vs step_id) and enforce it.
  • Auto-generate the “type / required / constraints” parts from schemas and keep only the “meaning” sections manually written.