Connector Schema Reference

This document provides the complete, canonical reference for Stack9 Connector schemas based on the official Joi validators in packages/stack9-sdk/src/schema/validators/v2/ConnectorSchemaValidator.ts. This is the single source of truth for all Connector property definitions.

Base Connector Structure

Every connector definition must have these base properties:

{
  "key": "unique_connector_key",       // Required: Unique identifier for the connector
  "name": "Human Readable Name",       // Required: Display name for the connector
  "description": "What this does",     // Required: Description of the connector's purpose
  "type": "connector_type",           // Required: Must match ConnectorType enum exactly
  "module": "module_name",            // Optional: Module association
  "configuration": {}                 // Required: Type-specific configuration (see below)
}

Key Validation Rules

• Must be lowercase - No uppercase letters allowed
• Must be a valid token - Only alphanumeric characters and underscores
• CANNOT start with 'stack9_' - This prefix is reserved for Stack9-managed connectors
• Must be unique - Cannot duplicate existing connector keys

Example

{
  "key": "payment_api",              // ✅ Correct: lowercase, no stack9_ prefix
  "key": "Payment_API",              // ❌ Wrong: contains uppercase
  "key": "stack9_payment",           // ❌ Wrong: starts with stack9_
  "key": "payment-api"               // ❌ Wrong: contains hyphen (not a valid token)
}

Connector Types

The following connector types are supported (values must match exactly):

Connector Type	Enum Value	Description
AMAZON_S3	amazon_s3	AWS S3 object storage
AZURE_BLOB	azure_blob	Azure Blob Storage
FIREBASE	firebase	Firebase Realtime Database
GRAPHQL	graphql	GraphQL API endpoints
MONGO_DB	mongodb	MongoDB database
MSSQL	mssql	Microsoft SQL Server
OPEN_API	open_api	OpenAPI/Swagger APIs
POSTGRESQL	postgresql	PostgreSQL database
REDIS	redis	Redis cache/database
REST_API	rest_api	REST/HTTP APIs
SENDGRID	sendgrid	SendGrid email service
ELASTIC_SEARCH	elastic_search	Elasticsearch search engine
STACK9_API	stack9_api	Stack9 internal API
STACK9_DB	stack9_db	Stack9 database (PostgreSQL or MSSQL)
STACK9_S3	stack9_s3	Stack9-managed S3 storage
STACK9_AZURE	stack9_azure	Stack9-managed Azure storage
STACK9_REDIS	stack9_redis	Stack9-managed Redis
STACK9_MONGO	stack9_mongo	Stack9-managed MongoDB

Note: ConnectorType values from the enum are: amazon_dynamodb, amazon_kms, amazon_opensearch are defined in the enum but not validated in the ConnectorSchemaValidator, so they may not be fully supported.

Authentication Schema

The authentication schema is used by multiple connector types (REST_API, GRAPHQL, OPEN_API, ELASTIC_SEARCH):

{
  "authentication": {
    "type": "basic | apiKey | bearer",     // Required: Authentication type

    // For type = "basic":
    "username": "username",                // Required when type is "basic"
    "password": "password",                // Required when type is "basic"

    // For type = "apiKey":
    "apiKey": "api_key_value",            // Required when type is "apiKey"

    // For type = "bearer":
    "bearer": "token_value"               // Required when type is "bearer"
  }
}

Authentication Options Enum

Auth Type	Enum Value	Required Fields
BASIC	basic	username, password
API_KEY	apiKey	apiKey
BEARER	bearer	bearer

Connector-Specific Configuration Schemas

REST_API

Connect to any REST/HTTP API.

