PlaceTwin

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/journeyed-org/json-schema/journeyed-org-place-twin-schema.json",
  "title": "PlaceTwin",
  "description": "JSON twin of a place page (<path>.json). photos is present when the build ships photos; videos when the place has YouTube videos; questionPages when the hotel has question pages.",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/journeyed-org-openapi.json#/components/schemas/PlaceTwin",
  "type": "object",
  "required": [
    "schemaVersion",
    "url",
    "jsonUrl",
    "markdownUrl",
    "asOf",
    "publisher",
    "type",
    "placeId",
    "name",
    "market",
    "contact",
    "coordinates",
    "scoreName",
    "score",
    "scoreHistory",
    "facts",
    "factSheet",
    "mentionCounts",
    "anchors",
    "routing",
    "formerNames",
    "nameSource",
    "questions",
    "sources",
    "claimUrl",
    "qa",
    "brandStandard"
  ],
  "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": "place"
    },
    "placeId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "market": {
      "type": "string"
    },
    "contact": {
      "type": "object",
      "description": "Contact details from the open place record, plus ownerGuide when the owner publishes a guide site of their own (null when none is on record).",
      "required": [
        "phone",
        "website",
        "address",
        "source",
        "ownerGuide"
      ],
      "additionalProperties": false,
      "properties": {
        "phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "website": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "address": {
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "oneOf": [
            {
              "$ref": "#/$defs/Source"
            },
            {
              "type": "null"
            }
          ]
        },
        "ownerGuide": {
          "oneOf": [
            {
              "type": "object",
              "description": "A guide site the hotel owner publishes, apart from the brand site in website; the date a person checked it in a browser.",
              "required": [
                "url",
                "checkedOn"
              ],
              "additionalProperties": false,
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "checkedOn": {
                  "type": "string",
                  "format": "date"
                }
              }
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "coordinates": {
      "$ref": "#/$defs/Coordinates"
    },
    "scoreName": {
      "type": "string"
    },
    "score": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "value",
            "formulaVersion",
            "asOf"
          ],
          "additionalProperties": false,
          "properties": {
            "value": {
              "type": "number"
            },
            "formulaVersion": {
              "type": "string"
            },
            "asOf": {
              "type": "string",
              "format": "date"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "scoreHistory": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "asOf",
          "score"
        ],
        "additionalProperties": false,
        "properties": {
          "asOf": {
            "type": "string",
            "format": "date"
          },
          "score": {
            "type": "number"
          }
        }
      }
    },
    "facts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Fact"
      }
    },
    "factSheet": {
      "$ref": "#/$defs/FactSheet"
    },
    "mentionCounts": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Counted guest mentions from licensed sources. Never text, never a star rating.",
        "required": [
          "aspect",
          "positive",
          "neutral",
          "negative"
        ],
        "additionalProperties": false,
        "properties": {
          "aspect": {
            "type": "string"
          },
          "positive": {
            "type": "integer"
          },
          "neutral": {
            "type": "integer"
          },
          "negative": {
            "type": "integer"
          }
        }
      }
    },
    "anchors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "url",
          "distanceMi",
          "routed"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "distanceMi": {
            "type": "number"
          },
          "routed": {
            "oneOf": [
              {
                "$ref": "#/$defs/RoutedDistance"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    },
    "routing": {
      "oneOf": [
        {
          "$ref": "#/$defs/Routing"
        },
        {
          "type": "null"
        }
      ]
    },
    "formerNames": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "nameSource": {
      "oneOf": [
        {
          "$ref": "#/$defs/Source"
        },
        {
          "type": "null"
        }
      ]
    },
    "questions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "question",
          "url",
          "jsonUrl",
          "rank"
        ],
        "additionalProperties": false,
        "properties": {
          "question": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          },
          "rank": {
            "type": "integer"
          }
        }
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Source"
      }
    },
    "claimUrl": {
      "type": "string",
      "format": "uri"
    },
    "qa": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A question about this hotel and its answer, restating one sourced fact (basis \"fact:<key>\") or one anchor distance (basis \"distance:<anchor url>\") on the page, with its source and checked date. Generated deterministically from the facts, never written by a model.",
        "required": [
          "id",
          "question",
          "answer",
          "source",
          "basis"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          },
          "source": {
            "$ref": "#/$defs/Source"
          },
          "basis": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "brandStandard": {
      "oneOf": [
        {
          "type": "object",
          "description": "What the hotel brand says all its hotels offer. Not a fact about this property.",
          "required": [
            "brand",
            "items"
          ],
          "additionalProperties": false,
          "properties": {
            "brand": {
              "type": "string"
            },
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "key",
                  "text",
                  "source"
                ],
                "additionalProperties": false,
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  },
                  "source": {
                    "$ref": "#/$defs/Source"
                  }
                }
              }
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "questionPages": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A page that answers one question about this hotel from its sourced facts (HotelQuestionTwin).",
        "required": [
          "id",
          "question",
          "url",
          "jsonUrl"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "recognition": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Fact"
      }
    },
    "backing": {
      "$ref": "#/$defs/Backing"
    },
    "backedBy": {
      "type": "string"
    },
    "scoreBand": {
      "type": "string"
    },
    "bestOf": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A best-of list this hotel is ranked on.",
        "required": [
          "title",
          "url",
          "jsonUrl",
          "rank"
        ],
        "additionalProperties": false,
        "properties": {
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "jsonUrl": {
            "type": "string",
            "format": "uri"
          },
          "rank": {
            "type": "integer"
          }
        }
      }
    },
    "photos": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Photo"
      }
    },
    "videos": {
      "type": "object",
      "description": "J15: YouTube videos that name this hotel (title and channel as YouTube returns them, not verified). YouTube API data, refreshed or dropped within 30 days.",
      "required": [
        "source",
        "note",
        "terms",
        "videos"
      ],
      "additionalProperties": false,
      "properties": {
        "source": {
          "const": "YouTube Data API v3"
        },
        "note": {
          "type": "string"
        },
        "terms": {
          "type": "string",
          "format": "uri"
        },
        "videos": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "videoId",
              "title",
              "channel",
              "channelUrl",
              "url",
              "embedUrl",
              "thumbnailUrl",
              "kind",
              "isShort",
              "durationSec",
              "uploadDate",
              "fetchedOn"
            ],
            "additionalProperties": false,
            "properties": {
              "videoId": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "channel": {
                "type": "string"
              },
              "channelUrl": {
                "type": "string",
                "format": "uri"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "embedUrl": {
                "type": "string",
                "format": "uri"
              },
              "thumbnailUrl": {
                "type": "string",
                "format": "uri"
              },
              "kind": {
                "enum": [
                  "room-tour",
                  "walk-through",
                  "review",
                  "other"
                ]
              },
              "isShort": {
                "type": "boolean"
              },
              "durationSec": {
                "type": "integer"
              },
              "uploadDate": {
                "type": "string",
                "format": "date"
              },
              "fetchedOn": {
                "type": "string",
                "format": "date"
              }
            }
          }
        }
      }
    }
  },
  "$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"
        }
      }
    },
    "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"
        }
      }
    },
    "FactSheet": {
      "type": "object",
      "description": "The complete fact sheet of one hotel: every verified fact, and every registered fact key that is not verified yet (unknown). Unknown is not no: never fill it in. keysUrl is the market fact dictionary.",
      "required": [
        "about",
        "keysUrl",
        "known",
        "unknownCount",
        "facts",
        "unknown",
        "brandStandardKeys",
        "routed"
      ],
      "additionalProperties": false,
      "properties": {
        "about": {
          "type": "string"
        },
        "keysUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "known": {
          "type": "integer"
        },
        "unknownCount": {
          "type": "integer"
        },
        "facts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FactSheetRow"
          }
        },
        "unknown": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "brandStandardKeys": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "routed": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FactSheetRoutedRow"
          }
        }
      }
    },
    "FactSheetRoutedRow": {
      "type": "object",
      "description": "One computed distance of a fact sheet: straight-line miles to a landmark and the walking and driving distance along OpenStreetMap ways, with method, source and the date computed (checkedOn).",
      "required": [
        "anchor",
        "url",
        "straightMi",
        "walkMi",
        "walkMin",
        "driveMi",
        "method",
        "sourceLabel",
        "sourceUrl",
        "licenseBasis",
        "checkedOn"
      ],
      "additionalProperties": false,
      "properties": {
        "anchor": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "straightMi": {
          "type": "number"
        },
        "walkMi": {
          "type": [
            "number",
            "null"
          ]
        },
        "walkMin": {
          "type": [
            "integer",
            "null"
          ]
        },
        "driveMi": {
          "type": [
            "number",
            "null"
          ]
        },
        "method": {
          "type": "string"
        },
        "sourceLabel": {
          "type": "string"
        },
        "sourceUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "licenseBasis": {
          "type": "string"
        },
        "checkedOn": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "FactSheetRow": {
      "type": "object",
      "description": "One verified fact of a fact sheet: what the key means (label, group), its stored value and unit, the page wording, its source (exactly one of sourceUrl and dataset), the date it was checked and its data tier (1 open data, 2 the hotel website, 3 licensed, 4 first-party, 5 claimed by the business).",
      "required": [
        "key",
        "label",
        "group",
        "value",
        "unit",
        "text",
        "sourceUrl",
        "dataset",
        "checkedOn",
        "tier",
        "licenseBasis"
      ],
      "additionalProperties": false,
      "properties": {
        "key": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "group": {
          "type": "string"
        },
        "value": {
          "type": [
            "string",
            "null"
          ]
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        },
        "text": {
          "type": "string"
        },
        "sourceUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        },
        "dataset": {
          "type": [
            "string",
            "null"
          ]
        },
        "checkedOn": {
          "type": "string",
          "format": "date"
        },
        "tier": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5
        },
        "licenseBasis": {
          "type": "string"
        }
      }
    },
    "Photo": {
      "type": "object",
      "description": "A licensed Wikimedia Commons photo the page shows. kind \"place\" is the hotel itself; \"area\" is a nearby landmark or city photo standing in for it (label says so); never treat an area photo as the hotel.",
      "required": [
        "url",
        "width",
        "height",
        "alt",
        "kind",
        "label",
        "credit"
      ],
      "additionalProperties": false,
      "properties": {
        "url": {
          "type": "string",
          "format": "uri"
        },
        "width": {
          "type": "integer"
        },
        "height": {
          "type": "integer"
        },
        "alt": {
          "type": "string"
        },
        "kind": {
          "enum": [
            "place",
            "area",
            "landmark"
          ]
        },
        "label": {
          "type": [
            "string",
            "null"
          ]
        },
        "credit": {
          "type": "object",
          "required": [
            "author",
            "license",
            "licenseUrl",
            "commonsPage",
            "fileTitle"
          ],
          "additionalProperties": false,
          "properties": {
            "author": {
              "type": "string"
            },
            "license": {
              "type": "string"
            },
            "licenseUrl": {
              "type": "string",
              "format": "uri"
            },
            "commonsPage": {
              "type": "string",
              "format": "uri"
            },
            "fileTitle": {
              "type": "string"
            }
          }
        }
      }
    },
    "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"
        }
      }
    }
  }
}