Contracts and compatibility

Pyplines maintains structural contracts in the repository's contracts/ directory. Definitions, configuration documents, and Action records use JSON Schema Draft 2020-12. The HTTP API uses OpenAPI 3.1. Behavioral specifications cover guarantees that structural schemas cannot express, including approvals and recovery.

Contract publication begins with software releases containing this capability. Older releases may have no downloadable contract bundle; use their running server's /openapi.json and retained documentation rather than applying a newer contract retroactively.

Choose the appropriate contract

Configuration files include name; resource API requests obtain it from the URL. API responses remove registry credentials. Use OpenAPI for HTTP payloads rather than assuming that a configuration-file schema describes the response.

Runtime envelopes are documented for compatible implementations. They do not provide a public endpoint for submitting work directly to runners. Integrations start Runs through the server API.

Discover published contracts

The publisher maintains a machine-readable catalog at https://pyplines.dev/contracts/index.json. Each entry identifies a release group, version, commit, immutable base URL, manifest, archive, and archive SHA-256.

The supported entries identify the selected platform/tooling tags and whether contracts have been published for them. A newly published release does not implicitly replace the supported combination. Follow the entry matching your installation rather than selecting the highest version string.

Release artifacts are also attached to the matching GitHub release as contracts.tar.gz and contracts-manifest.json. The manifest records file checksums, canonical schema IDs, and source schema hashes. Platform bundles contain OpenAPI; tooling bundles carry their applicable schemas without a server API export.

Validate offline

Download and verify the selected archive against its release manifest/catalog checksum, then extract it into a trusted local directory. The bundled schemas are self-contained; validation does not fetch schema references over the network.

For example, in a Python environment with the contract-enabled operator CLI installed, validate a parsed Definition against an extracted schema:

import json
from pathlib import Path

from jsonschema import Draft202012Validator
from referencing import Registry
from pyplines_cli.documents import load

schema = json.loads(
    Path("contracts/definition/v1/definition.schema.json").read_text()
)
Draft202012Validator.check_schema(schema)
definition = load(Path("workflow.yaml"))
Draft202012Validator(schema, registry=Registry()).validate(definition)

This example uses the installed operator CLI's bounded YAML loader to reject aliases, duplicate keys, and oversized files. A generic YAML loader alone does not provide the platform's parsing protections. For ordinary local use, pyplines validate workflow.yaml already uses its packaged structural schema.

Structural validation does not establish that an Action exists, that references address earlier steps, or that the supplied credentials work. Deployment and preparation perform those additional checks.

Configure an editor

A YAML editor with schema associations can map workflow files to the extracted definition.schema.json. For editors supporting a YAML language-server modeline:

# yaml-language-server: $schema=./contracts/definition/v1/definition.schema.json
apiVersion: pyplines/v1
kind: Definition
name: example
steps:
  - name: first
    uses: echo@2026.10.3
    with:
      message: Hello from operations

The echo image must be provided by your administrator before deployment. Editor completion and validation do not execute the workflow.

Generate an API client

Point an OpenAPI 3.1-compatible client generator at the extracted http/v1/openapi.json. Its operation IDs are stable method/path-based identifiers. It describes operator bearer authentication separately from runner registration credentials. Inspect error responses and Run states; an accepted request is not proof of completed execution.

The generated document served by /openapi.json uses the same route registration as the release export. Use a running server's document when diagnosing its exact version. See API integration for interaction guidance.

Inspect an individual Action

The shared manifest schema describes the packaging format. An Action's own input_schema and output_schema describe its specific fields and types. Those schemas are generated from its Python models and captured in its image.

Use the deployed revision and pinned digest to identify the actual Action being executed. A schema does not describe every external side effect; review the Action's documented permissions, failure behavior, and retry safety as well.

Version and compatibility rules

Protocol identifiers such as pyplines/v1 and pyplines.action.v1 differ from software release versions. Released schema $id URLs are immutable. The manifest's source hashes allow comparison of shared contracts across independently versioned platform and tooling releases.

Schema changes require review of both producers and consumers. A new response field can affect a strict client even when existing fields remain unchanged. Behavioral changes may be breaking without any schema change. Prereleases do not carry stable-interface guarantees; pin a release and its checksums for reproducible integrations.

Contribute a contract change

From the repository root:

task contracts:generate
task contracts:check

Generation updates the OpenAPI export, repository schema index, and packaged Python schemas. CI verifies reproducibility and conformance examples. Software releases package the exact reviewed contracts; website publication copies those artifacts without generating a new interface from current source.

Installation configuration

installation/v1/installation.schema.json defines the desired configuration for the installer: component, platform version, endpoints, TLS paths, storage location, and runner settings. It rejects credential values and unknown fields. The schema is packaged with the installer and included in release contract bundles; private installer state is not an interchange format.

The multi-target installer document uses apiVersion: pyplines.installer/v1 and contracts/installer/v1/installation.schema.json. It describes named targets, release versions, dependency references, and credential sources. Validate structural shape with JSON Schema, then use pyplines-installer validate FILE for graph and component checks. The original pyplines.installation/v1 single-service contract remains supported by compatibility commands. Both ship in release contract bundles.