{
  "type": "rest_api",
  "configuration": {
    "baseUrl": "https://api.example.com",     // Required: Base URL for API
    "headers": {                              // Optional: Default headers
      "Accept": "application/json",
      "X-Custom-Header": "value"
    },
    "urlParameters": {                        // Optional: Default URL parameters
      "version": "v1",
      "format": "json"
    },
    "extraBodyValues": {                      // Optional: Default body values
      "source": "stack9",
      "client_id": "abc123"
    },
    "authentication": {                       // Optional: See Authentication Schema
      "type": "bearer",
      "bearer": "%%APP_API_TOKEN%%"
    }
  }
}

POSTGRESQL

Connect to PostgreSQL databases.

{
  "type": "postgresql",
  "configuration": {
    // Option 1: Connection string (mutually exclusive with individual fields)
    "connectionString": "postgresql://user:pass@host:5432/db",

    // Option 2: Individual connection parameters (all required together)
    "host": "database.example.com",           // Required with individual params
    "port": 5432,                            // Required with individual params
    "databaseName": "mydb",                  // Required with individual params
    "databaseUsername": "dbuser",            // Required with individual params
    "databasePassword": "dbpass",            // Required with individual params

    "sslEnabled": true                       // Optional: Enable SSL connection
  }
}

Important: You must use EITHER connectionString OR all individual fields (host, port, databaseName, databaseUsername, databasePassword). They are mutually exclusive.

MSSQL

Connect to Microsoft SQL Server databases.

{
  "type": "mssql",
  "configuration": {
    // Option 1: Connection string (mutually exclusive with individual fields)
    "connectionString": "Server=host;Database=db;User Id=user;Password=pass;",

    // Option 2: Individual connection parameters (all required together)
    "host": "sqlserver.example.com",         // Required with individual params
    "port": 1433,                           // Required with individual params
    "databaseName": "mydb",                 // Required with individual params
    "databaseUsername": "sa",               // Required with individual params
    "databasePassword": "password",         // Required with individual params

    "sslEnabled": false                     // Optional: Enable SSL connection
  }
}

Important: Similar to PostgreSQL, use EITHER connectionString OR all individual fields.

MONGO_DB

Connect to MongoDB databases.

{
  "type": "mongodb",
  "configuration": {
    // Option 1: Connection string (mutually exclusive with host/port)
    "connectionString": "mongodb://user:pass@host:27017/db",

    // Option 2: Individual connection parameters
    "host": "mongodb.example.com",          // Required with port
    "port": 27017,                         // Required with host
    "databaseName": "mydb",                // Optional
    "databaseUsername": "mongouser",       // Optional
    "databasePassword": "mongopass",       // Optional

    "sslEnabled": false                    // Optional: Enable SSL (default: false)
  }
}

Important: When using individual params, host and port are required together. Cannot use connectionString with host/port.

REDIS

Connect to Redis cache/database.

{
  "type": "redis",
  "configuration": {
    "host": "redis.example.com",           // Required: Redis host
    "port": 6379,                         // Required: Redis port
    "password": "redis_password"          // Optional: Redis password
  }
}

AMAZON_S3

Connect to AWS S3 or S3-compatible storage.

{
  "type": "amazon_s3",
  "configuration": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",        // Required: AWS access key
    "secretAccessKeyId": "wJalrXUtnFEMI...",      // Required: AWS secret key
    "bucketName": "my-bucket",                    // Required: S3 bucket name
    "arn": "arn:aws:s3:::my-bucket",             // Optional: Bucket ARN (can be null)
    "isCustomS3Endpoint": false,                  // Optional: Use custom endpoint (default: false)
    "s3ForcePathStyle": false,                    // Optional: Force path-style URLs (default: false)
    "baseUrl": "https://s3.custom.com"           // Required when isCustomS3Endpoint is true
  }
}

Important: baseUrl is only required when isCustomS3Endpoint is true.

AZURE_BLOB

Connect to Azure Blob Storage.

{
  "type": "azure_blob",
  "configuration": {
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=...",  // Required
    "containerName": "my-container"                                        // Required
  }
}

FIREBASE

Connect to Firebase Realtime Database.

