Contributing to Connections

Connections are schema-driven. A Connection’s structure, identity, lifecycle, and the forms Meshery renders for it are declared in a connection definition that conforms to the Connection schema (connections.meshery.io/v1beta3) in meshery/schemas. Before contributing, familiarize yourself with that schema and read Contributing to Schemas for the development workflow.

This guide explains how to author a connection definition so that Meshery understands a new kind of Connection and offers it in the Connection Wizard. In most cases, authoring a JSON definition is all you need - no UI or server code.

What is a connection definition?

A connection definition is a first-class Registry entity, authored per Model - exactly like Components and Relationships. It declares everything Meshery needs to register, render, and manage a kind of Connection:

• its identity (kind, type, subType),
• its lifecycle (initial status and a transitionMap of allowed state transitions),
• the forms the Connection Wizard renders (connectionSchema and credentialSchema), and
• its visual identity (styles).

Anatomy of a connection definition

Below is a complete, minimal definition for a hypothetical telemetry backend. It uses the generic wizard flow, which is what most contributions should use.

	

		{
  "schemaVersion": "connections.meshery.io/v1beta3",
  "name": "Grafana",
  "description": "A Grafana instance that brings its dashboards and panels into Meshery.",
  "kind": "grafana",
  "type": "telemetry",
  "subType": "metrics",
  "status": "registered",
  "transitionMap": {
    "registered": [
      { "nextState": "connected", "description": "Connect to the Grafana instance." },
      { "nextState": "ignored", "description": "Keep the registration but do not connect." }
    ],
    "connected": [
      { "nextState": "disconnected", "description": "Disconnect the Grafana connection." },
      { "nextState": "deleted", "description": "Remove the Grafana connection completely." }
    ]
  },
  "connectionSchema": {
    "type": "object",
    "title": "Grafana Connection",
    "required": ["url"],
    "properties": {
      "url": {
        "type": "string", "format": "uri", "title": "Grafana Endpoint",
        "description": "Base URL of the Grafana instance (e.g. http://grafana.example:3000)."
      },
      "name": {
        "type": "string", "title": "Connection Name",
        "description": "Optional friendly name for this Grafana connection."
      }
    }
  },
  "credentialSchema": {
    "type": "object",
    "title": "Grafana Credential",
    "properties": {
      "secret": {
        "type": "string", "title": "API Key or Basic Auth",
        "description": "API key, or basic-auth credential formatted as username:password."
      }
    }
  },
  "styles": {
    "svgColor": "<svg ...>...</svg>",
    "svgWhite": "<svg ...>...</svg>"
  }
}
	

Identity: kind, type, subType

These three fields identify the Connection and determine how the wizard treats it:

• kind - the genre of Connection (e.g. grafana, prometheus, kubernetes). The wizard groups credentials and renders icons by kind.
• type - a broad classification: platform, telemetry, collaboration, and so on.
• subType - a finer classification: orchestration, metrics, git, chat, and so on.

Together they let the UI target a specific Connection with a custom wizard extension when the generic flow is not enough. For reference, the definitions Meshery ships with:

Lifecycle: status and transitionMap

status is the state a freshly created Connection starts in. Manually registered Connections typically start at registered; resources that Meshery discovers (like Kubernetes) start at discovered.

transitionMap declares the state machine for the Connection: for each state, the list of states it may move to, each with a human-readable description shown as a confirmation prompt in the UI. Use only the canonical states - discovered, registered, connected, disconnected, ignored, maintenance, deleted, and not found - and keep the transitions consistent with their documented meanings. See States and the Lifecycle of Connections for what each state means and which transitions make sense.

Forms: connectionSchema and credentialSchema

Both are JSON Schemas. The Connection Wizard renders them directly with react-jsonschema-form - the same library used for Component forms:

• connectionSchema becomes the Configure Connection step. Mark the fields a Connection cannot exist without (such as url) as required. A name property, if present, is used as the Connection’s display name.
• credentialSchema becomes the Associate Credential step. Omit it for a Connection that needs no secret - the wizard then skips the credential step entirely.

Because these schemas live on the definition, the wizard needs no per-kind UI code to render them. Adding a property to the schema adds a field to the form.

Visual identity: styles

styles carries inline SVG markup for the kind’s icon: svgColor (for light backgrounds), svgWhite (for dark backgrounds), and optionally svgComplete. Follow the same icon conventions as Components.

Optional metadata

Two optional metadata keys tune wizard behavior:

• metadata.flow - force a wizard flow: generic (the default for every kind except Kubernetes) or kubernetes. You rarely need to set this.
• metadata.docsURL - a documentation link surfaced for the kind in the wizard. Defaults to the Connections concept page.

Where the definition lives

Place the definition as a JSON file in a connections/ folder inside its Model, alongside that Model’s components/ and relationships/:

server/meshmodel/<model>/<version>/connections/<Name>Connection.json

For example, the shipped definitions live under server/meshmodel/meshery-core/.../connections/ as KubernetesConnection.json, GrafanaConnection.json, and PrometheusConnection.json. A Model may include any number of connection definitions. Use these existing files as templates.

How the definition is registered and consumed

1. Registration. On Model registration, Meshery registers the connection definition into the Registry under its Model and registrant - the same path as Components and Relationships. A Model (carrying a registrant) is required. Definitions can also be managed over the registry API:

   Method	Endpoint	Purpose
   GET	/api/meshmodels/connections	List connection definitions
   GET	/api/meshmodels/connections/{id}	Fetch one definition
   POST	/api/meshmodels/connections	Register a definition (needs a Model)
   PUT	/api/meshmodels/connections/{id}	Update a definition
   DELETE	/api/meshmodels/connections/{id}	Remove a definition

2. Consumption. The Connection Wizard lists every registered definition as a creatable kind and renders its connectionSchema and credentialSchema as wizard steps. Register your definition and it appears in the wizard automatically - no UI changes required.

Advanced: customizing the wizard

The generic flow - choose → configure → credential → review → done, all derived from your schemas - covers most Connections. When a Connection needs bespoke steps (Kubernetes, for example, imports clusters from a kubeconfig and offers a MeshSync deployment-mode step), register a connection extension in the Meshery UI at ui/components/connections/wizard/registry.ts.

An extension matches a Connection by kind (optionally narrowed by type/subType) and may override any step; the most specific match wins, and any step left unset falls back to the generic default:

• detailsStep, credentialStep, registerStep, receiptStep - override individual steps. Set credentialStep: null to remove the credential step (Kubernetes carries its credential inline as a kubeconfig).
• postConfigSteps - extra steps appended after registration; these also drive the wizard’s configure mode for an already-registered Connection.

Each step implements a small contract - an id and label, a Component to render, and optional canProceed, onNext, nextLabel, and hidden hooks. Use the existing kubernetesExtension as a worked example, and see Contributing to the Meshery UI for building and testing UI changes.

Authoring best practices

1. Use camelCase for property names, matching the rest of Meshery’s schemas.
2. Keep the transitionMap consistent with the documented Connection states; do not invent states.
3. Mark only genuinely required fields as required in connectionSchema, and omit credentialSchema when no secret is needed.
4. Start from a shipped definition rather than from scratch.
5. Provide both svgColor and svgWhite icons so the kind renders well on light and dark backgrounds.

Contribute your Connection

Submit a pull request to the Meshery repository adding your connection definition to its Model’s connections/ folder, so every user benefits from the new Connection kind. Follow the contribution gitflow and sign off your commits.