Skip to main content

Publish an adapter

You need openssl and jq, and an owner or admin account in your organisation on Adapter Studio.

1. Make a signing key​

ZAITRACK accepts one algorithm: ECDSA on the P-256 curve over SHA-256, the signature in ASN.1 DER, base64.

openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl ec -in key.pem -pubout -out key.pub.pem

Keep key.pem secret: anyone holding it can sign versions as you. In Adapter Studio, Signing keys → Register a key, give it a name (2 to 80 characters) and paste key.pub.pem. The studio shows the key's fingerprint, SHA256: and the base64 SHA-256 of the DER public key.

2. Create the project​

Projects → New project: a slug (lowercase letters, digits and hyphens), the family (codec, connector, datasource, action or ai), a display name, a summary and description, an SPDX licence (LicenseRef-… for your own) and the visibility: public (any organisation can see and install its approved versions) or tenant-only (your organisation only).

3. Write the manifest​

adapter.json says who the adapter is, what it can do, the permissions it asks for and the settings an installation must give:

{
  "id": "acme-fleet-export",
  "family": "connector",
  "version": "1.0.0",
  "displayName": "Acme fleet export",
  "capabilities": ["export"],
  "permissions": ["trips:read"],
  "config": [
    {"key": "sftpHost", "type": "url", "required": true, "label": "SFTP host"},
    {"key": "password", "type": "secret", "required": true, "label": "Password"}
  ]
}
  • id: 3 to 64 characters, lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen. The version must be new for the project.
  • version: semantic versioning (1.0.0, 1.1.0-rc.1).
  • displayName: at least 3 characters.
  • config[].key: a letter, then letters, digits or _ (48 at most), each key once.
  • config[].type: text, number, url, secret or port. A secret setting is never shown back once given.

4. Sign the canonical manifest​

The registry signs and checks the canonical manifest: keys sorted, no insignificant whitespace, no trailing newline. Make it with jq, then sign it:

jq -cSj . adapter.json > manifest.canonical.json
openssl dgst -sha256 -sign key.pem manifest.canonical.json | base64 -w0 > signature.b64

Keep the characters &, < and > out of the manifest's strings: the registry writes them as \u0026, \u003c and \u003e and jq does not, so the signature would not match. On macOS, use base64 without -w0 (it does not wrap).

5. Submit the version​

Projects → your project → Submit a version: paste adapter.json, the content of signature.b64 and choose the key. Optionally give the artifact's address (https:// or oci://). The registry makes the manifest canonical, hashes it with SHA-256 and checks the signature against your key. A wrong signature or a revoked key is refused. The version waits as pending-review.

6. Review​

ZAITRACK staff run the conformance suite and record its result: coverage and how many checks passed and failed. A version is approved only with a run of at least 85 % coverage and no failures; staff approve with a note, or reject with a reason.

7. Installations​

Organisations install an approved version and fill in the settings your manifest declares. They can upgrade to another approved version, change settings, suspend, resume and uninstall. You see one installation per organisation, with its version and status.

An active installation is a registry state, not proof of a connected device or a prepared runtime. Before deployment, follow Codec readiness; keep approval, installation and device evidence separate.

Revoking a key​

Signing keys → Revoke, with a reason. In one step it revokes every version that key signed and suspends their installations; the key goes on the revocation list with when and why. An installation resumes once it is upgraded to a version that is not revoked: sign the next version with a new key.