AI Connector Contract

The AI Connector Contract is a markdown prompt document designed to be shared with an AI coding assistant before asking it to generate or revise an Extend connector.

It explains the production Extend guardrails, runtime payload shape, account handling rules, output expectations, and security boundaries an AI assistant should follow.

Download the AI Connector Contract (.md)

When to use it

Use this document when you want an AI assistant to help create connector source code, configuration schema, test metadata, or field descriptions. It is especially useful before asking an AI assistant to build a connector for a system-specific protocol or API.

What it covers

Topic	Purpose
Runtime payload	Shows how to read input_payload, output_dir, runtime_manifest, and execution context.
Secrets	Requires account_id references and runtime-resolved credentials instead of secret fields.
Dependencies	Requires pinned dependencies and governed Python runtime usage.
Output files	Requires connector outputs to be written under output_dir.
Guardrails	Tells AI assistants not to modify SchemAlign internals or bypass the connector runner.
Testing	Requires safe mock test_metadata.

Preview

# SchemAlign Extend AI Connector Contract

This document is intended to be shared with an AI coding assistant before it generates a SchemAlign Extend connector. The assistant should follow these rules exactly.

## Product context

SchemAlign Extend creates governed custom connectors that can be validated, tested, published, installed to an organization, and used from Workspace as installed connector nodes. Extend connector code runs through a dedicated connector runner and must stay inside SchemAlign guardrails.

## Output requested from the AI assistant

When asked to build an Extend connector, produce connector source files and metadata only. Do not ask to modify SchemAlign backend code, database models, templates, Dockerfiles, CI/CD, or shared runtime files.

A minimal source connector normally includes:

- `connector.py`
- a `run(payload: dict | None = None) -> dict` entrypoint
- JSON-serializable metadata constants such as `config_schema` and `test_metadata`
- safe helper functions inside the connector source file or related connector files

## Required connector settings

Use these settings unless the user provides different values:

| Setting | Required value or rule |
|---|---|
| Entrypoint | `connector:run` unless explicitly changed. |
| Python version | Use the governed version requested by the user. Do not silently downgrade. |
| Dependencies | Pin dependencies. Do not install dependencies from inside connector code. |
| Connector type | Use `source`, `compose`, or `destination` as requested. |
| Config schema | Provide a JSON object with `type: object` and `properties`. |
| Test metadata | Provide safe mock input only. No real secrets. |

## Runtime payload

The connector entrypoint receives a single payload dictionary. Use this pattern:

````python
def run(payload: dict | None = None) -> dict:
    payload = payload or {}
    config = payload.get("input_payload") or {}
    output_dir = Path(str(payload.get("output_dir") or "."))
    output_dir.mkdir(parents=True, exist_ok=True)
    # connector logic here
    return {"status": "ok"}
````

The payload may include:

| Key | Meaning |
|---|---|
| `input_payload` | Node configuration values and any server-side runtime enrichment. |
| `output_dir` | Directory where connector output files must be written. |
| `working_dir` | Connector invocation working directory. |
| `runtime_manifest` | Connector/version/runtime metadata. |
| `organization` | Safe organization context. |
| `execution` | Pipeline and run context. |

## Secrets and accounts

Never put usernames, passwords, tokens, or private keys in `config_schema`, `test_metadata`, logs, returned metadata, or output files.

If a connector needs credentials, expose an `account_id` field. At runtime, SchemAlign resolves the account server-side and may place credentials into `input_payload.credentials`.

Use this pattern:

````python
config = payload.get("input_payload") or {}
credentials = config.get("credentials") or {}
username = credentials.get("username") or credentials.get("user")
password = credentials.get("password") or credentials.get("secret")
````

## File and output rules

- Write output only under `output_dir`.
- Use safe filenames; strip path separators from user-provided filenames.
- Return a JSON-serializable result with useful metadata.
- Prefer output files for large data instead of returning large payloads inline.
- Do not write into the SchemAlign app tree.
- Do not rely on persistent local state between runs.

Good result pattern:

````python
return {
    "status": "ok",
    "row_count": row_count,
    "filename": filename,
    "output_format": output_format,
    "mime": mime,
    "output_path": str(output_path),
}
````

## Runtime guardrails

Connector code must not attempt to bypass SchemAlign runtime guardrails. Do not:

- import SchemAlign application internals
- open database sessions directly
- choose tenant schemas or organization IDs
- read application environment variables
- call package installers at runtime
- fall back to application Python
- mutate staged connector source files
- write outside `output_dir`
- log secrets

If a required dependency or runtime is missing, the connector should fail clearly.

## Schema guidance

Use clear titles and descriptions. Put credentials behind an account reference. Group larger forms with `x-ui.tabs`.

````python
config_schema = {
    "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",
            "description": "Host name, FQDN, or service URI.",
        },
    },
}
````

## Testing guidance

`test_metadata` must be safe to store and view. Use mock mode, synthetic hosts, and fake sample rows. Do not include real credentials or customer data.

````python
test_metadata = {
    "mode": "mock",
    "output_format": "csv",
    "publish_artifact": False,
    "publish_history": False,
}
````

## Final checklist for AI-generated connectors

Before returning code, verify that:

- the entrypoint matches the configured value
- dependency names and versions are pinned
- config schema is valid JSON-serializable Python data
- test metadata is safe
- credentials use `account_id` plus runtime-resolved `credentials`
- output files are written under `output_dir`
- returned result is JSON-serializable
- no customer-specific or environment-specific examples are included unless the user explicitly provided them for their private code
- connector code does not patch or bypass SchemAlign itself