Listing

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/surfingdog-ai/json-schema/surfingdog-ai-listing-schema.json",
  "title": "Listing",
  "description": "A listed business. Name, description, city, address, tags and services are the business's own words. Nothing about any customer is ever returned.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/network-openapi.json#/components/schemas/Listing",
  "type": "object",
  "required": [
    "domain",
    "name",
    "categories",
    "tags",
    "languages",
    "item_types",
    "protocols",
    "open_now",
    "services",
    "receipts",
    "answering",
    "online",
    "not_answering_since"
  ],
  "properties": {
    "domain": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "address": {
      "$ref": "#/$defs/Address"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Slugs of GET /v1/categories."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "item_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What its inbox takes."
    },
    "protocols": {
      "type": "object",
      "description": "Protocol name → the inbox's entry URL. Book, order or ask at mcp, rest or openapi; the others, the owner's own door (mcp_owner) among them, are not for customers.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "hours": {
      "$ref": "#/$defs/Hours"
    },
    "open_now": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "null: it published no hours."
    },
    "services": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Service"
      }
    },
    "geo": {
      "type": "object",
      "required": [
        "lat",
        "lng"
      ],
      "properties": {
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        }
      }
    },
    "distance_km": {
      "type": "number",
      "minimum": 0,
      "description": "Near searches only."
    },
    "location_precision": {
      "type": "string",
      "enum": [
        "town"
      ],
      "description": "town: the listing's position is the centre of the town its own site names (GeoNames), not its own place, so distance_km is from there, in whole kilometres, and it has no geo."
    },
    "url": {
      "type": "string",
      "description": "The business's own web site."
    },
    "manifest_url": {
      "type": "string",
      "format": "uri",
      "description": "Always present for a member."
    },
    "verified_at": {
      "type": "string",
      "format": "date-time",
      "description": "Always present for a member."
    },
    "last_ping_at": {
      "type": "string",
      "format": "date-time"
    },
    "software": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "runtime": {
          "type": "string"
        }
      }
    },
    "receipts": {
      "$ref": "#/$defs/Receipts"
    },
    "answering": {
      "type": "boolean",
      "description": "Its inbox answered within the last day."
    },
    "online": {
      "type": "boolean",
      "description": "The same as answering."
    },
    "not_answering_since": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "rank_pos": {
      "type": "integer",
      "minimum": 1,
      "description": "Its place in this hour's order."
    },
    "rank_shuffle": {
      "type": "string",
      "pattern": "^[0-9a-f]{16}$",
      "description": "The day's shuffle key: a string, never a number."
    },
    "reputation": {
      "$ref": "#/$defs/Reputation"
    },
    "track_record": {
      "$ref": "#/$defs/TrackRecord"
    },
    "source": {
      "type": "string",
      "enum": [
        "member",
        "registered",
        "found"
      ],
      "description": "member: through its inbox; registered: by the business, with a proof; found: by this network on its own website."
    },
    "claimed": {
      "type": "boolean"
    },
    "proof": {
      "type": "string",
      "enum": [
        "domain",
        "key",
        "platform",
        "code"
      ]
    },
    "level": {
      "type": "string",
      "enum": [
        "listed",
        "readable",
        "askable",
        "bookable",
        "orderable",
        "payable"
      ],
      "description": "The highest level of its live doors: bookable when one of them takes bookings, orderable when they take orders and no bookings."
    },
    "has_inbox": {
      "type": "boolean"
    },
    "doors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Door"
      }
    },
    "requestable": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ask",
          "quote"
        ]
      },
      "description": "The kinds a live door declared it answers."
    },
    "accepts": {
      "type": "object",
      "required": [
        "kinds"
      ],
      "properties": {
        "kinds": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "ask",
              "quote",
              "book",
              "order",
              "pay"
            ]
          }
        },
        "pay": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Payment tokens of GET /v1/attributes: how a customer or their agent can pay."
        },
        "pay_with": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PayWith"
          },
          "description": "Each of pay with its evidence, in the vocabulary's order."
        }
      }
    },
    "category": {
      "type": "object",
      "required": [
        "primary",
        "alternates",
        "path"
      ],
      "properties": {
        "primary": {
          "$ref": "#/$defs/PlaceCategory"
        },
        "alternates": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/PlaceCategory"
          }
        },
        "path": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "group": {
          "type": "string"
        }
      }
    },
    "attributes": {
      "type": "object",
      "description": "Keys of GET /v1/attributes, each with its value and source.",
      "additionalProperties": {
        "type": "object",
        "required": [
          "v",
          "src"
        ],
        "properties": {
          "v": {
            "type": [
              "boolean",
              "string",
              "number"
            ]
          },
          "src": {
            "type": "string",
            "enum": [
              "declared",
              "seen",
              "probably"
            ]
          }
        }
      }
    },
    "place": {
      "type": "object",
      "description": "For a business that is not a member: its town, region and country, never the street until it claims its entry.",
      "required": [
        "kind"
      ],
      "properties": {
        "locality": {
          "type": "string"
        },
        "region": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        },
        "kind": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "storefront",
              "service_area",
              "online"
            ]
          }
        },
        "service_area": {
          "type": "object",
          "properties": {
            "radius_km": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 300
            },
            "countries": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "string"
              }
            }
          }
        },
        "ships_to": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "why": {
      "type": "string",
      "description": "Why it is in this place of the list, in plain words."
    },
    "found": {
      "type": "object",
      "required": [
        "note",
        "checked_at",
        "about_url"
      ],
      "properties": {
        "note": {
          "type": "string"
        },
        "checked_at": {
          "type": "string",
          "format": "date-time"
        },
        "about_url": {
          "type": "string",
          "format": "uri",
          "description": "Why it is here, and how to correct it or opt out."
        }
      }
    },
    "outcomes": {
      "type": "object",
      "description": "On a single business only: how many of its promises closed with each outcome code.",
      "additionalProperties": {
        "type": "integer",
        "minimum": 0
      }
    },
    "facts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Fact"
      },
      "description": "On a single business that is not a member: every displayed value with its source and date."
    },
    "door_history": {
      "$ref": "#/$defs/DoorHistory"
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "The street only when the business published one.",
      "properties": {
        "street": {
          "type": "string"
        },
        "locality": {
          "type": "string"
        },
        "postal_code": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        }
      }
    },
    "Door": {
      "type": "object",
      "description": "A machine door the business published for agents; mail, phone, messaging, forms and web pages are never doors.",
      "required": [
        "type",
        "url",
        "level",
        "status",
        "kinds",
        "src"
      ],
      "properties": {
        "type": {
          "type": "string",
          "pattern": "^(inbox|mcp|a2a|openapi|api|ucp|acp|nlweb|webhook|other|platform:[a-z0-9-]{1,40})$"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "level": {
          "type": "string",
          "enum": [
            "listed",
            "readable",
            "askable",
            "bookable",
            "orderable",
            "payable"
          ],
          "description": "bookable for a door that takes bookings, orderable for one that takes orders and no bookings."
        },
        "status": {
          "type": "string",
          "enum": [
            "live",
            "failing"
          ]
        },
        "kinds": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "ask",
              "quote",
              "book",
              "order",
              "pay"
            ]
          }
        },
        "src": {
          "type": "string",
          "enum": [
            "declared",
            "seen"
          ]
        },
        "protocol": {
          "type": "string"
        },
        "checked_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "DoorHistory": {
      "type": "object",
      "description": "On a single business: what this network's own reads found of the doors it shows, kept for good, one line a day (protocol §4.8). Each door type at each host, the doors there now first: the first and last day a read found it answering and on how many days, and for a door read every day (a member's, a claimed listing's), from 14 checked days, its daily checks: a day is answered only when every check that day answered; one missed (failed, or blocked while the door is down by the network's reads) or refused (blocked otherwise) is not. A read an agent's report or the business asked for is no check, and no agent's report enters any of it. Absent when there is nothing to say.",
      "required": [
        "as_of",
        "doors"
      ],
      "properties": {
        "as_of": {
          "type": "string",
          "format": "date"
        },
        "doors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "host",
              "first_seen",
              "last_seen",
              "days_seen",
              "current"
            ],
            "properties": {
              "type": {
                "type": "string",
                "pattern": "^(inbox|mcp|a2a|openapi|api|ucp|acp|nlweb|webhook|other|platform:[a-z0-9-]{1,40})$",
                "description": "A door type (inbox, mcp, a2a, platform:shopify and the rest)."
              },
              "host": {
                "type": "string"
              },
              "first_seen": {
                "type": "string",
                "format": "date",
                "description": "The first UTC day a read of ours found a door of this type at this host answering."
              },
              "last_seen": {
                "type": "string",
                "format": "date",
                "description": "The last such day."
              },
              "days_seen": {
                "type": "integer",
                "minimum": 1,
                "description": "On how many days a read of ours found it answering: a door the crawl reads about once a month is seen on few days, and nothing is said of the days between."
              },
              "current": {
                "type": "boolean",
                "description": "Whether a door of this type is at this host now."
              },
              "checks": {
                "type": "object",
                "description": "A door read every day, from 14 checked days: the first and last day checked, the days checked, answered and refused, and the last 90 days ending on as_of (a every check answered, x one was missed, b one was refused and none missed, . no check).",
                "required": [
                  "first_checked",
                  "last_checked",
                  "days",
                  "answered",
                  "refused",
                  "recent"
                ],
                "properties": {
                  "first_checked": {
                    "type": "string",
                    "format": "date"
                  },
                  "last_checked": {
                    "type": "string",
                    "format": "date"
                  },
                  "days": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "answered": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "refused": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Days on which a check was refused (blocked while the door was not down) and none missed."
                  },
                  "recent": {
                    "type": "string",
                    "pattern": "^[axb.]{90}$"
                  }
                }
              },
              "summary": {
                "type": "string",
                "description": "With checks, in English: \"Answered every check on 41 of 42 days checked since 3 Oct 2026 (97%).\" The share is floored, the days refused follow it (\"(75%; refused our check on 5)\"), and it says \"from … to …\" when the last check is more than 7 days old. Informative: another network may word it its own way."
              }
            }
          }
        }
      }
    },
    "Fact": {
      "type": "object",
      "description": "A displayed value with its source and date.",
      "required": [
        "field",
        "v",
        "src",
        "at"
      ],
      "properties": {
        "field": {
          "type": "string"
        },
        "v": {},
        "src": {
          "type": "string",
          "enum": [
            "declared",
            "seen",
            "probably"
          ]
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "at": {
          "type": "string",
          "format": "date-time"
        },
        "via": {
          "type": "string"
        }
      }
    },
    "Hours": {
      "type": "object",
      "description": "Weekly windows [opens, closes) in the business's own time zone, and the closures that have not ended (whole days, both included).",
      "required": [
        "timezone",
        "weekly",
        "closures"
      ],
      "properties": {
        "timezone": {
          "type": "string"
        },
        "weekly": {
          "type": "object",
          "propertyNames": {
            "enum": [
              "mon",
              "tue",
              "wed",
              "thu",
              "fri",
              "sat",
              "sun"
            ]
          },
          "additionalProperties": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "type": "array",
              "prefixItems": [
                {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                },
                {
                  "type": "string",
                  "pattern": "^(([01]\\d|2[0-3]):[0-5]\\d|24:00)$",
                  "description": "24:00 for a window that runs to midnight."
                }
              ],
              "minItems": 2,
              "maxItems": 2
            }
          }
        },
        "closures": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      }
    },
    "PayWith": {
      "type": "object",
      "description": "One way to pay a business, with the strongest evidence for it. declared: the business said so itself (its registration, its inbox's manifest, its own structured data, its own UCP or ACP profile, an agent payment protocol its door's document declares in its structure). seen: not its own word: a payment provider's own code, button, payment icon or file on its site, a door's document naming an agent payment protocol in passing, or its shop platform's standard UCP profile (via ucp). A page's words are never evidence. A card brand says a card: card comes with the brand's evidence. ucp_handlers names the UCP protocol, not a way a person pays; pages for people leave it out.",
      "required": [
        "token",
        "label",
        "src",
        "via"
      ],
      "properties": {
        "token": {
          "type": "string",
          "description": "A payment token of GET /v1/attributes."
        },
        "label": {
          "type": "string",
          "description": "Its English name."
        },
        "src": {
          "type": "string",
          "enum": [
            "declared",
            "seen"
          ]
        },
        "via": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]*$",
          "description": "Where the evidence is: registration, manifest, schema_org, ucp, acp, door, file or page today; a later network may add another, so read one you do not know as evidence of its src."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Where the evidence is: the page, file, profile, manifest or door. Absent for a registration."
        }
      }
    },
    "PlaceCategory": {
      "type": "object",
      "required": [
        "id",
        "label",
        "src"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "src": {
          "type": "string",
          "enum": [
            "declared",
            "seen",
            "probably"
          ]
        }
      }
    },
    "Receipts": {
      "type": "object",
      "description": "Promises the business signed and published here.",
      "required": [
        "issued",
        "acknowledged"
      ],
      "properties": {
        "issued": {
          "type": "integer",
          "minimum": 0
        },
        "acknowledged": {
          "type": "integer",
          "minimum": 0,
          "description": "Promises an acknowledgement came with; from rules version 8, the receipts an acknowledgement this network verified backs (any acknowledgement checks out against the key in its own header)."
        },
        "customers": {
          "type": "integer",
          "minimum": 0,
          "description": "On a single business only: the distinct subs its promises name. From rules version 8 absent when its reputation is self_reported."
        },
        "last_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "Reputation": {
      "type": "object",
      "description": "From the last nightly snapshot. The tiers are new, building and trusted: nothing below new. From rules version 8, a record less than a fifth of which is kept outcomes a verified acknowledgement backs rests on the business's own word and is self_reported: it shows its counts (kept, broken, open), tier new, not ranked, no score and no customers. From rules version 9 the score counts what the business cannot make up in its favour, and a record is self_reported until at least 3 distinct customers confirmed kept promises of it.",
      "required": [
        "ranked",
        "tier",
        "kept",
        "broken",
        "verified_share",
        "rules",
        "rules_url"
      ],
      "properties": {
        "ranked": {
          "type": "boolean",
          "description": "Sorts before the daily shuffle (building or better; under rules version 8 with verified_kept_share of 0.2 or more; from rules version 9 with at least 3 distinct customers who confirmed kept promises of it)."
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Absent when self_reported."
        },
        "tier": {
          "type": "string",
          "enum": [
            "new",
            "building",
            "trusted"
          ]
        },
        "kept": {
          "type": "integer",
          "minimum": 0
        },
        "broken": {
          "type": "integer",
          "minimum": 0
        },
        "open": {
          "type": "integer",
          "minimum": 0,
          "description": "From rules version 8: v2 promises still open (issued, not yet closed by an outcome, not unclosed)."
        },
        "customers": {
          "type": "integer",
          "minimum": 0,
          "description": "Distinct customers (§5.3). From rules version 8 absent when self_reported."
        },
        "verified_share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "The share of the record's weight that is verified evidence, reports included."
        },
        "verified_kept_share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "From rules version 8: the share of the record's weight that is kept outcomes a verified acknowledgement backs; ranked and scored from 0.2, as shown (four decimals)."
        },
        "self_reported": {
          "type": "boolean",
          "description": "From rules version 8: the record rests on the business's own word (verified_kept_share below 0.2), so no score and no customers are shown."
        },
        "rules": {
          "type": "integer",
          "minimum": 1
        },
        "rules_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "Service": {
      "type": "object",
      "required": [
        "name",
        "type"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 80
        },
        "type": {
          "type": "string",
          "enum": [
            "booking",
            "order",
            "quote_request"
          ]
        }
      }
    },
    "TrackRecord": {
      "type": "object",
      "description": "A member's track record, from the same nightly snapshot as its reputation and shown under the same rules: the promises it kept and broke, and when. From rules version 8, one that rests on the business's own word (its reputation is self_reported) is self_reported too: its counts, with no score and no count of customers. Only what its state can say is present; an entry that is not a member has none.",
      "required": [
        "state",
        "in_words"
      ],
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "held",
            "none",
            "pending",
            "gathering",
            "shown"
          ],
          "description": "held: a new member's 30 days after it joins, when nothing is counted; none: no receipts yet; pending: receipts the next nightly count reaches; gathering: fewer closed promises, or customers, than threshold; shown: the record."
        },
        "in_words": {
          "type": "string",
          "description": "The record in one or two plain sentences, with how many of its closed promises the customer's side confirmed; the rest are the business's own word."
        },
        "as_of": {
          "type": "string",
          "format": "date-time",
          "description": "The nightly snapshot it is from (00:00 UTC)."
        },
        "held_until": {
          "type": "string",
          "format": "date-time",
          "description": "held: the night its record is counted from."
        },
        "self_reported": {
          "type": "boolean",
          "description": "gathering and shown, from rules version 8: the record rests on the business's own word (under version 8 less than a fifth of it is kept outcomes a verified acknowledgement backs; from version 9 fewer than 3 distinct customers confirmed it; as its reputation's self_reported), so it has no customers, and its threshold none."
        },
        "closed": {
          "type": "integer",
          "minimum": 0,
          "description": "gathering and shown: kept plus broken."
        },
        "customers": {
          "type": "integer",
          "minimum": 0,
          "description": "gathering and shown, unless self_reported: the distinct customers the closed promises came from, as its receipts name them (the customer's mailbox when known, else, before rules version 8, the receipt's sub; from rules version 8 a sub that names no person is never a customer, and every receipt at a business that names nobody is one anonymous customer). Not reputation.customers, which counts only customers this network can tell apart."
        },
        "kept": {
          "type": "integer",
          "minimum": 0,
          "description": "shown."
        },
        "broken": {
          "type": "integer",
          "minimum": 0,
          "description": "shown: closed as not kept by the business or by a customer's report that stands, left open 9 days past due, or a refund paid late."
        },
        "open": {
          "type": "integer",
          "minimum": 0,
          "description": "shown, from rules version 8: its v2 promises still open (reputation.open)."
        },
        "unclosed": {
          "type": "integer",
          "minimum": 0,
          "description": "shown, of broken: left open 9 days past due (promise.unclosed)."
        },
        "refunds_late": {
          "type": "integer",
          "minimum": 0,
          "description": "shown, of broken: refunds paid late (refund.late)."
        },
        "from": {
          "type": "string",
          "format": "date-time",
          "description": "shown: the earliest day of the evidence counted, at 00:00 UTC (a day, never the moment of a promise)."
        },
        "to": {
          "type": "string",
          "format": "date-time",
          "description": "shown: the latest day of the evidence counted, at 00:00 UTC (a day, never the moment of a promise)."
        },
        "confirmed": {
          "type": "integer",
          "minimum": 0,
          "description": "shown: how many of the closed are kept outcomes a verified acknowledgement backs, confirmed by the customer's side (a customer's report is not a confirmation); the rest are the business's own word."
        },
        "confirmable": {
          "type": "boolean",
          "description": "shown: whether this network can verify any acknowledgement yet (a recognised platform's agent key, or an established person's)."
        },
        "threshold": {
          "type": "object",
          "description": "What a record shows from: closed promises, from customers distinct customers; a self_reported record is not asked for customers, and has none here.",
          "required": [
            "closed"
          ],
          "properties": {
            "closed": {
              "type": "integer",
              "minimum": 1
            },
            "customers": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "rules_url": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}