@useparagon/ocs

Open Connector Specification (OCS)

Declarative YAML contracts for defining integration connectors at Paragon.

Prerequisites

Before using the OCS CLI, make sure you have the following installed:

• Node.js >= 18
• npm >= 9

Installation

git clone https://github.com/useparagon/ocs.git
cd ocs
npm install
npm run build

After building, the ocs CLI is available via npx ocs from within the project.

Link ocs-core for local development

The ocs CLI depends on @useparagon/ocs-core. For local development across repositories, use npm link:

# In ocs-core repo:
cd ../ocs-core
npm link

# In ocs repo:
cd ../ocs
npm link @useparagon/ocs-core

This creates a symlink so changes in ocs-core are immediately available in the CLI without re-publishing.

Setup

1. Configure environment

Create a .env file in the project root to configure the registry endpoint:

# Registry API URL — where connector metadata and packages are stored
OCS_REGISTRY_URL=http://localhost:3456

2. Start the registry API (local development)

The registry API is a separate service that stores connector metadata and YAML packages. See the ocs-registry repo:

cd ../ocs-registry
npm install
npm run docker:up          # Starts Postgres + registry API
curl http://localhost:3456/health

End-to-End Workflow

1. Scaffold a new connector

npx ocs init ./connectors --id slack --title "Slack" --auth oauth2

2. Add resources

npx ocs new action get-users --dir ./connectors/slack
npx ocs new entity user --dir ./connectors/slack
npx ocs new trigger message-posted --dir ./connectors/slack
npx ocs new pipeline sync-contacts --dir ./connectors/slack

3. Validate

npx ocs validate ./connectors/slack

4. Publish to registry

The version is read from connector.yaml (metadata.version or the semver in apiVersion).

npx ocs push ./connectors/slack

This does three things:

• Packages the connector YAML into a .tgz archive
• Computes a SHA256 checksum for integrity verification
• Uploads the package and registers the version in the catalog API

5. Browse the catalog

npx ocs list                    # List all connectors
npx ocs list slack              # List all versions of slack
npx ocs search crm              # Search by name

6. Pull a published connector

npx ocs pull slack@1.0.0

CLI Commands — Full Reference

ocs init

Scaffold a new connector directory with starter files.

ocs init [dir] [--id <id>] [--title <name>] [--auth <type>]

Option	Description	Default
dir	Target directory	.
--id <id>	Connector identifier (kebab-case)	directory name
--title <name>	Display name	title-cased id
--auth <type>	Auth type: apikey, basic, bearer, oauth2, oauth2-client-credentials, oauth2-ropc	apikey

npx ocs init ./connectors --id github --title "GitHub" --auth oauth2
npx ocs init ./connectors --id stripe --auth bearer

ocs new

Scaffold a new resource file inside a connector.

ocs new <resource> <name> [--dir <path>]

Resource	What it creates
connector	Connector directory (alias for ocs init)
action	Action (HttpRequest)
trigger	Trigger (webhook)
pipeline	Pipeline (ManagedSync)
entity	Entity with starter schema

npx ocs new action get-users --dir ./connectors/slack
npx ocs new trigger order-created --dir ./connectors/shopify
npx ocs new entity invoice
npx ocs new pipeline sync-contacts

ocs validate

Run schema + semantic validation on OCS YAML files.

ocs validate <path...>

Performs two validation layers:

• Layer A (Schema) — JSONata-based rules checking structural correctness
• Layer B (Semantic) — Cross-resource reference checks, scopes, consistency

npx ocs validate                                  # Validate current directory
npx ocs validate ./connectors/slack               # Validate a specific connector
npx ocs validate actions/ entities/               # Validate specific directories

ocs doctor

Summarize connector resources, then run full validation.

ocs doctor <path...>

npx ocs doctor ./connectors/slack

ocs explain

Print a human-readable field reference for any OCS resource or concept.

ocs explain <topic>

Topic	Description
connector	Identity, capabilities, rate limits
authentication (or auth)	OAuth2, API Key, Bearer, etc.
action	HTTP actions (single and chained)
trigger	Webhook and polling event sources
pipeline (or sync-config, mapping)	ManagedSync and MultiStep data flows
entity	Typed data models
input (or inputs, fields)	Input field types, referencing, and display
output	Output mapping (entity, direct, plugin)
pagination	Pagination types and configuration
errors	Error handling

npx ocs explain action
npx ocs explain pagination
npx ocs explain input

ocs schema

Inspect OCS resource kind validation rules.

ocs schema list                     # List all resource kinds
ocs schema show <kind>              # Show rules for a kind

npx ocs schema list
npx ocs schema show Action
npx ocs schema show Connector

ocs operators

Inspect the global operator set.

ocs operators list                  # List all operators
ocs operators show <id>             # Show operator details

npx ocs operators list
npx ocs operators show '$StringContains'

ocs push

Package connector YAML and publish to the registry.

ocs push [path] [options]

Option	Description	Default
path	Connector directory	.
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL or http://localhost:3456
--published-by <actor>	Publisher identity	$USER
--no-validate	Skip validation before pushing	—

The version is read from connector.yaml (metadata.version or the semver suffix in apiVersion).

npx ocs push ./connectors/slack
npx ocs push . --no-validate
npx ocs push ./connectors/github --published-by ci

ocs pull

Download connector files from the registry.

ocs pull <connector[@version]> [options]

Option	Description	Default
-v, --version <version>	Specific version to pull	latest
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL
-o, --output <dir>	Output directory	.

npx ocs pull slack                              # Pull latest version
npx ocs pull salesforce@1.2.0                   # Pull specific version
npx ocs pull github -o ./connectors             # Pull into specific directory

