Extend Production Guardrails

Extend connectors are custom code, so SchemAlign treats them as unsafe by default and runs them through a governed connector runtime path. Connector authors should design for that boundary instead of trying to bypass it.

Non-negotiable rules

Rule	What it means
Use an entrypoint	The connector must expose the configured module:function entrypoint, normally connector:run.
Keep source files relative	Connector file paths must be relative, cannot be absolute, and cannot traverse upward with ...
Pin dependencies	Dependencies should be declared as specific requirement strings, such as ldap3==2.9.1.
Use governed Python	The requested Python version must resolve to a governed connector runtime.
Keep secrets out of config	Configuration schemas should use account references, not password or token fields.
Write only to output_dir	Connector output files should be written under the runtime-provided output_dir.
Return structured JSON	The entrypoint should return a JSON-serializable dictionary.
Do not patch the app	Extend apps should not modify SchemAlign backend code, database models, templates, or shared runtime files.
Do not choose tenancy	SchemAlign chooses organization, run context, runtime identity, and available accounts.
Fail closed	A connector should not install packages, switch runtimes, or fall back to app Python at runtime.

Runtime payload contract

The connector entrypoint receives one payload dictionary. A typical run(payload) function should read these keys:

Payload key	Description
input_payload	The connector configuration values from the node drawer. SchemAlign may enrich this with resolved account credentials at runtime.
output_dir	Directory where the connector should write output files.
working_dir	Working directory for this connector invocation. In normal use, treat it as the same output-focused runtime workspace.
runtime_manifest	Metadata about the installed connector, connector version, hashes, entrypoint, dependency hash, and runtime identity.
organization	Safe organization context for the current run.
execution	Pipeline/run context, including pipeline, project, organization, run, and current step metadata.

Accounts and credentials

Connectors should use an account_id field when they need credentials. The browser sees only safe account metadata. At runtime, SchemAlign resolves the selected account server-side and may add a credentials object to input_payload.

Connector code may read credentials from:

config = payload.get("input_payload") or {}
credentials = config.get("credentials") or {}

Do not write credentials to logs, output files, artifacts, or returned metadata.

Configuration schema rules

A connector configuration schema should be a JSON object with type: object, a properties map, and optional required fields. SchemAlign renders supported fields in Workspace and validates the node configuration on save.

Use x-ui.tabs to organize larger forms. Keep field descriptions concise and user-facing.

{
  "type": "object",
  "additionalProperties": true,
  "required": ["account_id", "server_uri"],
  "properties": {
    "account_id": {
      "type": "string",
      "title": "Account",
      "description": "Account reference used to resolve credentials at runtime."
    },
    "server_uri": {
      "type": "string",
      "title": "Server URI / host"
    }
  }
}

Validation checks

Before a connector is published, SchemAlign validates the version. Validation checks include:

• connector key is a safe identifier
• manifest can be materialized
• dependencies parse as valid requirement declarations
• requested Python resolves to a governed connector runtime
• requested capabilities are normalized
• source file paths are safe and unique
• at least one Python source file exists
• Python source compiles successfully
• the configured entrypoint maps to a stored source file
• the entrypoint target resolves to a callable function or class

Runtime isolation

At runtime, SchemAlign stages connector files into a connector-specific runtime directory. The staged source tree is made read-only. The connector receives a dedicated output directory and runs with a scrubbed environment, resource limits, and an organization-scoped runtime identity when enabled.

If the dedicated dependency environment or Python runtime is unavailable, the connector runner fails closed instead of falling back to shared application Python.

Good connector behavior

A production-ready connector should:

• validate required config values early
• use safe filenames
• sanitize unexpected control characters from output
• keep network timeouts bounded
• return row counts, output filenames, and format metadata
• avoid shell commands unless absolutely necessary
• keep test metadata mock-safe
• keep output deterministic enough for downstream nodes to consume