{"slug":"platform/UNIFIED_REGISTRY_SCHEMA","title":"Unified Registry Schema","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/UNIFIED_REGISTRY_SCHEMA.mdx","bytes":14750,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED REGISTRY SNAPSHOT.** This file is a source for registry\n> concepts but is not the canonical schema or credential/auth contract. Use\n> [`../architecture/IMPLEMENTATION_CONTRACT_v1.1.md`](../architecture/IMPLEMENTATION_CONTRACT_v1.1.md)\n> and the typed registry packages/code.\n\nOriginal status: CANONICAL\nScope: Single source of truth for all platform registries — credentials, connectors, MCP, ADK, capabilities.\nLast Updated: 2026-07-25\n\n---\n\n## Registry Architecture\n\nAll registries share a common envelope:\n\n```yaml\nregistry:\n  id: string          # unique identifier\n  version: string     # semver\n  updated_at: string  # ISO 8601\n  tenant_id: string   # null for platform-wide registries\n  metadata:\n    owner: string     # team or service responsible\n    environment: \"development\" | \"staging\" | \"production\"\n```\n\n---\n\n## 1. Credential Registry\n\n### Purpose\n\nTrack every secret, key, and credential across the platform. Answers: what exists, where it lives, who uses it, when it rotates.\n\n### Schema\n\n```yaml\ncredentials:\n  <credential_id>:\n    # Identity\n    name: string                    # human-readable name\n    type: \"api_key\" | \"secret\" | \"token\" | \"connection_string\" | \"certificate\" | \"webhook_secret\"\n\n    # Classification\n    category: \"platform\" | \"tenant\" | \"connector\" | \"service\" | \"webhook\" | \"infrastructure\"\n    sensitivity: \"public\" | \"internal\" | \"confidential\" | \"secret\"\n\n    # Storage\n    storage:\n      provider: \"doppler\" | \"cloudflare_secrets\" | \"vercel_env\" | \"d1\" | \"encrypted_kv\"\n      path: string                  # location within provider\n      encrypted: boolean\n\n    # Distribution\n    consumers:                      # which services receive this\n      - service: string             # e.g., \"gateway\", \"loader\", \"knowledge\"\n        environment: string\n        required: boolean\n\n    # Lifecycle\n    created_at: string\n    expires_at: string | null\n    rotation:\n      policy: \"manual\" | \"90d\" | \"30d\" | \"on_demand\"\n      last_rotated: string | null\n      next_rotation: string | null\n\n    # Audit\n    last_used_at: string | null\n    usage_count: number\n    compromised: boolean\n    compromised_at: string | null\n```\n\n### Example\n\n```yaml\ncredentials:\n  descope_management_key:\n    name: \"Descope Management Key\"\n    type: \"api_key\"\n    category: \"platform\"\n    sensitivity: \"secret\"\n    storage:\n      provider: \"doppler\"\n      path: \"/integratewise/prd_web-unified/DESCOPE_MANAGEMENT_KEY\"\n      encrypted: true\n    consumers:\n      - service: \"gateway\"\n        environment: \"production\"\n        required: true\n      - service: \"mcp-connector\"\n        environment: \"production\"\n        required: false\n    rotation:\n      policy: \"90d\"\n      last_rotated: \"2026-06-15T00:00:00Z\"\n      next_rotation: \"2026-09-13T00:00:00Z\"\n    compromised: false\n```\n\n---\n\n## 2. Connector Registry\n\n### Purpose\n\nCatalog all integrations available to tenants. Answers: what connectors exist, what they do, how they authenticate, what data they sync.\n\n### Schema\n\n```yaml\nconnectors:\n  <connector_id>:\n    # Identity\n    name: string\n    slug: string                    # URL-safe identifier\n    description: string\n    category: \"crm\" | \"project_management\" | \"communication\" | \"finance\" | \"analytics\" | \"storage\" | \"custom\"\n\n    # Provider\n    provider:\n      name: string                  # e.g., \"salesforce\", \"jira\", \"slack\"\n      website: string\n      logo_url: string\n\n    # Authentication\n    auth:\n      type: \"oauth2\" | \"api_key\" | \"basic\" | \"bearer\" | \"webhook\"\n      oauth_config:\n        authorize_url: string\n        token_url: string\n        scopes: string[]\n        redirect_uri_template: string\n      credential_ref: string       # points to credential registry\n\n    # Data Model\n    sync:\n      direction: \"inbound\" | \"outbound\" | \"bidirectional\"\n      entities:                     # what objects are synced\n        - name: string\n          fields: string[]\n          primary_key: string\n          sync_frequency: \"realtime\" | \"hourly\" | \"daily\" | \"manual\"\n      webhooks:\n        - event: string\n          endpoint: string\n          secret_ref: string        # points to credential registry\n\n    # Status\n    status: \"available\" | \"beta\" | \"deprecated\" | \"disabled\"\n    installed_by_count: number\n    last_sync_at: string | null\n\n    # Publishing\n    published:\n      marketplace: boolean\n      visibility: \"public\" | \"private\" | \"unlisted\"\n      approved_at: string | null\n      approved_by: string | null\n```\n\n### Example\n\n```yaml\nconnectors:\n  salesforce:\n    name: \"Salesforce CRM\"\n    slug: \"salesforce\"\n    description: \"Bidirectional sync with Salesforce CRM\"\n    category: \"crm\"\n    provider:\n      name: \"Salesforce\"\n      website: \"https://salesforce.com\"\n      logo_url: \"/icons/salesforce.svg\"\n    auth:\n      type: \"oauth2\"\n      oauth_config:\n        authorize_url: \"https://login.salesforce.com/services/oauth2/authorize\"\n        token_url: \"https://login.salesforce.com/services/oauth2/token\"\n        scopes: [\"api\", \"refresh_token\"]\n        redirect_uri_template: \"https://gateway.integratewise.ai/api/v1/connectors/{slug}/callback\"\n      credential_ref: \"salesforce_oauth_client\"\n    sync:\n      direction: \"bidirectional\"\n      entities:\n        - name: \"Account\"\n          fields: [\"Id\", \"Name\", \"Industry\", \"ARR__c\", \"Health_Score__c\"]\n          primary_key: \"Id\"\n          sync_frequency: \"hourly\"\n        - name: \"Contact\"\n          fields: [\"Id\", \"FirstName\", \"LastName\", \"Email\", \"AccountId\"]\n          primary_key: \"Id\"\n          sync_frequency: \"hourly\"\n      webhooks:\n        - event: \"account.updated\"\n          endpoint: \"/api/v1/webhooks/salesforce\"\n          secret_ref: \"salesforce_webhook_secret\"\n    status: \"available\"\n    installed_by_count: 23\n    published:\n      marketplace: true\n      visibility: \"public\"\n```\n\n---\n\n## 3. MCP Registry\n\n### Purpose\n\nCatalog all MCP tools and resources available to agents. Answers: what tools exist, what they do, what they require, how they're invoked.\n\n### Schema\n\n```yaml\nmcp_registry:\n  tools:\n    <tool_id>:\n      # Identity\n      name: string\n      description: string\n      category: \"spine\" | \"connector\" | \"memory\" | \"governance\" | \"analytics\" | \"custom\"\n\n      # Interface\n      input_schema: object          # JSON Schema for inputs\n      output_schema: object         # JSON Schema for outputs\n\n      # Requirements\n      requires:\n        auth: boolean\n        tenant_scoped: boolean\n        permissions: string[]       # required roles\n        capabilities: string[]      # required capability registry entries\n\n      # Runtime\n      implementation:\n        worker: string              # which CF worker serves this\n        timeout_ms: number\n        retry_policy: \"none\" | \"exponential\" | \"fixed\"\n\n      # Health\n      status: \"available\" | \"degraded\" | \"unavailable\"\n      last_health_check: string | null\n      avg_latency_ms: number\n      error_rate: number\n\n      # Versioning\n      version: string\n      deprecated: boolean\n      replaced_by: string | null\n\n  resources:\n    <resource_id>:\n      name: string\n      description: string\n      type: \"read\" | \"write\" | \"subscribe\"\n      schema: object\n      required_tools: string[]\n```\n\n### Example\n\n```yaml\nmcp_registry:\n  tools:\n    spine_query:\n      name: \"Query Spine Entity\"\n      description: \"Query entities from the Spine store by type, filters, and pagination\"\n      category: \"spine\"\n      input_schema:\n        type: \"object\"\n        properties:\n          entity_type: { type: \"string\" }\n          filters: { type: \"object\" }\n          limit: { type: \"integer\", default: 50 }\n        required: [\"entity_type\"]\n      output_schema:\n        type: \"object\"\n        properties:\n          entities: { type: \"array\" }\n          total: { type: \"integer\" }\n          has_more: { type: \"boolean\" }\n      requires:\n        auth: true\n        tenant_scoped: true\n        permissions: [\"read:entities\"]\n      implementation:\n        worker: \"integratewise-spine\"\n        timeout_ms: 5000\n        retry_policy: \"exponential\"\n      status: \"available\"\n      version: \"1.0.0\"\n```\n\n---\n\n## 4. ADK Registry\n\n### Purpose\n\nCatalog agent definitions and their capabilities. Answers: what agents exist, what they can do, how they're triggered, what resources they use.\n\n### Schema\n\n```yaml\nadk_registry:\n  agents:\n    <agent_id>:\n      # Identity\n      name: string\n      description: string\n      type: \"twin\" | \"specialist\" | \"orchestrator\" | \"swarm\"\n\n      # Capabilities\n      capabilities: string[]        # references to capability registry\n      mcp_tools: string[]           # references to MCP registry\n\n      # Triggers\n      triggers:\n        - type: \"event\" | \"schedule\" | \"manual\" | \"handoff\"\n          config: object\n\n      # Resources\n      memory:\n        scope: \"tenant\" | \"session\" | \"ephemeral\"\n        max_tokens: number\n      knowledge:\n        sources: string[]           # knowledge base references\n\n      # Governance\n      requires_approval: boolean\n      approval_role: string | null\n      max_actions_per_hour: number\n\n      # Runtime\n      model: string                 # AI model used\n      temperature: number\n      max_tokens: number\n\n      # Status\n      status: \"active\" | \"disabled\" | \"testing\"\n      version: string\n```\n\n### Example\n\n```yaml\nadk_registry:\n  agents:\n    csm_twin:\n      name: \"CSM Twin\"\n      description: \"Customer Success Manager AI agent with full account context\"\n      type: \"twin\"\n      capabilities:\n        - monitor_health\n        - generate_qbr\n        - propose_actions\n        - send_outreach\n      mcp_tools:\n        - spine_query\n        - memory_search\n        - signal_generate\n      triggers:\n        - type: \"event\"\n          config:\n            event: \"account.health_changed\"\n            threshold: 0.3\n        - type: \"schedule\"\n          config:\n            cron: \"0 9 * * 1\" # Every Monday at 9am\n      memory:\n        scope: \"tenant\"\n        max_tokens: 8192\n      governance:\n        requires_approval: true\n        approval_role: \"cs_manager\"\n        max_actions_per_hour: 10\n      model: \"claude-sonnet-4-20250514\"\n      temperature: 0.3\n      status: \"active\"\n      version: \"1.0.0\"\n```\n\n---\n\n## 5. Capability Registry\n\n### Purpose\n\nDefine executable capability contracts. Answers: what a capability does, what it needs, what it produces, who can invoke it.\n\n### Schema\n\n```yaml\ncapability_registry:\n  capabilities:\n    <capability_id>:\n      # Identity\n      name: string\n      description: string\n      domain: \"revenue\" | \"csm\" | \"finance\" | \"people\" | \"operations\" | \"marketing\"\n\n      # Workflow\n      steps:\n        - id: string\n          name: string\n          handler: \"ai\" | \"human\" | \"system\" | \"hybrid\"\n          requires_approval: boolean\n          timeout_ms: number\n\n      # Data Requirements\n      requires_data:\n        - entity_type: string\n          fields: string[]\n          must_exist: boolean\n      requires_signals:\n        - signal_type: string\n          threshold: number\n          time_window_days: number\n\n      # Permissions\n      permissions:\n        - role: string\n          can_invoke: boolean\n          can_approve: boolean\n          data_access: \"own\" | \"team\" | \"org\"\n\n      # Output\n      produces:\n        type: string\n        fields: Record<string, string>\n        destinations: string[]\n\n      # Governance\n      requires_audit: boolean\n      requires_approval: boolean\n      approval_role: string | null\n\n      # Metrics\n      success_rate_target: number\n      human_approval_rate_target: number\n      typical_duration_ms: number\n\n      # Versioning\n      version: string\n      status: \"active\" | \"deprecated\" | \"testing\"\n      deprecation_notice: string | null\n```\n\n### Example\n\n```yaml\ncapability_registry:\n  capabilities:\n    monitor_account_health:\n      name: \"Monitor Account Health\"\n      description: \"Continuously monitor account health signals and generate alerts\"\n      domain: \"csm\"\n      steps:\n        - id: \"collect_signals\"\n          name: \"Collect Health Signals\"\n          handler: \"system\"\n          requires_approval: false\n          timeout_ms: 30000\n        - id: \"analyze_health\"\n          name: \"AI Health Analysis\"\n          handler: \"ai\"\n          requires_approval: false\n          timeout_ms: 60000\n        - id: \"generate_alert\"\n          name: \"Generate Health Alert\"\n          handler: \"system\"\n          requires_approval: false\n          timeout_ms: 5000\n      requires_data:\n        - entity_type: \"Account\"\n          fields: [\"health_score\", \"last_touch\", \"renewal_date\", \"arr\"]\n          must_exist: true\n      requires_signals:\n        - signal_type: \"engagement_drop\"\n          threshold: 0.3\n          time_window_days: 30\n      permissions:\n        - role: \"csm\"\n          can_invoke: true\n          can_approve: false\n          data_access: \"team\"\n        - role: \"cs_manager\"\n          can_invoke: true\n          can_approve: true\n          data_access: \"org\"\n      produces:\n        type: \"alert\"\n        fields:\n          severity: \"string\"\n          message: \"string\"\n          recommended_action: \"string\"\n        destinations: [\"timeline\", \"email\", \"slack\"]\n      requires_audit: true\n      requires_approval: false\n      success_rate_target: 0.95\n      human_approval_rate_target: 0.0\n      typical_duration_ms: 45000\n      version: \"1.0.0\"\n      status: \"active\"\n```\n\n---\n\n## Cross-Registry Relationships\n\n```\nCredential Registry ←── Connector Registry\n       ↑                      ↓\n  MCP Registry ────→ Capability Registry\n       ↑                      ↓\n  ADK Registry ←──── Agent Runtime\n```\n\n### Relationship Rules\n\n1. **Credential → Connector**: Every connector auth references exactly one credential entry\n2. **Connector → MCP**: Each connector exposes tools via MCP; tool IDs are namespaced: `{connector}:{tool}`\n3. **MCP → Capability**: Capabilities compose MCP tools into workflows\n4. **ADK → Capability**: Agents declare which capabilities they can invoke\n5. **ADK → MCP**: Agents declare which MCP tools they use directly\n6. **All → Credential**: Every registry entry that needs auth references the credential registry\n\n---\n\n## Migration Path\n\n1. **Phase 1**: Populate credential registry from `infrastructure/secrets/registry.yaml` + Doppler\n2. **Phase 2**: Populate connector registry from `infrastructure/config/connectors/catalog.yaml`\n3. **Phase 3**: Populate MCP registry from `infrastructure/config/mcp/tools-registry.yaml`\n4. **Phase 4**: Populate ADK registry from `services/iw-agent-runtime` config\n5. **Phase 5**: Populate capability registry from `packages/core/capability-registry/types.ts` definitions\n6. **Phase 6**: Wire registry APIs: `/api/v1/registries/{type}` for discovery\n"}