Skip to main content
Link Studio With Link Studio you can author and import your own protocols. A protocol is a JSON document validated against the Link protocol meta-schema (link-protocol-v1) at import time; a document that does not conform is rejected.
Custom protocols require Link Studio. Link Connect runs Hellgate-published protocols only. See Protocols for the concept.
The meta-schema is JSON Schema (draft 2020-12) and is served by every instance: 
curl https://developer.hellgate.io/schemas/link-protocol/v1

​
Top-level structure

A protocol document has these fields (additionalProperties is false — unknown top-level keys are rejected):
FieldRequiredDescription
$schemayesReference to the meta-schema: https://developer.hellgate.io/schemas/link-protocol/v1
$idyesCanonical URI identifying this protocol. Backends reference the protocol by this URI; it is the join key.
nameyesHuman-readable protocol name.
versionyesVersion identifier (a string, for example 1.0.0).
actionsyesMap of action name → Action. At least one action is required.
componentsnoReusable schemas referenced via $ref (see Components).

​
Actions

actions is keyed by action name. Names may use dot notation to namespace related operations (for example notify.chargeback). Each action is an object (additionalProperties: false):
FieldRequiredDescription
methodyesHTTP method: POST, GET, PUT, PATCH, or DELETE. Callers must invoke with this method.
descriptionyesHuman-readable description of the action.
requestyesThe input definition — monomorphic or discriminated.
responsesyesOutput definitions keyed by HTTP status (see Responses).
requirednoWhether backends must implement this action. Defaults to false.

​
Requests

request is one of two shapes.

​
Monomorphic — a single schema

The request is a single JSON Schema: 
"request": {
  "type": "object",
  "properties": {
    "transaction": { "$ref": "#/components/schemas/Transaction" }
  },
  "required": ["transaction"]
}

​
Discriminated — a polymorphic union

A discriminator field selects a named variant. Each variant is a JSON Schema:
FieldRequiredDescription
discriminatoryesA JSONPath expression pointing to the discriminator field, for example $.credential.type.
variantsyesMap of discriminator value → JSON Schema. At least one variant.
required_variantsnoVariant names backends must implement. Each must exist in variants.
"request": {
  "discriminator": "$.credential.type",
  "variants": {
    "pan": { "$ref": "#/components/schemas/PanRequest" },
    "token": { "$ref": "#/components/schemas/TokenRequest" }
  },
  "required_variants": ["pan"]
}
Backends implement a discriminated action by its action.variant key (for example assess.pan). See Backends.

​
Responses

responses is keyed by HTTP status code (a string matching ^[1-5][0-9]{2}$), with at least one entry. Each entry nests the schema under content → application/json → schema: 
"responses": {
  "200": {
    "content": {
      "application/json": {
        "schema": { "$ref": "#/components/schemas/AssessResult" }
      }
    }
  }
}
Backend response mappings target these status codes and are validated against the corresponding schema at backend-write time — see Backends.

​
Components

components.schemas holds reusable schemas referenced from anywhere in the protocol via a JSON Pointer $ref (for example #/components/schemas/Transaction): 
"components": {
  "schemas": {
    "Transaction": {
      "type": "object",
      "properties": {
        "amount": { "type": "integer" },
        "currency": { "type": "string" }
      },
      "required": ["amount", "currency"]
    }
  }
}

​
Supported JSON Schema keywords

Schemas (in requests, responses, and components) are JSON Schema. The meta-schema explicitly lists the supported keywords; full validation is delegated to a JSON Schema validator (draft 2020-12): type, const, enum, properties, required, additionalProperties, items, oneOf, anyOf, allOf, $ref, description, format, minimum, maximum, minLength, maxLength, pattern.

​
Complete example

A minimal but valid protocol with one discriminated assess action and shared components: 
{
  "$schema": "https://developer.hellgate.io/schemas/link-protocol/v1",
  "$id": "https://acme.example/protocols/risk/v1",
  "name": "Acme Risk",
  "version": "1.0.0",
  "actions": {
    "assess": {
      "method": "POST",
      "description": "Score a transaction for fraud risk.",
      "request": {
        "discriminator": "$.credential.type",
        "variants": {
          "pan": {
            "type": "object",
            "properties": {
              "credential": { "$ref": "#/components/schemas/PanCredential" },
              "transaction": { "$ref": "#/components/schemas/Transaction" }
            },
            "required": ["credential", "transaction"]
          }
        },
        "required_variants": ["pan"]
      },
      "responses": {
        "200": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": { "const": "enum" },
                  "value": { "type": "string", "enum": ["ALLOW", "REVIEW", "BLOCK"] },
                  "backend_reference": { "type": "string" }
                },
                "required": ["type", "value"]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PanCredential": {
        "type": "object",
        "properties": {
          "type": { "const": "pan" },
          "pan": {
            "type": "object",
            "properties": {
              "value": { "type": "string" },
              "expiry_month": { "type": "integer" },
              "expiry_year": { "type": "integer" }
            },
            "required": ["value"]
          }
        },
        "required": ["type", "pan"]
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string" }
        },
        "required": ["amount", "currency"]
      }
    }
  }
}

​
Import and validation

Import a protocol you authored with Link Studio — by URL or by posting the document directly. Requires admin:protocols:write. 
# Import by URL
curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://acme.example/protocols/risk/v1"}'

# Or create from the document
curl -X POST https://{instance}.eu1.on-hellgate.cloud/api/admin/protocols \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @risk-v1.json
At import, Link validates the document against the meta-schema and rejects anything non-conforming. Studio also lifts the default restriction that limits imports to Hellgate-published protocol URLs, so your own $id is accepted. Once imported, Link generates an OpenAPI 3.1 specification for the protocol — see Protocols.

​
Next steps

Backends

Bind your protocol to a real provider with mapping rules.

Protocols

The protocol concept — actions, variants, and versioning.