@stellar-agent-services/protocol 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@stellar-agent-services/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Provider Standard v1 as code: manifest, job, receipt and header definitions shared by every package.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlgoriaLabs/stellar-agent-services.git",
+    "directory": "packages/protocol"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest.schema.json": "./schemas/manifest.schema.json",
+    "./verification-receipt.schema.json": "./schemas/verification-receipt.schema.json",
+    "./validation-request.schema.json": "./schemas/validation-request.schema.json",
+    "./test-vectors/*": "./test-vectors/*"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "test-vectors",
+    "!dist/.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "devDependencies": {
+    "@stellar/stellar-sdk": "16.4.1",
+    "@x402/stellar": "2.28.0",
+    "ajv": "8.20.0"
+  }
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,272 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider/1/manifest.schema.json",
+  "$comment": "The $id is provisional until the v1 freeze. Rule ids such as [M5] refer to docs/provider-standard.md.",
+  "title": "Provider Standard v1 manifest",
+  "description": "Describes a paid AI service on Stellar: its services, prices, payment option and job endpoints. Unknown fields are allowed and ignored [M8]. Some rules need code as well (§2.4): M1, M3, M5 (same origin), M7, S6, S9 and P11.",
+  "type": "object",
+  "required": ["standard", "provider", "baseUrl", "payment", "services"],
+  "properties": {
+    "standard": {
+      "description": "[M8] A manifest with a different major version is rejected.",
+      "const": "stellar-agent-services/provider@1"
+    },
+    "provider": { "$ref": "#/$defs/provider" },
+    "baseUrl": {
+      "description": "[M5] Job endpoints live under it. HTTPS, no user info, query, fragment, empty path segment or trailing slash. Same origin as the manifest URL, which is checked in code.",
+      "type": "string",
+      "maxLength": 300,
+      "pattern": "^https://[^\\s/?#@]+(/[^\\s/?#]+)*$"
+    },
+    "payment": { "$ref": "#/$defs/payment" },
+    "jobs": { "$ref": "#/$defs/jobs" },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 25,
+      "items": { "$ref": "#/$defs/service" }
+    },
+    "extensions": { "$ref": "#/$defs/extensions" }
+  },
+  "$defs": {
+    "provider": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "$ref": "#/$defs/line", "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "$ref": "#/$defs/text", "type": "string", "maxLength": 500 },
+        "homepage": { "$ref": "#/$defs/httpsUrl" },
+        "agentId": {
+          "description": "Stellar 8004 agent id (u32), needed for the identity check (§7).",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        },
+        "termsUrl": { "$ref": "#/$defs/httpsUrl" },
+        "dataUse": {
+          "type": "object",
+          "properties": {
+            "storesInputs": {
+              "description": "Whether inputs are kept after the job finishes.",
+              "type": "boolean"
+            },
+            "trainsOnInputs": {
+              "description": "Whether inputs are used to train models.",
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    },
+    "payment": {
+      "type": "object",
+      "required": ["protocol", "x402Version", "accepts"],
+      "properties": {
+        "protocol": { "const": "x402" },
+        "x402Version": { "const": 2 },
+        "accepts": {
+          "description": "[P1] Exactly one payment option in v1.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": { "$ref": "#/$defs/paymentOption" }
+        }
+      }
+    },
+    "paymentOption": {
+      "description": "x402 v2 PaymentRequirements field names, without amount, which comes from each service's price [P1].",
+      "type": "object",
+      "required": ["scheme", "network", "asset", "payTo", "maxTimeoutSeconds", "extra"],
+      "properties": {
+        "scheme": { "const": "exact" },
+        "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+        "asset": {
+          "description": "The USDC Stellar Asset Contract for the network.",
+          "type": "string"
+        },
+        "payTo": {
+          "description": "A G... account or C... contract address. Its checksum is checked in code [P11].",
+          "type": "string",
+          "pattern": "^[GC][A-D][A-Z2-7]{54}$"
+        },
+        "amount": false,
+        "maxTimeoutSeconds": { "type": "integer", "minimum": 30, "maximum": 300 },
+        "extra": {
+          "type": "object",
+          "required": ["areFeesSponsored"],
+          "properties": {
+            "areFeesSponsored": { "const": true }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "required": ["network"],
+            "properties": { "network": { "const": "stellar:testnet" } }
+          },
+          "then": {
+            "type": "object",
+            "properties": { "asset": { "const": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA" } }
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "required": ["network"],
+            "properties": { "network": { "const": "stellar:pubnet" } }
+          },
+          "then": {
+            "type": "object",
+            "properties": { "asset": { "const": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75" } }
+          }
+        }
+      ]
+    },
+    "jobs": {
+      "type": "object",
+      "properties": {
+        "retentionSeconds": {
+          "description": "How long results stay retrievable.",
+          "type": "integer",
+          "minimum": 3600,
+          "default": 86400
+        }
+      }
+    },
+    "service": {
+      "type": "object",
+      "required": ["name", "description", "price", "inputSchema", "outputSchema"],
+      "properties": {
+        "name": {
+          "description": "Unique in the manifest [M7]. A URL path segment, an MCP tool name and an LLM function name.",
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "title": { "$ref": "#/$defs/line", "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "$ref": "#/$defs/text", "type": "string", "minLength": 1, "maxLength": 1000 },
+        "price": {
+          "type": "object",
+          "required": ["amount"],
+          "properties": {
+            "amount": {
+              "description": "A positive integer in the asset's base units. USDC has 7 decimals, so \"100000\" is 0.01 USDC.",
+              "type": "string",
+              "pattern": "^[1-9][0-9]{0,37}$"
+            }
+          }
+        },
+        "charge": {
+          "description": "When the user is charged (§3.2).",
+          "enum": ["on-success", "upfront"],
+          "default": "upfront"
+        },
+        "expectedDurationSeconds": { "type": "integer", "minimum": 1 },
+        "inputSchema": { "$ref": "#/$defs/objectSchema" },
+        "outputSchema": { "$ref": "#/$defs/objectSchema" },
+        "examples": {
+          "description": "Each input and output must match the service's schemas, which is checked in code [S9].",
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "required": ["input", "output"],
+            "properties": {
+              "input": { "type": "object" },
+              "output": { "type": "object" }
+            }
+          }
+        },
+        "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 10485760, "default": 1048576 },
+        "tags": {
+          "type": "array",
+          "maxItems": 10,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" }
+        },
+        "capacity": {
+          "description": "How much load the service takes (§5.8). Hints only: the provider's 429, 503 and queue answers are what count.",
+          "type": "object",
+          "properties": {
+            "concurrency": {
+              "description": "Jobs the service runs at the same time.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxQueueWaitSeconds": {
+              "description": "Longest a new job may expect to wait in the queue; beyond it, create-job answers 503. 0 means no queue.",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "extensions": { "$ref": "#/$defs/extensions" }
+      },
+      "if": {
+        "type": "object",
+        "required": ["charge"],
+        "properties": { "charge": { "const": "on-success" } }
+      },
+      "then": { "type": "object", "required": ["expectedDurationSeconds"] }
+    },
+    "objectSchema": {
+      "description": "[S4] A JSON Schema 2020-12 schema whose root is \"type\": \"object\". [S5] It references nothing outside itself. Its size is checked in code [S6].",
+      "allOf": [
+        { "$ref": "https://json-schema.org/draft/2020-12/schema" },
+        { "$ref": "#/$defs/localReferencesOnly" },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": { "type": { "const": "object" } }
+        }
+      ]
+    },
+    "localReferencesOnly": {
+      "description": "[S5] Wherever they appear, $ref and $dynamicRef start with \"#\", and $schema is JSON Schema 2020-12. Deliberately conservative: it also applies inside const, enum, default and examples.",
+      "if": { "type": "object" },
+      "then": {
+        "type": "object",
+        "properties": {
+          "$ref": { "$ref": "#/$defs/localReference" },
+          "$dynamicRef": { "$ref": "#/$defs/localReference" },
+          "$schema": {
+            "if": { "type": "string" },
+            "then": { "type": "string", "const": "https://json-schema.org/draft/2020-12/schema" },
+            "else": { "$ref": "#/$defs/localReferencesOnly" }
+          }
+        },
+        "additionalProperties": { "$ref": "#/$defs/localReferencesOnly" }
+      },
+      "else": {
+        "if": { "type": "array" },
+        "then": { "type": "array", "items": { "$ref": "#/$defs/localReferencesOnly" } }
+      }
+    },
+    "localReference": {
+      "if": { "type": "string" },
+      "then": { "type": "string", "pattern": "^#" },
+      "else": { "$ref": "#/$defs/localReferencesOnly" }
+    },
+    "httpsUrl": {
+      "description": "[M6] An HTTPS URL of at most 300 characters, without user info.",
+      "type": "string",
+      "maxLength": 300,
+      "pattern": "^https://[^\\s/?#@]+([/?#]\\S*)?$"
+    },
+    "line": {
+      "description": "Text without control characters.",
+      "type": "string",
+      "pattern": "^[^\u0000-\u001f\u007f]*$"
+    },
+    "text": {
+      "description": "Text that may contain tabs and newlines but no other control characters.",
+      "type": "string",
+      "pattern": "^[^\u0000-\u0008\u000b-\u001f\u007f]*$"
+    },
+    "extensions": {
+      "description": "[X1] Fields outside this standard. Keys SHOULD be reverse-DNS names such as com.example.sla.",
+      "type": "object"
+    }
+  }
+}

package/schemas/validation-request.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider/1/validation-request.schema.json",
+  "$comment": "Rule ids such as [I1] refer to docs/provider-standard.md; the request itself is described in docs/verification.md.",
+  "title": "Provider Standard v1 validation request",
+  "description": "What a provider's owner asks a verifier to check, in a Stellar 8004 validation_request. It is published as RFC 8785 canonical JSON: the SHA-256 of those bytes is the request_hash, and the request_uri holds the same bytes. Unknown fields are allowed and ignored, but they are hashed with the rest.",
+  "type": "object",
+  "required": ["standard", "type", "agentId", "network", "manifest", "validator", "requestedAt"],
+  "properties": {
+    "standard": { "const": "stellar-agent-services/provider@1" },
+    "type": { "const": "validation-request" },
+    "agentId": {
+      "description": "The provider's Stellar 8004 agent id (u32).",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 4294967295
+    },
+    "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+    "manifest": {
+      "description": "The manifest to check.",
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": {
+          "description": "The HTTPS URL the agent's registration names [I1].",
+          "type": "string",
+          "maxLength": 2048,
+          "pattern": "^https://[^\\s]+$"
+        }
+      }
+    },
+    "validator": {
+      "description": "The verifier's account: the only one that may answer the request.",
+      "type": "string",
+      "pattern": "^G[A-D][A-Z2-7]{54}$"
+    },
+    "requestedAt": {
+      "description": "RFC 3339. It makes each request unique: the registry refuses a request_hash it already has.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$"
+    }
+  }
+}

package/schemas/verification-receipt.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider/1/verification-receipt.schema.json",
+  "$comment": "Rule ids such as [P4] refer to docs/provider-standard.md; the receipt itself is described in docs/verification.md.",
+  "title": "Provider Standard v1 verification receipt",
+  "description": "What a verifier issues after checking a provider. It is published as RFC 8785 canonical JSON, and the SHA-256 of those bytes is the Stellar 8004 Validation Registry response_hash. Unknown fields are allowed and ignored. Two rules need code as well: level is the highest conformance level whose checks all passed, and score is that level's score.",
+  "type": "object",
+  "required": ["standard", "network", "validator", "startedAt", "checkedAt", "score", "scoreDirection", "level", "manifest", "results"],
+  "properties": {
+    "standard": { "const": "stellar-agent-services/provider@1" },
+    "agentId": {
+      "description": "The provider's Stellar 8004 agent id (u32). Required to publish the receipt to the Validation Registry.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 4294967295
+    },
+    "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+    "validator": {
+      "description": "The verifier's account, which signs validation_response.",
+      "type": "string",
+      "pattern": "^G[A-D][A-Z2-7]{54}$"
+    },
+    "startedAt": { "$ref": "#/$defs/timestamp" },
+    "checkedAt": { "$ref": "#/$defs/timestamp" },
+    "score": {
+      "description": "The level's score, and the on-chain response: 0, 33, 67 or 100 for levels 0 to 3.",
+      "enum": [0, 33, 67, 100]
+    },
+    "scoreDirection": { "const": "higher-is-better" },
+    "level": { "enum": [0, 1, 2, 3] },
+    "manifest": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "sha256": {
+          "description": "SHA-256 of the parsed manifest as canonical JSON. Absent when the manifest could not be read as JSON.",
+          "$ref": "#/$defs/sha256"
+        }
+      }
+    },
+    "results": {
+      "description": "One result per check, in order from C1 to C7.",
+      "type": "array",
+      "prefixItems": [
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C1" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C2" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C3" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C4" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C5" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C6" } } },
+        { "$ref": "#/$defs/checkResult", "type": "object", "properties": { "check": { "const": "C7" } } }
+      ],
+      "minItems": 7,
+      "items": false
+    },
+    "payment": { "$ref": "#/$defs/paymentReceipt" },
+    "tool": {
+      "description": "The software that issued the receipt.",
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+        "version": { "type": "string", "minLength": 1, "maxLength": 50 }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "type": "object", "properties": { "level": { "const": 0 } } },
+      "then": { "type": "object", "properties": { "score": { "const": 0 } } }
+    },
+    {
+      "if": { "type": "object", "properties": { "level": { "const": 1 } } },
+      "then": { "type": "object", "properties": { "score": { "const": 33 } } }
+    },
+    {
+      "if": { "type": "object", "properties": { "level": { "const": 2 } } },
+      "then": { "type": "object", "properties": { "score": { "const": 67 } } }
+    },
+    {
+      "if": { "type": "object", "properties": { "level": { "const": 3 } } },
+      "then": { "type": "object", "properties": { "score": { "const": 100 } } }
+    }
+  ],
+  "$defs": {
+    "timestamp": {
+      "description": "RFC 3339.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$"
+    },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "rule": {
+      "description": "A rule id such as P4, or a section such as §5.5 for a requirement without an id.",
+      "type": "string",
+      "pattern": "^(?:[A-Z][0-9]{1,2}|§[0-9]{1,2}(?:\\.[0-9]{1,2})?)$"
+    },
+    "checkResult": {
+      "type": "object",
+      "required": ["check", "status", "failedRules"],
+      "properties": {
+        "check": { "enum": ["C1", "C2", "C3", "C4", "C5", "C6", "C7"] },
+        "status": { "enum": ["passed", "failed", "skipped"] },
+        "failedRules": { "type": "array", "items": { "$ref": "#/$defs/rule" }, "uniqueItems": true },
+        "warnings": { "type": "array", "items": { "$ref": "#/$defs/rule" }, "uniqueItems": true },
+        "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "findings": {
+          "type": "array",
+          "maxItems": 50,
+          "items": {
+            "type": "object",
+            "required": ["rule", "severity", "message"],
+            "properties": {
+              "rule": { "$ref": "#/$defs/rule" },
+              "severity": { "enum": ["fail", "warn"] },
+              "message": { "type": "string", "minLength": 1, "maxLength": 500 }
+            }
+          }
+        },
+        "evidence": { "type": "object" }
+      },
+      "allOf": [
+        {
+          "if": { "type": "object", "properties": { "status": { "const": "failed" } } },
+          "then": { "type": "object", "properties": { "failedRules": { "type": "array", "minItems": 1 } } },
+          "else": { "type": "object", "properties": { "failedRules": { "type": "array", "maxItems": 0 } } }
+        },
+        {
+          "if": { "type": "object", "properties": { "status": { "const": "skipped" } } },
+          "then": { "type": "object", "required": ["reason"] }
+        }
+      ]
+    },
+    "paymentReceipt": {
+      "description": "The C4 payment, as the job view reported it (provider-standard.md §5.7), after the verifier confirmed it on chain.",
+      "type": "object",
+      "required": ["network", "asset", "amount", "payTo", "payer", "transaction", "settledAt"],
+      "properties": {
+        "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+        "asset": { "type": "string", "pattern": "^C[A-D][A-Z2-7]{54}$" },
+        "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,37}$" },
+        "payTo": { "type": "string", "pattern": "^[GC][A-D][A-Z2-7]{54}$" },
+        "payer": { "type": "string", "pattern": "^[GC][A-D][A-Z2-7]{54}$" },
+        "transaction": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "settledAt": { "$ref": "#/$defs/timestamp" }
+      }
+    }
+  }
+}