{
  "type": "firebase",
  "configuration": {
    "firebaseDatabaseUrl": "https://project.firebaseio.com",    // Required: Database URL
    "firebaseProjectId": "my-project-id",                      // Required: Project ID
    "firebasePrivateKey": "-----BEGIN PRIVATE KEY-----..."     // Required: Service account key
  }
}

GRAPHQL

Connect to GraphQL API endpoints.

{
  "type": "graphql",
  "configuration": {
    "baseUrl": "https://api.example.com/graphql",    // Required: GraphQL endpoint
    "urlParameters": {                               // Optional: URL parameters
      "version": "v2"
    },
    "headers": {                                     // Optional: HTTP headers
      "X-API-Version": "2024-01-01"
    },
    "extraBodyValues": {                            // Optional: Additional body values
      "client": "stack9"
    },
    "authentication": {                              // Optional: See Authentication Schema
      "type": "bearer",
      "bearer": "%%APP_GRAPHQL_TOKEN%%"
    }
  }
}

OPEN_API

Connect to OpenAPI/Swagger specification APIs.

{
  "type": "open_api",
  "configuration": {
    "specificationUrl": "https://api.example.com/openapi.json",  // Required: OpenAPI spec URL
    "basePath": "/v1",                                          // Required: Base path
    "customHeaders": {                                          // Optional: Custom headers
      "X-API-Version": "2024-01-01"
    },
    "customQueryParameters": {                                  // Optional: Custom query params
      "format": "json"
    },
    "authentication": {                                         // Optional: See Authentication Schema
      "type": "apiKey",
      "apiKey": "%%APP_API_KEY%%"
    }
  }
}

SENDGRID

Connect to SendGrid email service.

{
  "type": "sendgrid",
  "configuration": {
    "accessToken": "SG.xxxxxxxxxxxx"              // Required: SendGrid API key
  }
}

ELASTIC_SEARCH

Connect to Elasticsearch clusters.

{
  "type": "elastic_search",
  "configuration": {
    "nodeOrCloudId": "https://es.example.com:9200",    // Required: Node URL or Cloud ID
    "auth": {                                          // Required: See Authentication Schema
      "type": "basic",
      "username": "elastic",
      "password": "changeme"
    }
  }
}

Stack9-Managed Connectors

Stack9 provides managed versions of certain connectors with additional features.

STACK9_API

Access Stack9's internal API with OpenAPI specification.

{
  "type": "stack9_api",
  "configuration": {
    "specificationUrl": "https://api.stack9.io/spec"    // Required: API specification URL
  }
}

STACK9_DB

Stack9's managed database connector supporting both PostgreSQL and MSSQL.

{
  "type": "stack9_db",
  "configuration": {
    "client": "pg | mssql",                           // Required: Database client type

    // Then include either PostgreSQL or MSSQL configuration based on client
    // For client = "pg", use PostgreSQL schema
    // For client = "mssql", use MSSQL schema
  }
}

Stack9DBClient Enum Values

Client	Value	Description
POSTGRESQL	pg	PostgreSQL database
MSSQL	mssql	Microsoft SQL Server

Example with PostgreSQL:

{
  "type": "stack9_db",
  "configuration": {
    "client": "pg",
    "host": "localhost",
    "port": 5432,
    "databaseName": "stack9",
    "databaseUsername": "stack9user",
    "databasePassword": "password",
    "sslEnabled": true
  }
}

STACK9_S3

Stack9-managed S3 storage with public access control.

{
  "type": "stack9_s3",
  "configuration": {
    // All AMAZON_S3 configuration properties plus:
    "isPublic": false                               // Optional: Public access (default: false)
  }
}

STACK9_AZURE

Stack9-managed Azure Blob storage with public access control.

{
  "type": "stack9_azure",
  "configuration": {
    // All AZURE_BLOB configuration properties plus:
    "isPublic": false                               // Optional: Public access (default: false)
  }
}

STACK9_REDIS

