BestOfTwin

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/journeyed-org/json-schema/journeyed-org-best-of-twin-schema.json",
  "title": "BestOfTwin",
  "description": "JSON twin of a best-of page (/<category>/<market>/best-...json): hotels that can be ranked, ordered by a published formula of recognized awards, hotel class, verified facts, reader votes and distance. Never a review score. sponsored (present only when the page shows one) holds labelled paid cards, never part of ranked.",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/journeyed-org-openapi.json#/components/schemas/BestOfTwin",
  "type": "object",
  "required": [
    "schemaVersion",
    "url",
    "jsonUrl",
    "markdownUrl",
    "asOf",
    "publisher",
    "type",
    "title",
    "kind",
    "market",
    "answer",
    "answerSentences",
    "countLine",
    "anchor",
    "need",
    "considered",
    "eligible",
    "eligibility",
    "formula",
    "votes",
    "ranked",
    "rankedTotal",
    "sections",
    "routing",
    "whyTrust",
    "qa",
    "related",
    "alsoAskedAs",
    "sources"
  ],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": {
      "type": "integer",
      "const": 1
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "jsonUrl": {
      "type": "string",
      "format": "uri"
    },
    "markdownUrl": {
      "type": "string",
      "format": "uri"
    },
    "asOf": {
      "type": "string",
      "format": "date"
    },
    "publisher": {
      "$ref": "#/$defs/Publisher"
    },
    "type": {
      "const": "best-of"
    },
    "title": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "anchor",
        "need"
      ]
    },
    "market": {
      "type": "string"
    },
    "answer": {
      "type": "string"
    },
    "answerSentences": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 2
    },
    "countLine": {
      "type": "string"
    },
    "anchor": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "name",
            "url",
            "lat",
            "lon",
            "radiusMi",
            "kind"
          ],
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            },
            "lat": {
              "type": "number"
            },
            "lon": {
              "type": "number"
            },
            "radiusMi": {
              "type": "number"
            },
            "kind": {
              "type": "string"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "need": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "id",
            "label",
            "definition"
          ],
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "definition": {
              "type": "string"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "considered": {
      "type": "integer"
    },
    "eligible": {
      "type": "integer"
    },
    "eligibility": {
      "type": "string"
    },
    "formula": {
      "type": "object",
      "description": "What best means on this page: points per part (they sum to 100), in two sentences and one line per part.",
      "required": [
        "version",
        "weights",
        "sentences",
        "lines",
        "url"
      ],
      "additionalProperties": false,
      "properties": {
        "version": {
          "type": "string"
        },
        "weights": {
          "$ref": "#/$defs/BestOfParts"
        },
        "sentences": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "lines": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "votes": {
      "type": "object",
      "description": "Reader opinion enters only as Yes or No votes on details. Never reviews.",
      "required": [
        "counted",
        "note"
      ],
      "additionalProperties": false,
      "properties": {
        "counted": {
          "type": "integer"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "ranked": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A ranked hotel. points is the best-of total (0 to 100), not the place score; why holds the sourced facts behind its place, awards first (value is the level, unit the list year).",
        "required": [
          "rank",
          "placeId",
          "name",
          "url",
          "jsonUrl",
          "points",
          "parts",
          "eligibleBy",
          "score",
          "scoreBand",
          "distanceMi",
          "routed",
          "address",
          "coordinates",
          "why",
          "backing",
          "backedBy",
          "questionPages"
        ],
        "additionalProperties": false,
        "properties": {
          "rank": {
            "type": "integer"
          },
          "placeId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          },
          "points": {
            "type": "number"
          },
          "parts": {
            "$ref": "#/$defs/BestOfParts"
          },
          "eligibleBy": {
            "enum": [
              "profile",
              "award",
              "both"
            ]
          },
          "score": {
            "type": "number"
          },
          "scoreBand": {
            "type": "string"
          },
          "distanceMi": {
            "type": [
              "number",
              "null"
            ]
          },
          "routed": {
            "oneOf": [
              {
                "$ref": "#/$defs/RoutedDistance"
              },
              {
                "type": "null"
              }
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "coordinates": {
            "$ref": "#/$defs/Coordinates"
          },
          "why": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Fact"
            }
          },
          "backing": {
            "$ref": "#/$defs/Backing"
          },
          "backedBy": {
            "type": "string"
          },
          "questionPages": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/Link"
            }
          }
        }
      }
    },
    "rankedTotal": {
      "type": "integer"
    },
    "sections": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "heading",
          "note",
          "rows"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "heading": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "placeId",
                "name",
                "url",
                "distanceMi",
                "routed",
                "score",
                "rank",
                "fact"
              ],
              "additionalProperties": false,
              "properties": {
                "placeId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "distanceMi": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "routed": {
                  "oneOf": [
                    {
                      "$ref": "#/$defs/RoutedDistance"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "score": {
                  "type": "number"
                },
                "rank": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "fact": {
                  "$ref": "#/$defs/Fact"
                }
              }
            }
          }
        }
      }
    },
    "routing": {
      "oneOf": [
        {
          "$ref": "#/$defs/Routing"
        },
        {
          "type": "null"
        }
      ]
    },
    "whyTrust": {
      "type": "object",
      "required": [
        "bullets",
        "url"
      ],
      "additionalProperties": false,
      "properties": {
        "bullets": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "qa": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "question",
          "answer"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        }
      }
    },
    "related": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Link"
      }
    },
    "alsoAskedAs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Source"
      }
    },
    "walking": {
      "$ref": "#/$defs/Link"
    },
    "table": {
      "$ref": "#/$defs/CompareTable"
    },
    "sponsored": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ListSponsoredPlace"
      }
    }
  },
  "$defs": {
    "Backing": {
      "type": "object",
      "description": "What is on record behind a hotel score, in counts: facts read from the hotel own website (and the newest date they were checked), contact details from the open place record, recognized awards, counted reader votes, and how many of the standard facts the score counts are verified.",
      "required": [
        "ownSiteFacts",
        "ownSiteCheckedOn",
        "recordFacts",
        "awards",
        "votes",
        "standardFacts",
        "standardTotal"
      ],
      "additionalProperties": false,
      "properties": {
        "ownSiteFacts": {
          "type": "integer"
        },
        "ownSiteCheckedOn": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "recordFacts": {
          "type": "integer"
        },
        "awards": {
          "type": "integer"
        },
        "votes": {
          "type": "integer"
        },
        "standardFacts": {
          "type": "integer"
        },
        "standardTotal": {
          "type": "integer"
        }
      }
    },
    "BestOfParts": {
      "type": "object",
      "description": "The five parts of a best-of order, in points.",
      "required": [
        "awards",
        "class",
        "facts",
        "votes",
        "distance"
      ],
      "additionalProperties": false,
      "properties": {
        "awards": {
          "type": "number"
        },
        "class": {
          "type": "number"
        },
        "facts": {
          "type": "number"
        },
        "votes": {
          "type": "number"
        },
        "distance": {
          "type": "number"
        }
      }
    },
    "CompareTable": {
      "type": "object",
      "description": "The comparison table a list page shows under its answer: one row per listed hotel, in the list order; cells are in column order. distance is straight-line miles; walk, walkMin, walkMi and drive follow OpenStreetMap ways (walk times are estimates). of names the guide section whose hotels the rows are. routing is present when the twin has no routing of its own.",
      "required": [
        "heading",
        "caption",
        "anchorUrl",
        "columns",
        "rows"
      ],
      "additionalProperties": false,
      "properties": {
        "heading": {
          "type": "string"
        },
        "caption": {
          "type": "string"
        },
        "anchorUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "of": {
          "type": "string"
        },
        "columns": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "label"
            ],
            "additionalProperties": false,
            "properties": {
              "id": {
                "enum": [
                  "distance",
                  "walk",
                  "walkMin",
                  "walkMi",
                  "drive",
                  "parking",
                  "answer",
                  "checkin",
                  "pets",
                  "recognition",
                  "verified",
                  "profile"
                ]
              },
              "label": {
                "type": "string"
              }
            }
          }
        },
        "rows": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "rank",
              "placeId",
              "name",
              "url",
              "jsonUrl",
              "cells"
            ],
            "additionalProperties": false,
            "properties": {
              "rank": {
                "type": "integer"
              },
              "placeId": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "jsonUrl": {
                "type": "string",
                "format": "uri"
              },
              "cells": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One cell. facts are the sourced facts the text was worded from; a cell without them is computed (a distance, a walk, a count, a band). \"not stated\" means the value is not on record, never that it is no.",
                  "required": [
                    "text"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "text": {
                      "type": "string"
                    },
                    "facts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/$defs/Fact"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "routing": {
          "$ref": "#/$defs/Routing"
        }
      }
    },
    "Coordinates": {
      "type": "object",
      "required": [
        "lat",
        "lon"
      ],
      "additionalProperties": false,
      "properties": {
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        }
      }
    },
    "Fact": {
      "type": "object",
      "description": "One sourced fact. Exactly one of sourceUrl and dataset is set. text is the wording the page shows; value is the stored canonical value.",
      "required": [
        "key",
        "text",
        "value",
        "unit",
        "sourceUrl",
        "dataset",
        "sourceLabel",
        "licenseBasis",
        "checkedOn"
      ],
      "additionalProperties": false,
      "properties": {
        "key": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "value": {
          "type": [
            "string",
            "null"
          ]
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "sourceUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "dataset": {
          "type": [
            "string",
            "null"
          ]
        },
        "sourceLabel": {
          "type": "string"
        },
        "licenseBasis": {
          "type": "string"
        },
        "checkedOn": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "Link": {
      "type": "object",
      "required": [
        "text",
        "url",
        "jsonUrl"
      ],
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "jsonUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "ListSponsoredPlace": {
      "type": "object",
      "description": "A labelled paid card above a best-of, walking or landmark list. Never inside ranked[] and never a change to any rank or score: organicRank is the hotel position in ranked[] when the list shows it, else null; score is its unchanged place score.",
      "required": [
        "label",
        "placeId",
        "name",
        "url",
        "organicRank",
        "score",
        "distanceMi"
      ],
      "additionalProperties": false,
      "properties": {
        "label": {
          "type": "string"
        },
        "placeId": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "organicRank": {
          "type": [
            "integer",
            "null"
          ]
        },
        "score": {
          "type": "number"
        },
        "distanceMi": {
          "type": "number"
        },
        "rankedOn": {
          "type": "object",
          "description": "Event pages: the hotel position on the full best-of list the page links to, as that list publishes it, when the page shows only its first rows.",
          "required": [
            "rank",
            "total",
            "title",
            "url"
          ],
          "additionalProperties": false,
          "properties": {
            "rank": {
              "type": "integer"
            },
            "total": {
              "type": "integer"
            },
            "title": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      }
    },
    "Publisher": {
      "type": "object",
      "description": "The publisher. disclosure and parent are present only when the publisher has a parent company.",
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "disclosure": {
          "type": "string"
        },
        "parent": {
          "type": "string"
        }
      }
    },
    "RoutedDistance": {
      "type": "object",
      "description": "A distance along OpenStreetMap streets and paths between a hotel and a landmark, beside the straight-line distanceMi and never shorter than it. walkMin is the routing engine's estimate (say \"about\"), never a measured time. driveMi is a distance only: no drive time is published. A null part is not on record.",
      "required": [
        "walkMi",
        "walkMin",
        "driveMi"
      ],
      "additionalProperties": false,
      "properties": {
        "walkMi": {
          "type": [
            "number",
            "null"
          ]
        },
        "walkMin": {
          "type": [
            "integer",
            "null"
          ]
        },
        "driveMi": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "Routing": {
      "type": "object",
      "description": "What sources every routed figure of a twin: the credit (OpenStreetMap contributors, routed with the named engine), the date of the map data, the date computed and the method of each figure.",
      "required": [
        "source",
        "engine",
        "mapDataOn",
        "computedOn",
        "walkMethod",
        "driveMethod",
        "note"
      ],
      "additionalProperties": false,
      "properties": {
        "source": {
          "$ref": "#/$defs/Source"
        },
        "engine": {
          "type": "string"
        },
        "mapDataOn": {
          "type": "string",
          "format": "date"
        },
        "computedOn": {
          "type": "string",
          "format": "date"
        },
        "walkMethod": {
          "type": "string"
        },
        "driveMethod": {
          "type": "string"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "Source": {
      "type": "object",
      "required": [
        "label",
        "url",
        "dataset",
        "licenseBasis",
        "checkedOn"
      ],
      "additionalProperties": false,
      "properties": {
        "label": {
          "type": "string"
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "dataset": {
          "type": [
            "string",
            "null"
          ]
        },
        "licenseBasis": {
          "type": "string"
        },
        "checkedOn": {
          "type": "string",
          "format": "date"
        }
      }
    }
  }
}