ocs install

Pull and extract connector files into a local directory.

ocs install <connector[@version]> [options]

Option	Description	Default
-v, --version <version>	Specific version to install	latest
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL
-d, --dir <path>	Base connectors directory	./connectors

npx ocs install slack
npx ocs install salesforce@1.2.0
npx ocs install hubspot@2.0.0 -d ./my-connectors

ocs list

List connectors or versions.

ocs list [connector-id] [options]

Option	Description	Default
connector-id	If provided, lists all versions of this connector	—
--visibility <scope>	Filter: paragon, customer, partner, community	—
--org <org-id>	Filter by owner organization	—
--limit <n>	Max results	50
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL

npx ocs list                                    # List all connectors
npx ocs list klaviyo                            # List all versions
npx ocs list --visibility community             # Filter by visibility
npx ocs list --org my-org --limit 20            # Filter by org

ocs search

Search for connectors by name.

ocs search <query> [options]

Option	Description	Default
--limit <n>	Max results	50
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL

npx ocs search crm
npx ocs search slack

ocs verify

Verify a published connector version in the catalog.

ocs verify <connector[@version]> [options]

Option	Description	Default
-r, --registry <url>	Registry API URL	$OCS_REGISTRY_URL

npx ocs verify slack@1.0.0
npx ocs verify salesforce

ocs login / ocs logout

Authenticate with the OCS registry (not yet implemented).

npx ocs login
npx ocs logout

Connector Directory Layout

<connector-id>/
  connector.yaml           # Identity, capabilities, rate limits
  auth/
    <scheme-id>.yaml       # Authentication scheme
  actions/
    <action-id>.yaml       # API operations
  entities/
    <entity-id>.yaml       # Typed data models
  triggers/
    <trigger-id>.yaml      # Webhook/polling event sources
  pipelines/
    <pipeline-id>.yaml     # Data flows (optional)
  plugins/
    <plugin-id>.yaml       # Custom logic (optional)
  filters/
    filter.yaml            # Operator mappings (optional)
    operator-set.yaml      # Custom operators (optional)

Resource Kinds

Each YAML file declares a kind and apiVersion:

Kind	apiVersion prefix	Purpose
Connector	ocs.useparagon.com/connector/	Identity, capabilities, rate limits
Authentication	ocs.useparagon.com/authentication/	Auth scheme, scopes, verification
Action	ocs.useparagon.com/action/	API operation with input/output
Entity	ocs.useparagon.com/entity/	Typed data model
Trigger	ocs.useparagon.com/trigger/	Webhook or polling event source
Pipeline	ocs.useparagon.com/pipeline/	Data flow (MultiStep or ManagedSync)
Plugin	ocs.useparagon.com/plugin/	Custom function
TriggerPlugin	ocs.useparagon.com/triggerPlugin/	Shared webhook config
AuthPlugin	ocs.useparagon.com/authPlugin/	Base auth pattern (managed)
OperatorSet	ocs.useparagon.com/filter/	Global filter operators (managed)
IntegrationFilter	ocs.useparagon.com/filter/	Per-connector operator mappings

Connector Metadata

The connector.yaml metadata block supports the following fields:

Field	Description	Required
metadata.id	Unique connector identifier (kebab-case)	Yes
metadata.name	Display name	No
metadata.version	Connector version (semver)	Recommended
metadata.author	Owner in @org/connector-id format (e.g. @useparagon/klaviyo)	Recommended

Expression Syntax (JSONata)

OCS uses JSONata as its expression language:

Context	Syntax	Example
Input field	$input.field	body: { name: $input.name }
Compound expression	${{ expr }}	path: ${{ '/contacts/' & $input.id }}
Template interpolation	{{$ref}}	path: "/contacts/{{$input.id}}"
Auth input	$inputs.field	$inputs.apiKey
Stored credential	$stored.field	$stored.accessToken
Auth endpoint	$endpoints.field	$endpoints.tokenUrl
API response	$response.path	output: { id: $response.id }
Step reference	$steps.{id}...	$steps.step1.output.id
Plugin argument	$args.name	$args.secret
Plugin pipe output	$pipe.index	$pipe.0

Input Types

Type	Description
TEXT	String
NUMBER	Numeric
BOOLEAN	True/false
ENUM	Single selection from options
MULTI_ENUM	Multiple selections
DATE	Date only
DATETIME	Date and time
JSON	Arbitrary JSON
FILE	File upload
SECRET	Sensitive value (masked)
URL	URL string
TEXTAREA	Multi-line text
CODE	Code block
CONDITIONAL	Conditional field set

Development

npm install                    # Install dependencies
npm run build                  # Compile TypeScript
npm run typecheck              # Type check without emitting
npm test                       # Run Jest tests
npm run validate:examples      # Validate all example connectors

Repository Structure

src/
  cli.ts                       # CLI entry point
  commands/                    # Command implementations
  rules/                       # JSONata validation rules (Layer A)
  validator/                   # Semantic validation (Layer B)
platform/
  auth-plugins/                # Base auth patterns (ApiKey, OAuth2, etc.)
  operator-sets/               # Global filter operators
init-examples/                 # Starter templates used by ocs init
examples/
  connectors/                  # Reference connectors
  resources/                   # Per-kind standalone examples
docs/
  ocs-schema-reference.md      # Complete field-level schema reference
  platform-guide.md            # End-to-end platform walkthrough

Related Packages

Package	Purpose
@useparagon/ocs	YAML spec + ocs CLI (this repo)
@useparagon/ocs-core	Runtime engine for executing YAML connectors
@useparagon/ocs-registry	Catalog API, S3 package storage

License

ISC