Stack9-managed Redis (identical to REDIS configuration).

{
  "type": "stack9_redis",
  "configuration": {
    "host": "redis.stack9.internal",
    "port": 6379,
    "password": "redis_password"
  }
}

STACK9_MONGO

Stack9-managed MongoDB (identical to MONGO_DB configuration).

{
  "type": "stack9_mongo",
  "configuration": {
    "connectionString": "mongodb://user:pass@host:27017/db"
  }
}

Environment Variables

Use the %%VARIABLE_NAME%% syntax to inject environment variables securely:

{
  "configuration": {
    "baseUrl": "%%APP_API_URL%%",
    "authentication": {
      "type": "bearer",
      "bearer": "%%APP_API_TOKEN%%"
    }
  }
}

Complete Examples

REST API with Bearer Authentication

{
  "key": "payment_gateway",
  "name": "Payment Gateway",
  "description": "Stripe payment processing API",
  "type": "rest_api",
  "configuration": {
    "baseUrl": "%%APP_STRIPE_API_URL%%",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "authentication": {
      "type": "bearer",
      "bearer": "%%APP_STRIPE_SECRET_KEY%%"
    }
  }
}

PostgreSQL with Connection String

{
  "key": "analytics_db",
  "name": "Analytics Database",
  "description": "PostgreSQL analytics database",
  "type": "postgresql",
  "configuration": {
    "connectionString": "%%APP_ANALYTICS_DB_URL%%",
    "sslEnabled": true
  }
}

MongoDB with Individual Parameters

{
  "key": "document_store",
  "name": "Document Store",
  "description": "MongoDB document database",
  "type": "mongodb",
  "configuration": {
    "host": "%%APP_MONGO_HOST%%",
    "port": 27017,
    "databaseName": "documents",
    "databaseUsername": "%%APP_MONGO_USER%%",
    "databasePassword": "%%APP_MONGO_PASSWORD%%",
    "sslEnabled": true
  }
}

S3-Compatible Storage (MinIO)

{
  "key": "file_storage",
  "name": "File Storage",
  "description": "MinIO S3-compatible storage",
  "type": "amazon_s3",
  "configuration": {
    "accessKeyId": "%%APP_MINIO_ACCESS_KEY%%",
    "secretAccessKeyId": "%%APP_MINIO_SECRET_KEY%%",
    "bucketName": "documents",
    "isCustomS3Endpoint": true,
    "s3ForcePathStyle": true,
    "baseUrl": "%%APP_MINIO_ENDPOINT%%"
  }
}

Validation Error Messages

Key Validation Errors

Error	Cause	Solution
Connector key 'stack9_custom' cannot start with 'stack9_'	Key starts with reserved prefix	Use a different prefix
"key" must only contain alpha-numeric and underscore characters	Invalid characters in key	Use only a-z, 0-9, and _
"key" must only contain lowercase characters	Uppercase letters in key	Convert to lowercase

Configuration Validation Errors

Error	Cause	Solution
"connectionString" conflict with forbidden peer "host"	Using both connection string and individual params	Use either connectionString OR individual params
"host" missing required peer "port"	Missing required paired field	Include all required fields when using individual params
"baseUrl" is required	Missing baseUrl when isCustomS3Endpoint is true	Add baseUrl configuration

Best Practices

1. Always use environment variables for sensitive data (passwords, API keys, tokens)
2. Choose the right connection method - connection strings for simplicity, individual params for flexibility
3. Enable SSL for production database connections
4. Use descriptive keys that indicate the service purpose (e.g., payment_api, not api1)
5. Document your connectors with clear descriptions
6. Test connectivity before deploying to production
7. Validate required fields based on connector type
8. Follow naming conventions - lowercase with underscores for keys

Related Documentation

• Connectors Concept Guide - High-level overview and usage patterns
• Query Library Schema Reference - Query templates for each connector
• Integrating External APIs Guide - Practical integration examples