@authorizedretailers/spec 0.1.0 → 0.2.0

package/schemas/0.2/list.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://authorizedretailers.ai/schemas/0.2/list.json",
+  "title": "Signed list (section 5.2)",
+  "type": "object",
+  "required": [
+    "spec",
+    "brand",
+    "public",
+    "issued",
+    "valid_until",
+    "stale_until",
+    "signature"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "$ref": "common.json#/$defs/specVersion"
+    },
+    "brand": {
+      "$ref": "common.json#/$defs/listBrand"
+    },
+    "public": {
+      "type": "boolean"
+    },
+    "issued": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "valid_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "stale_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "catalog": {
+      "type": "array",
+      "items": {
+        "$ref": "common.json#/$defs/product"
+      }
+    },
+    "exclusions": {
+      "$ref": "common.json#/$defs/exclusions"
+    },
+    "authorizations": {
+      "type": "array",
+      "items": {
+        "$ref": "common.json#/$defs/authorization"
+      }
+    },
+    "signature": {
+      "$ref": "common.json#/$defs/signature"
+    }
+  },
+  "if": {
+    "properties": {
+      "public": {
+        "const": true
+      }
+    }
+  },
+  "then": {
+    "required": [
+      "authorizations"
+    ]
+  },
+  "else": {
+    "not": {
+      "anyOf": [
+        {
+          "required": [
+            "authorizations"
+          ]
+        },
+        {
+          "required": [
+            "catalog"
+          ]
+        },
+        {
+          "required": [
+            "exclusions"
+          ]
+        }
+      ]
+    }
+  }
+}

package/schemas/0.2/pointer.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://authorizedretailers.ai/schemas/0.2/pointer.json",
+  "title": "authorized-retailers.json pointer (section 5.1)",
+  "type": "object",
+  "required": [
+    "spec",
+    "form",
+    "brand",
+    "verify_token",
+    "list"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "$ref": "common.json#/$defs/specVersion"
+    },
+    "form": {
+      "const": "pointer"
+    },
+    "brand": {
+      "$ref": "common.json#/$defs/brand"
+    },
+    "verify_token": {
+      "description": "The domain's public verification token (section 4).",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    },
+    "list": {
+      "$ref": "common.json#/$defs/registryUrl"
+    }
+  }
+}

package/schemas/0.2/revocation-feed.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://authorizedretailers.ai/schemas/0.2/revocation-feed.json",
+  "title": "Revocation feed (section 10.3)",
+  "type": "object",
+  "required": [
+    "spec",
+    "feed",
+    "issued",
+    "valid_until",
+    "stale_until",
+    "entries",
+    "signature"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "spec": {
+      "$ref": "common.json#/$defs/specVersion"
+    },
+    "feed": {
+      "const": "revocations"
+    },
+    "issued": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "valid_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "stale_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "revocation_id",
+          "revoked"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "revocation_id": {
+            "$ref": "common.json#/$defs/revocationId"
+          },
+          "revoked": {
+            "$ref": "common.json#/$defs/timestamp"
+          }
+        }
+      }
+    },
+    "signature": {
+      "$ref": "common.json#/$defs/signature"
+    }
+  }
+}

package/schemas/0.2/verify-request.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://authorizedretailers.ai/schemas/0.2/verify-request.json",
+  "title": "POST /v0/verify request (section 9)",
+  "description": "Canonical form. Call normalizeVerifyRequest on raw input first.",
+  "type": "object",
+  "required": [
+    "brand_domain",
+    "channel"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "brand_domain": {
+      "$ref": "common.json#/$defs/domain"
+    },
+    "channel": {
+      "$ref": "common.json#/$defs/channel"
+    },
+    "territory": {
+      "$ref": "common.json#/$defs/countryCode"
+    },
+    "product_line": {
+      "$ref": "common.json#/$defs/productLine"
+    },
+    "product": {
+      "description": "Exactly one of gtin or asin.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "gtin"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "gtin": {
+              "$ref": "common.json#/$defs/gtin"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "asin"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "asin": {
+              "$ref": "common.json#/$defs/asin"
+            }
+          }
+        }
+      ]
+    },
+    "as_of": {
+      "anyOf": [
+        {
+          "$ref": "common.json#/$defs/date"
+        },
+        {
+          "$ref": "common.json#/$defs/timestamp"
+        }
+      ]
+    }
+  }
+}