package/test-vectors/README.md

@@ -0,0 +1,45 @@
+# Provider Standard v1 test vectors
+
+Known-answer tests for [Provider Standard v1](../../../docs/provider-standard.md). An implementation in any
+language can check itself against these files. `packages/protocol` runs all of them in its own tests.
+
+| File | What it pins | Spec |
+| --- | --- | --- |
+| `canonical-json.json` | RFC 8785 canonical JSON and its SHA-256, including the RFC's own examples | §5.3, verification receipts |
+| `binding-hash.json` | The job binding hash | §5.3 |
+| `headers.json` | `Idempotency-Key` and `Job-Token` formats | §5.2 |
+| `manifests.json` | Manifest validation: the JSON Schema and the rules it can't express | §2.4 |
+| `challenges.json` | Checking an x402 challenge against the approved manifest | §4.2 |
+| `job-states.json` | Allowed job state transitions and the `charged` value of each state | §5.6 |
+| `problems.json` | Error codes, their HTTP status and Retry-After, and job failure codes | §6 |
+| `validation-requests.json` | Validation request documents: their canonical bytes, `request_hash` and `data:` URI, and the JSON Schema | [verification.md](../../../docs/verification.md#stellar-8004-validation-registry) |
+
+## Conventions
+
+- **Patches.** `manifests.json` and `challenges.json` describe each case as a small change to a base document,
+  using the `add`, `replace` and `remove` operations of JSON Patch (RFC 6902). A last path segment of `-`
+  appends to an array.
+- **Violations.** Each `{ "rule", "pointer" }` is a rule id from the spec and a JSON Pointer (RFC 6901) to the
+  offending value, or to where a missing field belongs. Compare them as a set. Messages are not part of the
+  vectors.
+- **`checkedBy`.** In `manifests.json`, `"schema"` cases fail the
+  [manifest JSON Schema](../schemas/manifest.schema.json). `"code"` cases pass it and fail only the rules JSON
+  Schema can't express. If you validate in code only, every invalid case must still fail.
+- **Numbers** are IEEE 754 doubles, as I-JSON requires. Integers beyond ±(2^53 − 1) aren't interoperable, so the
+  vectors avoid them. Services should send such values as strings.
+- **Duplicate keys** make a document invalid I-JSON, but many parsers can't detect them, so no vector covers
+  them.
+
+## How they were made
+
+The expected values were generated once and checked before they were written:
+- canonical JSON against the independent [`canonicalize`](https://github.com/erdtman/canonicalize) package by an
+  RFC 8785 author;
+- the RFC 8785 examples (§3.2.2, §3.2.3, Appendix B) against the text of the RFC;
+- hashes against a second SHA-256 implementation;
+- every manifest and challenge case against Ajv with the JSON Schema, and against `packages/protocol`;
+- validation requests with Python's `json`, `hashlib` and `base64` modules, apart from `packages/protocol`, and the
+  hashes again with `shasum`;
+- job states and error codes by hand from the tables in §5.6 and §6.
+
+When you change a vector, run `npm test` and review the diff by hand.

package/test-vectors/binding-hash.json

@@ -0,0 +1,64 @@
+{
+  "description": "The job binding hash of provider-standard.md §5.3: bindingHash = lowercase hex SHA-256 of the RFC 8785 canonical JSON of {\"service\": service, \"input\": input}. `canonical` shows the bytes that are hashed.",
+  "cases": [
+    {
+      "name": "the text-stats example",
+      "service": "text-stats",
+      "input": { "text": "Hello world." },
+      "canonical": "{\"input\":{\"text\":\"Hello world.\"},\"service\":\"text-stats\"}",
+      "bindingHash": "3d3b3dbdf90621535bd77d1f1d2a1ed0334bf875c7dc7c023caa48cad949ce87"
+    },
+    {
+      "name": "key order does not matter (1 of 2)",
+      "service": "translate",
+      "input": { "text": "Good morning", "target": "tr", "source": "en" },
+      "canonical": "{\"input\":{\"source\":\"en\",\"target\":\"tr\",\"text\":\"Good morning\"},\"service\":\"translate\"}",
+      "bindingHash": "1727298e87acb5642a49ceed3cfca3012e3d90c8ddae8642aec5b21c5d40531d"
+    },
+    {
+      "name": "key order does not matter (2 of 2)",
+      "service": "translate",
+      "input": { "source": "en", "target": "tr", "text": "Good morning" },
+      "canonical": "{\"input\":{\"source\":\"en\",\"target\":\"tr\",\"text\":\"Good morning\"},\"service\":\"translate\"}",
+      "bindingHash": "1727298e87acb5642a49ceed3cfca3012e3d90c8ddae8642aec5b21c5d40531d"
+    },
+    {
+      "name": "the service name is part of the binding",
+      "service": "summarize",
+      "input": { "text": "Hello world." },
+      "canonical": "{\"input\":{\"text\":\"Hello world.\"},\"service\":\"summarize\"}",
+      "bindingHash": "6b84191b4fce4a19ae8e51b637df8dd5c0d349a57e00d416c729a2ee2a942882"
+    },
+    {
+      "name": "numbers use RFC 8785 formatting",
+      "service": "image-generate",
+      "input": { "prompt": "a lighthouse at dusk", "width": 1024, "guidance": 7.5, "ratio": 0.5625, "seed": 0 },
+      "canonical": "{\"input\":{\"guidance\":7.5,\"prompt\":\"a lighthouse at dusk\",\"ratio\":0.5625,\"seed\":0,\"width\":1024},\"service\":\"image-generate\"}",
+      "bindingHash": "197fad97c66e72f70045bcaf8433a6e11185fc76ddc4789c86d82032856e5d5a"
+    },
+    {
+      "name": "nested objects are sorted, arrays keep their order",
+      "service": "batch-classify",
+      "input": {
+        "items": [{ "text": "Second", "id": "b" }, { "text": "First", "id": "a" }],
+        "labels": ["spam", "ham"]
+      },
+      "canonical": "{\"input\":{\"items\":[{\"id\":\"b\",\"text\":\"Second\"},{\"id\":\"a\",\"text\":\"First\"}],\"labels\":[\"spam\",\"ham\"]},\"service\":\"batch-classify\"}",
+      "bindingHash": "8695964e2a63c73facb3cc46fb9ed3df5c4e8716ba3e1b909d8b15b3b4473e1b"
+    },
+    {
+      "name": "non-ASCII text, quotes and newlines",
+      "service": "text-stats",
+      "input": { "text": "Merhaba dünya 🌍\n\"quoted\"" },
+      "canonical": "{\"input\":{\"text\":\"Merhaba dünya 🌍\\n\\\"quoted\\\"\"},\"service\":\"text-stats\"}",
+      "bindingHash": "2ed5ae38386e9a30c98a4d38d497278d6059360ce066fb30f96fa351ebc25b51"
+    },
+    {
+      "name": "an empty input object",
+      "service": "ping",
+      "input": {},
+      "canonical": "{\"input\":{},\"service\":\"ping\"}",
+      "bindingHash": "76658c27819d7e93b8ed15f1a81519b33ae76c1c765185daaf380fa252176000"
+    }
+  ]
+}