Developer connector SDK guide

dpone.connector_sdk is the framework-owned layer for community connector package generation. It intentionally stays outside runtime connector execution so scaffold behavior can be tested without live services.

Package map

Module	Responsibility
dpone.connector_sdk.models	Stable result dataclasses returned by SDK services.
dpone.connector_sdk.certification	Deterministic certification manifest templates.
dpone.connector_sdk.scaffold	File generation for connector packages.
dpone.commands.connectors_cmd	Thin CLI adapter only. No scaffold business logic belongs here.

Design rules

• Keep generated code small and dependency-injected.
• Do not import runtime source/sink implementations in SDK services.
• Do not add connector-specific behavior to the scaffold service.
• Keep certification contracts deterministic so generated files are diff-friendly.
• Extend certification templates through small capability sections, not branching god modules.

Main service

ConnectorSdkScaffoldService owns package generation:

from dpone.connector_sdk.scaffold import ConnectorSdkScaffoldService

result = ConnectorSdkScaffoldService().scaffold(
    name="demo_api",
    root="./community-connectors",
    connector_type="api",
    capabilities=("source", "sink"),
)
print(result.sdk_root)

ConnectorCertificationTemplateService owns the evidence contract:

from dpone.connector_sdk.certification import ConnectorCertificationTemplateService

template = ConnectorCertificationTemplateService().build(
    connector="demo_api",
    connector_type="api",
    capabilities=("source", "sink"),
)

Test expectations

Every SDK change should update or add tests for:

• generated package structure;
• generated certification manifest content;
• CLI JSON output;
• documentation links;
• backward compatibility of existing dpone connectors scaffold defaults.

Architecture notes

The SDK belongs to the control-plane family. It can be imported by commands, tests, and docs tooling. Runtime connectors must not import the SDK because generated files are a developer experience tool, not a pipeline execution dependency.

flowchart LR
  CLI["dpone connectors scaffold"] --> SDK["dpone.connector_sdk.scaffold"]
  SDK --> Models["dpone.connector_sdk.models"]
  SDK --> Cert["dpone.connector_sdk.certification"]
  SDK --> Files["Connector package files"]
  Files --> Tests["Connector package tests"]
  Files --> Evidence["certification/certification.yaml"]

Adding a new capability

1. Add the capability name and validation in dpone.connector_sdk.scaffold.
2. Add a dedicated capability section in ConnectorCertificationTemplateService.
3. Add generated runtime files only when the capability is requested.
4. Add tests that prove source-only packages do not receive sink-only files.
5. Update Connector SDK and certification docs.