@aifabrix/builder 2.40.0 → 2.41.0

package/lib/schema/external-system.schema.json

@@ -1,430 +1,452 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json",
-  "title": "AI Fabrix External System Configuration Schema",
-  "description": "Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, OpenAPI/MCP bindings, field mappings defaults, metadata handling and portal inputs.",
-  "metadata": {
-    "key": "external-system-schema",
-    "name": "External System Configuration Schema",
-    "description": "JSON schema for validating ExternalSystem configuration files",
-    "version": "1.2.0",
-    "type": "schema",
-    "category": "integration",
-    "author": "AI Fabrix Team",
-    "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2025-12-01T00:00:00Z",
-    "compatibility": {
-      "minVersion": "1.0.0",
-      "maxVersion": "2.0.0",
-      "deprecated": false
-    },
-    "tags": [
-      "schema",
-      "external-system",
-      "dataplane",
-      "integration",
-      "validation"
-    ],
-    "dependencies": [],
-    "changelog": [
-      {
-        "version": "1.2.0",
-        "date": "2025-02-01T00:00:00Z",
-        "changes": [
-          "Added generateMcpContract (boolean, default true): config-only control for MCP contract generation on publish",
-          "Added generateOpenApiContract (boolean, default true): reserved for future use"
-        ],
-        "breaking": false
-      },
-      {
-        "version": "1.1.0",
-        "date": "2025-12-01T00:00:00Z",
-        "changes": [
-          "Added RBAC roles and permissions support",
-          "RBAC roles/permissions are registered with miso-controller during deployment",
-          "Roles support Azure AD group mapping via Groups property",
-          "Permissions reference roles and are used for access control"
-        ],
-        "breaking": false
-      },
-      {
-        "version": "1.0.0",
-        "date": "2024-01-01T00:00:00Z",
-        "changes": [
-          "Initial schema for External Systems",
-          "Added OpenAPI and MCP contract configuration",
-          "Added authentication and environment variables",
-          "Added portalInput for UI-driven onboarding",
-          "Compatible with field-mappings.schema and security-model.schema"
-        ],
-        "breaking": false
-      }
-    ]
+  "$schema":"http://json-schema.org/draft-07/schema#",
+  "$id":"https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/external-system.schema.json",
+  "title":"AI Fabrix External System Configuration Schema",
+  "description":"Schema for configuring an external system connected to the AI Fabrix Dataplane. This defines authentication, OpenAPI/MCP bindings, field mappings defaults, metadata handling and portal inputs.",
+  "metadata":{
+     "key":"external-system-schema",
+     "name":"External System Configuration Schema",
+     "description":"JSON schema for validating ExternalSystem configuration files",
+     "version":"1.3.0",
+     "type":"schema",
+     "category":"integration",
+     "author":"AI Fabrix Team",
+     "createdAt":"2024-01-01T00:00:00Z",
+     "updatedAt":"2026-02-18T00:00:00Z",
+     "compatibility":{
+        "minVersion":"1.3.0",
+        "maxVersion":"2.0.0",
+        "deprecated":false
+     },
+     "tags":[
+        "schema",
+        "external-system",
+        "dataplane",
+        "integration",
+        "validation"
+     ],
+     "dependencies":[
+        
+     ],
+     "changelog":[
+        {
+           "version":"1.3.0",
+           "date":"2026-02-18T00:00:00Z",
+           "changes":[
+              "Template-based authentication: method, variables (baseUrl when method not none), security (kv:// only), credentialKey, writeOnce",
+              "Credential created on deploy as authentication.credentialKey or <external-system.key>-cred"
+           ]
+        },
+        {
+           "version":"1.2.0",
+           "date":"2025-02-01T00:00:00Z",
+           "changes":[
+              "Added generateMcpContract (boolean, default true): config-only control for MCP contract generation on publish",
+              "Added generateOpenApiContract (boolean, default true): reserved for future use"
+           ],
+           "breaking":false
+        },
+        {
+           "version":"1.1.0",
+           "date":"2025-12-01T00:00:00Z",
+           "changes":[
+              "Added RBAC roles and permissions support",
+              "RBAC roles/permissions are registered with miso-controller during deployment",
+              "Roles support Azure AD group mapping via Groups property",
+              "Permissions reference roles and are used for access control"
+           ],
+           "breaking":false
+        },
+        {
+           "version":"1.0.0",
+           "date":"2024-01-01T00:00:00Z",
+           "changes":[
+              "Initial schema for External Systems",
+              "Added OpenAPI and MCP contract configuration",
+              "Added authentication and environment variables",
+              "Added portalInput for UI-driven onboarding",
+              "Compatible with field-mappings.schema and security-model.schema"
+           ],
+           "breaking":false
+        }
+     ]
   },
-  "type": "object",
-  "required": [
-    "key",
-    "displayName",
-    "description",
-    "type",
-    "authentication"
+  "type":"object",
+  "required":[
+     "key",
+     "displayName",
+     "description",
+     "type",
+     "authentication"
   ],
-  "properties": {
-    "key": {
-      "type": "string",
-      "description": "Unique external system identifier (cannot be changed after creation). Example: 'hubspot', 'salesforce', 'teams'.",
-      "pattern": "^[a-z0-9-]+$",
-      "minLength": 3,
-      "maxLength": 40
-    },
-    "displayName": {
-      "type": "string",
-      "description": "Human-readable name for the external system",
-      "minLength": 1,
-      "maxLength": 100
-    },
-    "description": {
-      "type": "string",
-      "description": "Description of this external system integration",
-      "minLength": 1,
-      "maxLength": 500
-    },
-    "type": {
-      "type": "string",
-      "enum": [
-        "openapi",
-        "mcp",
-        "custom"
-      ],
-      "description": "Integration type: OpenAPI-driven, MCP-driven, or custom Python connector."
-    },
-    "enabled": {
-      "type": "boolean",
-      "default": true
-    },
-    "internal": {
-      "type": "boolean",
-      "description": "When true, this integration is deployed on dataplane startup (internal integration). When false or absent, deployed via pipeline only.",
-      "default": false
-    },
-    "authentication": {
-      "type": "object",
-      "description": "Authentication configuration for external system",
-      "required": [
-        "type"
-      ],
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": [
-            "oauth2",
-            "apikey",
-            "basic",
-            "aad",
-            "none"
-          ],
-          "description": "Authentication type"
+  "properties":{
+     "key":{
+        "type":"string",
+        "description":"Unique external system identifier (cannot be changed after creation). Example: 'hubspot', 'salesforce', 'teams'.",
+        "pattern":"^[a-z0-9-]+$",
+        "minLength":3,
+        "maxLength":40
+     },
+     "displayName":{
+        "type":"string",
+        "description":"Human-readable name for the external system",
+        "minLength":1,
+        "maxLength":100
+     },
+     "description":{
+        "type":"string",
+        "description":"Description of this external system integration",
+        "minLength":1,
+        "maxLength":500
+     },
+     "type":{
+        "type":"string",
+        "enum":[
+           "openapi",
+           "mcp",
+           "custom"
+        ],
+        "description":"Integration type: OpenAPI-driven, MCP-driven, or custom Python connector."
+     },
+     "enabled":{
+        "type":"boolean",
+        "default":true
+     },
+     "credentialIdOrKey":{
+        "type":"string",
+        "description":"Credential identifier (ID or key) to attach to this system. Used by dataplane when creating/updating system from deploy config."
+     },
+     "internal":{
+        "type":"boolean",
+        "description":"When true, this integration is deployed on dataplane startup (internal integration). When false or absent, deployed via pipeline only.",
+        "default":false
+     },
+     "authentication":{
+        "type":"object",
+        "description":"Template-based authentication. Required: method, variables. When method is not 'none', variables must include baseUrl and security must contain only kv:// references. On deploy, a credential is created with key authentication.credentialKey or <external-system.key>-cred. Template is write-once.",
+        "required":[
+           "method",
+           "variables"
+        ],
+        "properties":{
+           "credentialKey":{
+              "type":"string",
+              "description":"Stable reference key for the active credential. Default: <external-system.key>-cred."
+           },
+           "displayName":{
+              "type":"string",
+              "description":"Display name for the credential created from this template."
+           },
+           "method":{
+              "type":"string",
+              "enum":[
+                 "oauth2",
+                 "apikey",
+                 "basic",
+                 "aad",
+                 "none",
+                 "queryParam",
+                 "oidc",
+                 "hmac"
+              ],
+              "description":"Authentication method."
+           },
+           "variables":{
+              "type":"object",
+              "description":"Non-secret config. Must include baseUrl for all methods except none. Common keys: baseUrl, tokenUrl, authorizationUrl, tenantId, audience, scope, headerName; queryParam: paramName; oidc: openIdConfigUrl, clientId, expectedIssuer; hmac: algorithm, signatureHeader, timestampHeader, signaturePrefix, timestampMaxAge.",
+              "additionalProperties":{
+                 "type":"string"
+              }
+           },
+           "security":{
+              "type":"object",
+              "description":"Secret-bearing keys only. Every value must be a Key Vault reference matching ^kv://.+$",
+              "additionalProperties":{
+                 "type":"string",
+                 "pattern":"^kv://.+$"
+              }
+           },
+           "writeOnce":{
+              "type":"boolean",
+              "description":"Template is immutable after first deploy; dataplane does not update the credential from this template again.",
+              "default":true
+           }
         },
-        "oauth2": {
-          "type": "object",
-          "description": "OAuth2 authentication configuration",
-          "additionalProperties": true
+        "additionalProperties":false
+     },
+     "openapi":{
+        "type":"object",
+        "description":"OpenAPI integration configuration",
+        "properties":{
+           "documentKey":{
+              "type":"string",
+              "description":"Key of the OpenAPI document in the registry"
+           },
+           "specUrl":{
+              "type":"string",
+              "description":"URL to the OpenAPI specification",
+              "pattern":"^(http|https)://.*$"
+           }
         },
-        "apikey": {
-          "type": "object",
-          "description": "API key authentication configuration",
-          "additionalProperties": true
+        "additionalProperties":true
+     },
+     "mcp":{
+        "type":"object",
+        "description":"Model Context Protocol integration configuration",
+        "properties":{
+           "serverUrl":{
+              "type":"string",
+              "description":"MCP server URL",
+              "pattern":"^(http|https)://.*$"
+           },
+           "toolPrefix":{
+              "type":"string",
+              "description":"Prefix for MCP tool names",
+              "pattern":"^[a-zA-Z0-9_-]+$"
+           }
         },
-        "basic": {
-          "type": "object",
-          "description": "Basic authentication configuration",
-          "additionalProperties": true
+        "additionalProperties":true
+     },
+     "dataSources":{
+        "type":"array",
+        "description":"List of data source keys belonging to this external system. Each must match external-datasource.schema.json.",
+        "items":{
+           "type":"string",
+           "pattern":"^[a-z0-9-]+$"
         },
-        "aad": {
-          "type": "object",
-          "description": "Azure AD authentication configuration",
-          "additionalProperties": true
+        "uniqueItems":true
+     },
+     "configuration":{
+        "type":"array",
+        "description":"External system configuration variables (same pattern as application-schema).",
+        "items":{
+           "type":"object",
+           "required":[
+              "name",
+              "value",
+              "location",
+              "required"
+           ],
+           "properties":{
+              "name":{
+                 "type":"string",
+                 "pattern":"^[A-Z_][A-Z0-9_]*$"
+              },
+              "value":{
+                 "type":"string",
+                 "description":"Literal value or parameter reference ({{parameter}})"
+              },
+              "location":{
+                 "type":"string",
+                 "enum":[
+                    "variable",
+                    "keyvault"
+                 ]
+              },
+              "required":{
+                 "type":"boolean"
+              },
+              "portalInput":{
+                 "type":"object",
+                 "required":[
+                    "field",
+                    "label"
+                 ],
+                 "properties":{
+                    "field":{
+                       "type":"string",
+                       "enum":[
+                          "password",
+                          "text",
+                          "textarea",
+                          "select",
+                          "json"
+                       ]
+                    },
+                    "label":{
+                       "type":"string"
+                    },
+                    "placeholder":{
+                       "type":"string"
+                    },
+                    "options":{
+                       "type":"array",
+                       "items":{
+                          "type":"string"
+                       }
+                    },
+                    "masked":{
+                       "type":"boolean"
+                    },
+                    "validation":{
+                       "type":"object",
+                       "properties":{
+                          "minLength":{
+                             "type":"integer"
+                          },
+                          "maxLength":{
+                             "type":"integer"
+                          },
+                          "pattern":{
+                             "type":"string"
+                          },
+                          "required":{
+                             "type":"boolean"
+                          }
+                       },
+                       "additionalProperties":false
+                    }
+                 },
+                 "additionalProperties":false
+              }
+           },
+           "additionalProperties":false
         }
-      },
-      "additionalProperties": true
-    },
-    "openapi": {
-      "type": "object",
-      "description": "OpenAPI integration configuration",
-      "properties": {
-        "documentKey": {
-          "type": "string",
-          "description": "Key of the OpenAPI document in the registry"
-        },
-        "specUrl": {
-          "type": "string",
-          "description": "URL to the OpenAPI specification",
-          "pattern": "^(http|https)://.*$"
+     },
+     "tags":{
+        "type":"array",
+        "description":"Optional tags for search / filtering",
+        "items":{
+           "type":"string"
         }
-      },
-      "additionalProperties": true
-    },
-    "mcp": {
-      "type": "object",
-      "description": "Model Context Protocol integration configuration",
-      "properties": {
-        "serverUrl": {
-          "type": "string",
-          "description": "MCP server URL",
-          "pattern": "^(http|https)://.*$"
-        },
-        "toolPrefix": {
-          "type": "string",
-          "description": "Prefix for MCP tool names",
-          "pattern": "^[a-zA-Z0-9_-]+$"
+     },
+     "roles":{
+        "type":"array",
+        "description":"External system roles for Azure AD group mapping",
+        "items":{
+           "type":"object",
+           "required":[
+              "name",
+              "value",
+              "description"
+           ],
+           "properties":{
+              "name":{
+                 "type":"string",
+                 "description":"Human-readable role name",
+                 "minLength":1,
+                 "maxLength":100
+              },
+              "value":{
+                 "type":"string",
+                 "description":"Role identifier (used in JWT and ACL)",
+                 "pattern":"^[a-z-]+$"
+              },
+              "description":{
+                 "type":"string",
+                 "description":"Role description",
+                 "minLength":1,
+                 "maxLength":500
+              },
+              "groups":{
+                 "type":"array",
+                 "description":"Azure AD groups mapped to this role",
+                 "items":{
+                    "type":"string",
+                    "minLength":1,
+                    "maxLength":100
+                 }
+              }
+           },
+           "additionalProperties":false
         }
-      },
-      "additionalProperties": true
-    },
-    "dataSources": {
-      "type": "array",
-      "description": "List of data source keys belonging to this external system. Each must match external-datasource.schema.json.",
-      "items": {
-        "type": "string",
-        "pattern": "^[a-z0-9-]+$"
-      },
-      "uniqueItems": true
-    },
-    "configuration": {
-      "type": "array",
-      "description": "External system configuration variables (same pattern as application-schema).",
-      "items": {
-        "type": "object",
-        "required": [
-          "name",
-          "value",
-          "location",
-          "required"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "pattern": "^[A-Z_][A-Z0-9_]*$"
-          },
-          "value": {
-            "type": "string",
-            "description": "Literal value or parameter reference ({{parameter}})"
-          },
-          "location": {
-            "type": "string",
-            "enum": [
-              "variable",
-              "keyvault"
-            ]
-          },
-          "required": {
-            "type": "boolean"
-          },
-          "portalInput": {
-            "type": "object",
-            "required": [
-              "field",
-              "label"
-            ],
-            "properties": {
-              "field": {
-                "type": "string",
-                "enum": [
-                  "password",
-                  "text",
-                  "textarea",
-                  "select",
-                  "json"
-                ]
+     },
+     "permissions":{
+        "type":"array",
+        "description":"External system permissions with role mappings for access control",
+        "items":{
+           "type":"object",
+           "required":[
+              "name",
+              "roles",
+              "description"
+           ],
+           "properties":{
+              "name":{
+                 "type":"string",
+                 "description":"Permission identifier (e.g., 'documentstore:read', 'flowise:dev:access')",
+                 "pattern":"^[a-z0-9-:]+$",
+                 "minLength":1,
+                 "maxLength":100
+              },
+              "roles":{
+                 "type":"array",
+                 "description":"Roles that have this permission",
+                 "items":{
+                    "type":"string",
+                    "pattern":"^[a-z-]+$",
+                    "minLength":1,
+                    "maxLength":50
+                 },
+                 "minItems":1
               },
-              "label": {
-                "type": "string"
+              "description":{
+                 "type":"string",
+                 "description":"Permission description",
+                 "minLength":1,
+                 "maxLength":500
+              }
+           },
+           "additionalProperties":false
+        }
+     },
+     "endpoints":{
+        "type":"array",
+        "description":"API endpoint configurations for this external system. Used for dynamic endpoint registration at application startup.",
+        "items":{
+           "type":"object",
+           "required":[
+              "type",
+              "path"
+           ],
+           "properties":{
+              "type":{
+                 "type":"string",
+                 "description":"Endpoint type identifier (e.g., 'commands', 'events', 'notifications')",
+                 "pattern":"^[a-z0-9-]+$"
               },
-              "placeholder": {
-                "type": "string"
+              "path":{
+                 "type":"string",
+                 "description":"URL path for this endpoint (e.g., '/commands', '/events')",
+                 "pattern":"^/[a-z0-9/-]*$"
               },
-              "options": {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                }
+              "description":{
+                 "type":"string",
+                 "description":"Human-readable description of the endpoint"
               },
-              "masked": {
-                "type": "boolean"
+              "active":{
+                 "type":"boolean",
+                 "description":"Whether this endpoint should be registered (defaults to true)",
+                 "default":true
               },
-              "validation": {
-                "type": "object",
-                "properties": {
-                  "minLength": {
-                    "type": "integer"
-                  },
-                  "maxLength": {
-                    "type": "integer"
-                  },
-                  "pattern": {
-                    "type": "string"
-                  },
-                  "required": {
-                    "type": "boolean"
-                  }
-                },
-                "additionalProperties": false
+              "router":{
+                 "type":"string",
+                 "description":"Custom router module path override (defaults to auto-discovery based on naming convention)"
               }
-            },
-            "additionalProperties": false
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "tags": {
-      "type": "array",
-      "description": "Optional tags for search / filtering",
-      "items": {
-        "type": "string"
-      }
-    },
-    "roles": {
-      "type": "array",
-      "description": "External system roles for Azure AD group mapping",
-      "items": {
-        "type": "object",
-        "required": [
-          "name",
-          "value",
-          "description"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Human-readable role name",
-            "minLength": 1,
-            "maxLength": 100
-          },
-          "value": {
-            "type": "string",
-            "description": "Role identifier (used in JWT and ACL)",
-            "pattern": "^[a-z-]+$"
-          },
-          "description": {
-            "type": "string",
-            "description": "Role description",
-            "minLength": 1,
-            "maxLength": 500
-          },
-          "groups": {
-            "type": "array",
-            "description": "Azure AD groups mapped to this role",
-            "items": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 100
-            }
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "permissions": {
-      "type": "array",
-      "description": "External system permissions with role mappings for access control",
-      "items": {
-        "type": "object",
-        "required": [
-          "name",
-          "roles",
-          "description"
-        ],
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Permission identifier (e.g., 'documentstore:read', 'flowise:dev:access')",
-            "pattern": "^[a-z0-9-:]+$",
-            "minLength": 1,
-            "maxLength": 100
-          },
-          "roles": {
-            "type": "array",
-            "description": "Roles that have this permission",
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z-]+$",
-              "minLength": 1,
-              "maxLength": 50
-            },
-            "minItems": 1
-          },
-          "description": {
-            "type": "string",
-            "description": "Permission description",
-            "minLength": 1,
-            "maxLength": 500
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "endpoints": {
-      "type": "array",
-      "description": "API endpoint configurations for this external system. Used for dynamic endpoint registration at application startup.",
-      "items": {
-        "type": "object",
-        "required": [
-          "type",
-          "path"
-        ],
-        "properties": {
-          "type": {
-            "type": "string",
-            "description": "Endpoint type identifier (e.g., 'commands', 'events', 'notifications')",
-            "pattern": "^[a-z0-9-]+$"
-          },
-          "path": {
-            "type": "string",
-            "description": "URL path for this endpoint (e.g., '/commands', '/events')",
-            "pattern": "^/[a-z0-9/-]*$"
-          },
-          "description": {
-            "type": "string",
-            "description": "Human-readable description of the endpoint"
-          },
-          "active": {
-            "type": "boolean",
-            "description": "Whether this endpoint should be registered (defaults to true)",
-            "default": true
-          },
-          "router": {
-            "type": "string",
-            "description": "Custom router module path override (defaults to auto-discovery based on naming convention)"
-          }
-        },
-        "additionalProperties": false
-      }
-    },
-    "endpointsActive": {
-      "type": "boolean",
-      "description": "Master switch for all endpoints in this system. If false, no endpoints are registered regardless of individual endpoint active flags.",
-      "default": true
-    },
-    "credentialIdOrKey": {
-      "type": "string",
-      "description": "Credential identifier (ID or key) to use for authenticating with this external system."
-    },
-    "generateMcpContract": {
-      "type": "boolean",
-      "description": "Whether to generate MCP contract on publish. Config only (no query parameter); default true when absent.",
-      "default": true
-    },
-    "generateOpenApiContract": {
-      "type": "boolean",
-      "description": "Reserved: whether to generate or expose OpenAPI contract on publish. Not yet implemented.",
-      "default": true
-    },
-    "triggerPathsHash": {
-      "type": "string",
-      "description": "SHA256 hash of triggerPaths payload (64-char hex). Used to detect structural changes. Optional; Dataplane computes when absent.",
-      "pattern": "^[a-f0-9]{64}$"
-    }
+           },
+           "additionalProperties":false
+        }
+     },
+     "endpointsActive":{
+        "type":"boolean",
+        "description":"Master switch for all endpoints in this system. If false, no endpoints are registered regardless of individual endpoint active flags.",
+        "default":true
+     },
+     "generateMcpContract":{
+        "type":"boolean",
+        "description":"Whether to generate MCP contract on publish. Config only (no query parameter); default true when absent.",
+        "default":true
+     },
+     "generateOpenApiContract":{
+        "type":"boolean",
+        "description":"Reserved: whether to generate or expose OpenAPI contract on publish. Not yet implemented.",
+        "default":true
+     },
+     "triggerPathsHash":{
+        "type":"string",
+        "description":"SHA256 hash of triggerPaths payload (64-char hex). Used to detect structural changes. Optional; Dataplane computes when absent.",
+        "pattern":"^[a-f0-9]{64}$"
+     }
   },
-  "additionalProperties": false
-}
+  "additionalProperties":false
+}