package/schemas/0.2/verify-response.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://authorizedretailers.ai/schemas/0.2/verify-response.json",
+  "title": "POST /v0/verify response (section 9)",
+  "type": "object",
+  "required": [
+    "status",
+    "checked",
+    "valid_until",
+    "stale_until",
+    "observed",
+    "signals",
+    "signature"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "status": {
+      "enum": [
+        "authorized",
+        "unlisted",
+        "expired",
+        "brand_not_registered",
+        "disputed"
+      ]
+    },
+    "reason": {
+      "enum": [
+        "not_registered",
+        "domain_unlinked",
+        "verification_lapsed",
+        "territory_mismatch",
+        "product_excluded",
+        "product_not_in_scope",
+        "product_not_in_catalog"
+      ]
+    },
+    "authorization_id": {
+      "$ref": "common.json#/$defs/id"
+    },
+    "revocation_id": {
+      "$ref": "common.json#/$defs/revocationId"
+    },
+    "expires": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "checked": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "as_of": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "valid_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "stale_until": {
+      "$ref": "common.json#/$defs/timestamp"
+    },
+    "product": {
+      "type": "object",
+      "required": [
+        "in_catalog"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "in_catalog": {
+          "type": "boolean"
+        },
+        "id": {
+          "$ref": "common.json#/$defs/id"
+        },
+        "product_line": {
+          "$ref": "common.json#/$defs/productLine"
+        }
+      },
+      "if": {
+        "properties": {
+          "in_catalog": {
+            "const": false
+          }
+        }
+      },
+      "then": {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "id"
+              ]
+            },
+            {
+              "required": [
+                "product_line"
+              ]
+            }
+          ]
+        }
+      }
+    },
+    "observed": {
+      "description": "Section 7: when the registry last saw this seller selling on the channel, within 30 days; otherwise null",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "required": [
+            "last_seen"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "last_seen": {
+              "$ref": "common.json#/$defs/timestamp"
+            }
+          }
+        }
+      ]
+    },
+    "signals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "type",
+          "observed"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]{0,63}$"
+          },
+          "observed": {
+            "$ref": "common.json#/$defs/timestamp"
+          },
+          "detail": {
+            "type": "string",
+            "maxLength": 1024
+          }
+        }
+      }
+    },
+    "signature": {
+      "$ref": "common.json#/$defs/signature"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "enum": [
+              "authorized",
+              "expired",
+              "disputed"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "authorization_id"
+        ]
+      },
+      "else": {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "authorization_id"
+              ]
+            },
+            {
+              "required": [
+                "expires"
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "expired"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "expires"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "authorized"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "revocation_id"
+        ]
+      },
+      "else": {
+        "properties": {
+          "observed": {
+            "const": null
+          }
+        },
+        "not": {
+          "required": [
+            "revocation_id"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "brand_not_registered"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "reason": {
+            "enum": [
+              "not_registered",
+              "domain_unlinked",
+              "verification_lapsed"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "unlisted"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "reason": {
+            "enum": [
+              "territory_mismatch",
+              "product_excluded",
+              "product_not_in_scope",
+              "product_not_in_catalog"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "enum": [
+              "authorized",
+              "expired",
+              "disputed"
+            ]
+          }
+        }
+      },
+      "then": {
+        "not": {
+          "required": [
+            "reason"
+          ]
+        }
+      }
+    }
+  ]
+}

package/spec/spec-v0.1.md

@@ -1,6 +1,6 @@
 # Authorized Retailers Specification v0.1
 
-Draft v0.1 · 23 September 2026, updated 25 September 2026  
+Draft v0.1 · 23 September 2026, updated 26 September 2026  
 Editor: Ed Jacobs
 
 Licensed under [CC BY 4.0](https://github.com/authorizedretailers/spec/blob/main/LICENSE-SPEC). JSON Schemas and reference code: Apache-2.0.
@@ -13,6 +13,8 @@ Status: draft v0.1, for discussion with brands, retailers and agent developers.
 
 The spec asserts one thing: whether a brand has authorized a given seller, on a given channel, in a given territory, for a given product scope, as of a given date.
 
+Scope: the spec covers consumer-facing online channels: marketplaces and web stores, including omnichannel retailers, which are identified by their web domain. Trade, wholesale and practitioner-only channels are out of scope. Sellers there are not listed, so their resale on consumer channels verifies as unlisted.
+
 It does not assert:
 
 - **Authenticity.** An authorized seller can still sell counterfeit goods or have its account compromised. Authorization and authenticity are separate questions.
@@ -123,7 +125,7 @@ An individual authorization's `expires` MUST NOT be later than the file's `expir
 
 ## 6. Seller identity and channel identifiers
 
-Agents see sellers as channel identifiers, not company names, so every authorization MUST name at least one channel identifier. A name alone is not verifiable.
+Agents see sellers as channel identifiers, not company names, so every authorization MUST name at least one online channel identifier (`amazon`, `walmart`, `ebay` or `web`). A name alone is not verifiable, and a `physical` identifier alone does not authorize anything.
 
 | Channel type | Required fields | Identifier |
 | --- | --- | --- |
@@ -131,7 +133,7 @@ Agents see sellers as channel identifiers, not company names, so every authoriza
 | `walmart` | `marketplace`, `seller_id` | Walmart Marketplace partner ID |
 | `ebay` | `marketplace`, `seller_id` | eBay user ID |
 | `web` | `domain` | The retailer's store domain |
-| `physical` | `address`, `country` | Store location, for completeness; not verifiable by agents |
+| `physical` | `address`, `country` | Optional storefront detail. Not a channel agents can verify, and never sufficient on its own |
 
 New channel types are added by registry proposal and published in the spec changelog.
 
@@ -260,6 +262,8 @@ The registry's liability position, dispute timelines and data handling are set o
 - [ ] Observation on channels beyond Amazon: Walmart and retailer web domains first?
 - [ ] Alignment with UCP and ACP: an extension field that points agents to a brand's authorized-retailers file.
 - [ ] Brand-declared `unauthorized`: a status for sellers the brand has explicitly said are not authorized, as distinct from `unlisted`, with a dispute path for the seller.
+- [ ] Dispensary and multi-seller platforms (e.g. practitioner dispensaries hosted on one platform domain): how to authorize individual sellers when agents only see the platform domain.
+- [ ] Channel audience: whether a channel needs an `audience` field (consumer, trade, practitioner) or whether consumer-only scope is enough.
 
 ## 14. Changelog
 
@@ -280,3 +284,7 @@ The registry's liability position, dispute timelines and data handling are set o
   - A registry MAY warn brands about sellers at PO boxes or commercial mailboxes. Verify answers don't change (section 12).
   - Corrected: the reference registry doesn't observe sellers yet (section 7).
   - Examples use reserved `.example` domains.
+- **2026-09-26**
+  - Scope: the spec covers consumer-facing online channels, including omnichannel retailers identified by their web domain. Trade, wholesale and practitioner-only channels are out of scope (section 1).
+  - Every authorization MUST name at least one online channel identifier (`amazon`, `walmart`, `ebay` or `web`). A `physical` identifier alone no longer authorizes anything (section 6).
+  - Two open questions: dispensary and multi-seller platforms, and a channel `audience` field (section 13).