ftl-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "FtlConfig",
  "description": "Root configuration structure for ftl.toml",
  "type": "object",
  "required": ["project"],
  "properties": {
    "project": {
      "description": "Project metadata",
      "$ref": "#/$defs/ProjectConfig"
    },
    "oauth": {
      "description": "OpenID Connect authentication configuration (optional)",
      "$ref": "#/$defs/OauthConfig"
    },
    "mcp": {
      "description": "MCP component configuration",
      "$ref": "#/$defs/McpConfig",
      "default": {
        "gateway": "ghcr.io/fastertools/mcp-gateway:0.0.11",
        "authorizer": "ghcr.io/fastertools/mcp-authorizer:0.0.13",
        "validate_arguments": false
      }
    },
    "tools": {
      "description": "Tool definitions",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/ToolConfig"
      },
      "default": {}
    },
    "variables": {
      "description": "Application-level variables",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/ApplicationVariable"
      },
      "default": {}
    }
  },
  "$defs": {
    "ProjectConfig": {
      "description": "Project metadata",
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {
          "description": "Project name (alphanumeric, hyphens, underscores only, must start with letter)",
          "type": "string",
          "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$",
          "minLength": 1
        },
        "version": {
          "description": "Semantic version (e.g., 0.1.0)",
          "type": "string",
          "default": "0.1.0",
          "minLength": 1
        },
        "description": {
          "description": "Project description",
          "type": "string",
          "default": ""
        },
        "authors": {
          "description": "Project authors",
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "access_control": {
          "description": "Access control mode: 'public' (no auth), 'private' (user-level auth), 'org' (organization-wide auth), or 'custom' (custom OAuth)",
          "type": "string",
          "enum": ["public", "private", "org", "custom"],
          "default": "public"
        },
        "default_registry": {
          "description": "Default registry for component references (e.g., 'ghcr.io/myorg')",
          "type": "string",
          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._\\-/]*[a-zA-Z0-9]$",
          "minLength": 1
        }
      }
    },
    "OauthConfig": {
      "description": "OpenID Connect authentication configuration",
      "type": "object",
      "required": ["issuer"],
      "properties": {
        "issuer": {
          "description": "OAuth issuer URL",
          "type": "string",
          "minLength": 1
        },
        "audience": {
          "description": "Expected audience for tokens",
          "type": "string",
          "default": ""
        },
        "jwks_uri": {
          "description": "JWKS endpoint URL (auto-discovered if not set)",
          "type": "string",
          "default": ""
        },
        "public_key": {
          "description": "Public key in PEM format (alternative to JWKS)",
          "type": "string",
          "default": ""
        },
        "algorithm": {
          "description": "JWT signature algorithm (e.g., RS256, ES256)",
          "type": "string",
          "default": ""
        },
        "required_scopes": {
          "description": "Comma-separated list of required scopes",
          "type": "string",
          "default": ""
        },
        "authorize_endpoint": {
          "description": "OAuth authorization endpoint",
          "type": "string",
          "default": ""
        },
        "token_endpoint": {
          "description": "OAuth token endpoint",
          "type": "string",
          "default": ""
        },
        "userinfo_endpoint": {
          "description": "OAuth userinfo endpoint",
          "type": "string",
          "default": ""
        }
      }
    },
    "McpConfig": {
      "description": "MCP component configuration",
      "type": "object",
      "properties": {
        "gateway": {
          "description": "MCP gateway component registry URI",
          "type": "string",
          "default": "ghcr.io/fastertools/mcp-gateway:0.0.11",
          "minLength": 1
        },
        "authorizer": {
          "description": "MCP authorizer component registry URI",
          "type": "string",
          "default": "ghcr.io/fastertools/mcp-authorizer:0.0.13",
          "minLength": 1
        },
        "validate_arguments": {
          "description": "Whether to validate tool call arguments",
          "type": "boolean",
          "default": false
        }
      }
    },
    "ToolConfig": {
      "description": "Tool configuration",
      "type": "object",
      "required": ["wasm"],
      "properties": {
        "path": {
          "description": "Path to tool directory relative to project root (for local tools only, defaults to tool name)",
          "type": "string"
        },
        "wasm": {
          "description": "Path to WASM file (local) or registry reference (e.g., 'ghcr.io/org/component:1.0.0')",
          "type": "string",
          "minLength": 1
        },
        "build": {
          "description": "Build configuration (required for local tools, omitted for registry components)",
          "$ref": "#/$defs/BuildConfig"
        },
        "profiles": {
          "description": "Build profiles (optional, for advanced multi-profile builds)",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/BuildProfile"
          }
        },
        "up": {
          "description": "Up configuration for development mode",
          "$ref": "#/$defs/UpConfig"
        },
        "deploy": {
          "description": "Deployment configuration",
          "$ref": "#/$defs/DeployConfig"
        },
        "allowed_outbound_hosts": {
          "description": "Allowed outbound hosts for the tool",
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "variables": {
          "description": "Tool-specific variables",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "default": {}
        }
      }
    },
    "BuildConfig": {
      "description": "Build configuration for a tool",
      "type": "object",
      "required": ["command"],
      "properties": {
        "command": {
          "description": "Build command to execute",
          "type": "string",
          "minLength": 1
        },
        "watch": {
          "description": "Paths to watch for changes in development mode",
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "env": {
          "description": "Environment variables to set during build",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "default": {}
        }
      }
    },
    "BuildProfile": {
      "description": "A single build profile",
      "type": "object",
      "required": ["command"],
      "properties": {
        "command": {
          "description": "Build command to execute",
          "type": "string",
          "minLength": 1
        },
        "watch": {
          "description": "Paths to watch for changes in development mode",
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": []
        },
        "env": {
          "description": "Environment variables to set during build",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "default": {}
        }
      }
    },
    "UpConfig": {
      "description": "Up configuration for development mode",
      "type": "object",
      "required": ["profile"],
      "properties": {
        "profile": {
          "description": "Build profile to use for 'ftl up'",
          "type": "string",
          "minLength": 1
        }
      }
    },
    "DeployConfig": {
      "description": "Deployment configuration for a tool",
      "type": "object",
      "required": ["profile"],
      "properties": {
        "profile": {
          "description": "Build profile to use for deployment (e.g., release, production)",
          "type": "string",
          "minLength": 1
        },
        "name": {
          "description": "Optional custom name suffix for the deployed tool",
          "type": "string"
        }
      }
    },
    "ApplicationVariable": {
      "description": "Application-level variable configuration",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "default": {
              "description": "Default value for the variable",
              "type": "string"
            }
          },
          "required": ["default"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "required": {
              "description": "Whether the variable is required (must be true)",
              "type": "boolean",
              "const": true
            }
          },
          "required": ["required"],
          "additionalProperties": false
        }
      ]
    }
  }
}