{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-preview.wikiup.app/travel-listings.schema.json",
  "title": "Wikiup affiliate listing API v2",
  "description": "Choose the named response definition for the endpoint. Search-only keys retain the legacy contract.",
  "oneOf": [
    {
      "$ref": "#/$defs/SearchResponse"
    },
    {
      "$ref": "#/$defs/ContentResponse"
    },
    {
      "$ref": "#/$defs/AvailabilityResponse"
    },
    {
      "$ref": "#/$defs/ErrorResponse"
    },
    {
      "$ref": "#/$defs/CatalogResponse"
    },
    {
      "$ref": "#/$defs/BatchAvailabilityResponse"
    },
    {
      "$ref": "#/$defs/RoomContentResponse"
    },
    {
      "$ref": "#/$defs/RoomCollectionResponse"
    }
  ],
  "$defs": {
    "ImageVariant": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Public versioned photo URL. Use the returned URL unchanged; it contains no API key."
        },
        "width": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image width in pixels; do not assume the nominal thumbnail width."
        },
        "height": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image height in pixels; preserve its aspect ratio."
        },
        "format": {
          "enum": [
            "avif",
            "webp",
            "jpeg",
            "png"
          ],
          "description": "Encoded thumbnail image format."
        }
      },
      "required": [
        "url",
        "width",
        "height",
        "format"
      ],
      "additionalProperties": false,
      "description": "Response structure: ImageVariant."
    },
    "PublicImage": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Public versioned photo URL. Use the returned URL unchanged; it contains no API key."
        },
        "alt": {
          "type": "string",
          "description": "Image alternative text for accessible presentation."
        },
        "width": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image width in pixels; do not assume the nominal thumbnail width."
        },
        "height": {
          "type": "integer",
          "minimum": 1,
          "description": "Actual image height in pixels; preserve its aspect ratio."
        },
        "variants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ImageVariant"
          },
          "description": "Prepared image sizes; choose by displayed width and pixel density. Original image remains available at url."
        },
        "group": {
          "anyOf": [
            {
              "$ref": "#/$defs/PhotoGroup"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional owner-defined photo group; null means ungrouped."
        }
      },
      "required": [
        "id",
        "url",
        "alt",
        "width",
        "height",
        "variants",
        "group"
      ],
      "additionalProperties": false,
      "description": "Response structure: PublicImage."
    },
    "Listing": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "type": {
          "enum": [
            "hotel",
            "vacation_rental"
          ],
          "description": "Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit."
        },
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property identifier."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "propertyName": {
          "type": "string",
          "description": "Public property listing title, falling back to property name."
        },
        "location": {
          "type": "string",
          "description": "Saved city/state display label, not a street address or map position."
        },
        "image": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cover photo URL, or null if no public photo exists."
        },
        "imageVariants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ImageVariant"
          },
          "description": "Prepared responsive sizes for the cover image."
        },
        "maxGuests": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards."
        },
        "availableRoomCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of qualifying rooms across the hotel for these dates and party."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. All amounts are in major currency units."
        },
        "nightlyRate": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Average accommodation rate per night for this requested stay, excluding taxes and fees."
        },
        "staySubtotal": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees."
        },
        "priceBasis": {
          "const": "accommodation_subtotal",
          "description": "Prices are accommodation subtotals, not final checkout totals."
        },
        "taxes": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "fees": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "finalTotal": {
          "type": "null",
          "description": "Determined at checkout. Null must not be displayed as zero."
        },
        "bookingUrl": {
          "type": "string",
          "format": "uri",
          "description": "Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it."
        },
        "priceLabel": {
          "enum": [
            "From",
            "Stay"
          ],
          "description": "From for the lowest qualifying hotel option; Stay for a rental."
        },
        "mapLocation": {
          "$ref": "#/$defs/PublicMapLocation",
          "description": "Exact approved public coordinate pair, or null. Never use town-center guesses."
        },
        "timeZone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Validated property IANA time zone. Use for local timestamps; null means unknown."
        }
      },
      "required": [
        "id",
        "type",
        "propertyId",
        "name",
        "propertyName",
        "location",
        "image",
        "imageVariants",
        "currency",
        "nightlyRate",
        "staySubtotal",
        "priceBasis",
        "taxes",
        "fees",
        "finalTotal",
        "bookingUrl",
        "priceLabel",
        "mapLocation",
        "timeZone"
      ],
      "additionalProperties": false,
      "description": "Response structure: Listing."
    },
    "ListingContent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "type": {
          "enum": [
            "hotel",
            "vacation_rental"
          ],
          "description": "Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit."
        },
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property identifier."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "propertyName": {
          "type": "string",
          "description": "Public property listing title, falling back to property name."
        },
        "location": {
          "type": "string",
          "description": "Saved city/state display label, not a street address or map position."
        },
        "destination": {
          "type": [
            "string",
            "null"
          ],
          "description": "Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Full saved description for the exact listing; may contain HTML. Null when unknown. The catalog uses a bounded plain-text excerpt instead."
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "One value in the ordered collection."
          },
          "description": "Public amenity names for this exact listing. Empty means none supplied; do not invent amenities."
        },
        "maxGuests": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards."
        },
        "coverImage": {
          "anyOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ],
          "description": "Public cover image metadata, or null when absent."
        },
        "gallery": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PublicImage"
          },
          "description": "Ordered public listing photos, including thumbnails and group labels."
        },
        "galleryGroups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GalleryGroup"
          },
          "description": "Ordered photo groups referencing gallery image IDs."
        },
        "mapLocation": {
          "$ref": "#/$defs/PublicMapLocation",
          "description": "Exact approved public coordinate pair, or null. Never use town-center guesses."
        },
        "timeZone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Validated property IANA time zone. Use for local timestamps; null means unknown."
        },
        "stayType": {
          "enum": [
            "hotel",
            "inn",
            "bed_and_breakfast",
            "resort",
            "vacation_rental",
            null
          ],
          "description": "Owner-supplied subtype compatible with the existing broad type; null when unknown or inconsistent. Does not select the booking flow."
        },
        "tagLine": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "Explicit owner-provided hotel facts or beds/baths from the exact rental unit or room-type content. Not live available inventory. Unknown is null. Limited to 100 Unicode characters including an ellipsis when shortened."
        },
        "ratings": {
          "$ref": "#/$defs/AffiliateRating",
          "description": "Present only with fetch=ratings; omitted otherwise. Unset values are null."
        },
        "address": {
          "oneOf": [
            {
              "$ref": "#/$defs/ListingAddress"
            },
            {
              "type": "null"
            }
          ],
          "description": "Saved property address, not owner-account address. Null when all address fields are empty. Detail only."
        },
        "contact": {
          "$ref": "#/$defs/ListingContact",
          "description": "Property business contact details. No account records or credentials are included."
        }
      },
      "required": [
        "id",
        "type",
        "propertyId",
        "name",
        "propertyName",
        "location",
        "destination",
        "description",
        "amenities",
        "coverImage",
        "gallery",
        "galleryGroups",
        "mapLocation",
        "timeZone",
        "stayType",
        "tagLine",
        "address",
        "contact"
      ],
      "additionalProperties": false,
      "description": "Response structure: ListingContent."
    },
    "Option": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "roomId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Physical room identifier; null for a pooled room-type option."
        },
        "roomTypeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Room-type identifier for pooled inventory; null for a named room."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "coverImage": {
          "anyOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ],
          "description": "Public cover image metadata, or null when absent."
        },
        "photos": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri",
            "description": "One value in the ordered collection."
          },
          "description": "Public photo URLs for this inventory; may be empty."
        },
        "capacity": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this exact bookable option."
        },
        "availableCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of physical units assignable throughout the entire requested stay; not a hold."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. All amounts are in major currency units."
        },
        "nightlyRate": {
          "type": "number",
          "minimum": 0,
          "description": "Average accommodation rate per night for this requested stay, excluding taxes and fees."
        },
        "staySubtotal": {
          "type": "number",
          "minimum": 0,
          "description": "Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees."
        },
        "priceBasis": {
          "const": "accommodation_subtotal",
          "description": "Prices are accommodation subtotals, not final checkout totals."
        },
        "taxes": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "fees": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "finalTotal": {
          "type": "null",
          "description": "Determined at checkout. Null must not be displayed as zero."
        },
        "bookingUrl": {
          "type": "string",
          "format": "uri",
          "description": "Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it."
        },
        "image": {
          "type": [
            "string",
            "null"
          ],
          "description": "Cover photo URL, or null if no public photo exists."
        },
        "imageVariants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ImageVariant"
          },
          "description": "Prepared responsive sizes for the cover image."
        },
        "maxGuests": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards."
        }
      },
      "required": [
        "id",
        "roomId",
        "roomTypeId",
        "name",
        "photos",
        "capacity",
        "availableCount",
        "currency",
        "nightlyRate",
        "staySubtotal",
        "priceBasis",
        "taxes",
        "fees",
        "finalTotal",
        "bookingUrl",
        "image",
        "imageVariants",
        "maxGuests"
      ],
      "additionalProperties": false,
      "description": "Response structure: Option."
    },
    "LegacyRoom": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "roomId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Physical room identifier; null for a pooled room-type option."
        },
        "roomTypeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Room-type identifier for pooled inventory; null for a named room."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "coverImage": {
          "anyOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ],
          "description": "Public cover image metadata, or null when absent."
        },
        "photos": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri",
            "description": "One value in the ordered collection."
          },
          "description": "Public photo URLs for this inventory; may be empty."
        },
        "capacity": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this exact bookable option."
        },
        "availableCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of physical units assignable throughout the entire requested stay; not a hold."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. All amounts are in major currency units."
        },
        "nightlyRate": {
          "type": "number",
          "minimum": 0,
          "description": "Average accommodation rate per night for this requested stay, excluding taxes and fees."
        },
        "staySubtotal": {
          "type": "number",
          "minimum": 0,
          "description": "Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees."
        },
        "priceBasis": {
          "const": "accommodation_subtotal",
          "description": "Prices are accommodation subtotals, not final checkout totals."
        },
        "taxes": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "fees": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "finalTotal": {
          "type": "null",
          "description": "Determined at checkout. Null must not be displayed as zero."
        },
        "bookingUrl": {
          "type": "string",
          "format": "uri",
          "description": "Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it."
        }
      },
      "required": [
        "id",
        "roomId",
        "roomTypeId",
        "name",
        "photos",
        "capacity",
        "availableCount",
        "currency",
        "nightlyRate",
        "staySubtotal",
        "priceBasis",
        "taxes",
        "fees",
        "finalTotal",
        "bookingUrl"
      ],
      "additionalProperties": false,
      "description": "Response structure: LegacyRoom."
    },
    "Query": {
      "type": "object",
      "properties": {
        "destination": {
          "type": "string",
          "description": "Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography."
        },
        "checkIn": {
          "type": "string",
          "format": "date",
          "description": "Arrival calendar date in the property timezone, YYYY-MM-DD."
        },
        "checkOut": {
          "type": "string",
          "format": "date",
          "description": "Departure calendar date, YYYY-MM-DD; checkout is not an occupied night."
        },
        "adults": {
          "type": "integer",
          "minimum": 0,
          "description": "Adult guest count; defaults to 2 in requests."
        },
        "children": {
          "type": "integer",
          "minimum": 0,
          "description": "Child guest count; defaults to 0 in requests."
        },
        "pets": {
          "type": "integer",
          "minimum": 0,
          "description": "Pet count; defaults to 0 in requests."
        },
        "page": {
          "type": "integer",
          "minimum": 0,
          "description": "One-based property page number."
        },
        "pageSize": {
          "type": "integer",
          "minimum": 0,
          "description": "Property count per page, not listing-card count; rental properties can produce multiple cards."
        }
      },
      "required": [
        "destination",
        "checkIn",
        "checkOut",
        "adults",
        "children",
        "pets",
        "page",
        "pageSize"
      ],
      "additionalProperties": false,
      "description": "Response structure: Query."
    },
    "Meta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 0,
          "description": "One-based property page number."
        },
        "pageSize": {
          "type": "integer",
          "minimum": 0,
          "description": "Property count per page, not listing-card count; rental properties can produce multiple cards."
        },
        "nextPage": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "description": "Next property page number, or null at the end."
        },
        "matchedProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Eligible properties matching geography before this page is evaluated."
        },
        "searchedProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Properties whose availability check succeeded on this page."
        },
        "soldOutProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Checked properties with no options matching dates, party and booking rules; not necessarily occupied."
        },
        "withdrawnProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Properties removed because eligibility changed while processing."
        },
        "partial": {
          "type": "boolean",
          "description": "True when provider failures make the current response incomplete."
        },
        "pageComplete": {
          "type": "boolean",
          "description": "True when this page has no provider failures; does not imply all pages were fetched."
        },
        "complete": {
          "type": "boolean",
          "description": "Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search."
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date."
        },
        "paginationBasis": {
          "enum": [
            "affiliate_properties",
            "published_properties"
          ],
          "description": "Pagination counts affiliate properties or owner-published properties according to key scope."
        }
      },
      "required": [
        "page",
        "pageSize",
        "nextPage",
        "matchedProperties",
        "searchedProperties",
        "soldOutProperties",
        "withdrawnProperties",
        "partial",
        "pageComplete",
        "complete",
        "generatedAt",
        "paginationBasis"
      ],
      "additionalProperties": false,
      "description": "Response structure: Meta."
    },
    "SearchResponse": {
      "type": "object",
      "properties": {
        "contractVersion": {
          "const": 2,
          "description": "Response contract version; currently 2."
        },
        "query": {
          "$ref": "#/$defs/Query",
          "description": "Validated search inputs and defaults used to produce this response."
        },
        "listings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Listing"
          },
          "description": "Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability."
        },
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "property": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Stable identifier of this resource; preserve it unchanged."
                  },
                  "name": {
                    "type": "string",
                    "description": "Public display name."
                  },
                  "type": {
                    "enum": [
                      "hotel",
                      "vacation_rental"
                    ],
                    "description": "Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit."
                  },
                  "location": {
                    "type": "string",
                    "description": "Saved city/state display label, not a street address or map position."
                  },
                  "coverImage": {
                    "anyOf": [
                      {
                        "$ref": "#/$defs/PublicImage"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Public cover image metadata, or null when absent."
                  },
                  "photos": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri",
                      "description": "One value in the ordered collection."
                    },
                    "description": "Public photo URLs for this inventory; may be empty."
                  },
                  "destination": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Stable identifier of this resource; preserve it unchanged."
                      },
                      "name": {
                        "type": "string",
                        "description": "Public display name."
                      },
                      "regionId": {
                        "type": "string",
                        "description": "Qualified parent region ID, for example east-county-san-diego-ca, or the destination ID when no parent applies."
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "regionId"
                    ],
                    "additionalProperties": false,
                    "description": "Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography."
                  },
                  "mapLocation": {
                    "$ref": "#/$defs/PublicMapLocation",
                    "description": "Exact approved public coordinate pair, or null. Never use town-center guesses."
                  },
                  "timeZone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Property IANA timezone for date and time presentation; null means unknown."
                  }
                },
                "required": [
                  "id",
                  "name",
                  "photos",
                  "destination"
                ],
                "additionalProperties": false,
                "description": "Public property projection for compatibility consumers."
              },
              "rooms": {
                "type": "array",
                "items": {
                  "$ref": "#/$defs/LegacyRoom"
                },
                "description": "Bookable room or pooled room-type options."
              }
            },
            "required": [
              "property",
              "rooms"
            ],
            "additionalProperties": false,
            "description": "One record in results."
          },
          "description": "Per-property or per-request results. Inspect individual outcomes rather than treating every HTTP 200 as complete."
        },
        "failures": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "propertyId": {
                "type": "string",
                "description": "Raw Wikiup property identifier."
              },
              "code": {
                "enum": [
                  "timeout",
                  "provider_unavailable"
                ],
                "description": "Machine-readable provider failure code."
              },
              "retryable": {
                "const": true,
                "description": "True when the failed provider request may be retried."
              }
            },
            "required": [
              "propertyId",
              "code",
              "retryable"
            ],
            "additionalProperties": false,
            "description": "One record in failures."
          },
          "description": "Provider failures; never interpret these as sold-out inventory."
        },
        "meta": {
          "$ref": "#/$defs/Meta",
          "description": "Pagination and completion metadata."
        }
      },
      "required": [
        "contractVersion",
        "query",
        "listings",
        "results",
        "failures",
        "meta"
      ],
      "additionalProperties": false,
      "description": "Response structure: SearchResponse."
    },
    "ContentResponse": {
      "type": "object",
      "properties": {
        "listing": {
          "$ref": "#/$defs/ListingContent",
          "description": "Public detail for the requested stable listing ID."
        }
      },
      "required": [
        "listing"
      ],
      "additionalProperties": false,
      "description": "Response structure: ContentResponse."
    },
    "AvailabilityResponse": {
      "type": "object",
      "properties": {
        "listingId": {
          "type": "string",
          "description": "Stable hotel or rental listing ID from the catalog."
        },
        "status": {
          "enum": [
            "available",
            "sold_out"
          ],
          "description": "Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported."
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Option"
          },
          "description": "Exact bookable room/rental options matching the dates and party."
        },
        "complete": {
          "const": true,
          "description": "Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search."
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date."
        }
      },
      "required": [
        "listingId",
        "status",
        "options",
        "complete",
        "generatedAt"
      ],
      "additionalProperties": false,
      "description": "Response structure: AvailabilityResponse."
    },
    "ErrorResponse": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "description": "Human-readable error message; use status/code for program logic."
        },
        "complete": {
          "const": false,
          "description": "Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search."
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": {
                "type": "string",
                "description": "Dotted path of the invalid input field."
              },
              "message": {
                "type": "string",
                "description": "Explanation of the validation failure."
              }
            },
            "required": [
              "field",
              "message"
            ],
            "additionalProperties": false,
            "description": "One record in details."
          },
          "description": "Validation issues; present for invalid requests."
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false,
      "description": "Response structure: ErrorResponse."
    },
    "PhotoGroup": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "title": {
          "type": "string",
          "maxLength": 160,
          "description": "Display title supplied by Wikiup; group titles are Title Case."
        }
      },
      "required": [
        "id",
        "title"
      ],
      "additionalProperties": false,
      "description": "Response structure: PhotoGroup."
    },
    "GalleryGroup": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "title": {
          "type": "string",
          "maxLength": 160,
          "description": "Display title supplied by Wikiup; group titles are Title Case."
        },
        "imageIds": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "One value in the ordered collection."
          },
          "minItems": 1,
          "uniqueItems": true,
          "description": "IDs of gallery images in this group, in display order."
        }
      },
      "required": [
        "id",
        "title",
        "imageIds"
      ],
      "additionalProperties": false,
      "description": "Response structure: GalleryGroup."
    },
    "CatalogListing": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property identifier."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "propertyName": {
          "type": "string",
          "description": "Public property listing title, falling back to property name."
        },
        "location": {
          "type": "string",
          "description": "Saved city/state display label, not a street address or map position."
        },
        "destination": {
          "type": "string",
          "description": "Qualified catalog destination ID, for example julian-ca, aurora-co, aurora-il, paris-tx, or paris-fr. Responses use canonical IDs; null where allowed means unknown geography."
        },
        "type": {
          "enum": [
            "hotel",
            "vacation_rental"
          ],
          "description": "Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit."
        },
        "maxGuests": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards."
        },
        "availabilityStatus": {
          "const": "unchecked",
          "description": "Unchecked means no date/occupancy/pricing calculation has run for this catalog card."
        },
        "coverImage": {
          "oneOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ],
          "description": "Public cover image metadata, or null when absent."
        },
        "imageStatus": {
          "enum": [
            "deferred",
            "none",
            "pending",
            "ready"
          ],
          "description": "deferred: not requested; none: no photo; ready: metadata available; pending: source exists but metadata is unavailable."
        },
        "mapLocation": {
          "$ref": "#/$defs/PublicMapLocation",
          "description": "Exact approved public coordinate pair, or null. Never use town-center guesses."
        },
        "timeZone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Validated property IANA time zone. Use for local timestamps; null means unknown."
        },
        "stayType": {
          "enum": [
            "hotel",
            "inn",
            "bed_and_breakfast",
            "resort",
            "vacation_rental",
            null
          ],
          "description": "Owner-supplied subtype compatible with the existing broad type; null when unknown or inconsistent. Does not select the booking flow."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 240,
          "description": "Plain text from this exact listing description. HTML and common booking/placeholder prompts removed. Unknown is null."
        },
        "tagLine": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "Explicit owner-provided hotel facts or beds/baths from the exact rental unit or room-type content. Not live available inventory. Unknown is null. Limited to 100 Unicode characters including an ellipsis when shortened."
        },
        "ratings": {
          "$ref": "#/$defs/AffiliateRating",
          "description": "Present only with fetch=ratings; omitted otherwise. Unset values are null."
        }
      },
      "required": [
        "id",
        "propertyId",
        "name",
        "propertyName",
        "location",
        "destination",
        "type",
        "availabilityStatus",
        "coverImage",
        "imageStatus",
        "mapLocation",
        "timeZone",
        "stayType",
        "description",
        "tagLine"
      ],
      "additionalProperties": false,
      "description": "Response structure: CatalogListing."
    },
    "CatalogMeta": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "minimum": 0,
          "description": "One-based property page number."
        },
        "pageSize": {
          "type": "integer",
          "minimum": 0,
          "description": "Property count per page, not listing-card count; rental properties can produce multiple cards."
        },
        "matchedProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Eligible properties matching geography before this page is evaluated."
        },
        "checkedProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Properties successfully processed in this response."
        },
        "withdrawnProperties": {
          "type": "integer",
          "minimum": 0,
          "description": "Properties removed because eligibility changed while processing."
        },
        "nextPage": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Next property page number, or null at the end."
        },
        "paginationBasis": {
          "const": "affiliate_properties",
          "description": "Pagination counts affiliate properties or owner-published properties according to key scope."
        },
        "partial": {
          "type": "boolean",
          "description": "True when provider failures make the current response incomplete."
        },
        "pageComplete": {
          "type": "boolean",
          "description": "True when this page has no provider failures; does not imply all pages were fetched."
        },
        "complete": {
          "type": "boolean",
          "description": "Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search."
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date."
        }
      },
      "required": [
        "page",
        "pageSize",
        "nextPage",
        "paginationBasis",
        "matchedProperties",
        "checkedProperties",
        "withdrawnProperties",
        "partial",
        "pageComplete",
        "complete",
        "generatedAt"
      ],
      "additionalProperties": false,
      "description": "Response structure: CatalogMeta."
    },
    "CatalogResponse": {
      "type": "object",
      "properties": {
        "contractVersion": {
          "const": 2,
          "description": "Response contract version; currently 2."
        },
        "query": {
          "type": "object",
          "properties": {
            "destination": {
              "type": "string",
              "description": "Optional geographic filter. Omitted when browsing all approved properties; otherwise a canonical destination, parent-region or county ID."
            },
            "page": {
              "type": "integer",
              "minimum": 0,
              "description": "One-based property page number."
            },
            "pageSize": {
              "type": "integer",
              "minimum": 0,
              "description": "Property count per page, not listing-card count; rental properties can produce multiple cards."
            },
            "includeImages": {
              "type": "boolean",
              "description": "Whether prepared cover metadata was requested; defaults to false."
            },
            "fetch": {
              "const": "ratings",
              "description": "Present only when the request opted into affiliate ratings."
            }
          },
          "required": [
            "page",
            "pageSize",
            "includeImages"
          ],
          "additionalProperties": false,
          "description": "Validated search inputs and defaults used to produce this response."
        },
        "listings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CatalogListing"
          },
          "description": "Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability."
        },
        "failures": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "propertyId": {
                "type": "string",
                "description": "Raw Wikiup property identifier."
              },
              "code": {
                "enum": [
                  "timeout",
                  "provider_unavailable"
                ],
                "description": "Machine-readable provider failure code."
              },
              "retryable": {
                "const": true,
                "description": "True when the failed provider request may be retried."
              }
            },
            "required": [
              "propertyId",
              "code",
              "retryable"
            ],
            "additionalProperties": false,
            "description": "One record in failures."
          },
          "description": "Provider failures; never interpret these as sold-out inventory."
        },
        "meta": {
          "$ref": "#/$defs/CatalogMeta",
          "description": "Pagination and completion metadata."
        }
      },
      "required": [
        "contractVersion",
        "query",
        "listings",
        "failures",
        "meta"
      ],
      "additionalProperties": false,
      "description": "Response structure: CatalogResponse."
    },
    "BatchListing": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "type": {
          "enum": [
            "hotel",
            "vacation_rental"
          ],
          "description": "Listing kind: hotel has a property-level room selection flow; vacation_rental identifies a bookable unit."
        },
        "propertyId": {
          "type": "string",
          "description": "Raw Wikiup property identifier."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "propertyName": {
          "type": "string",
          "description": "Public property listing title, falling back to property name."
        },
        "location": {
          "type": "string",
          "description": "Saved city/state display label, not a street address or map position."
        },
        "maxGuests": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this rental or option. Null, where allowed, means unknown; absent on hotel cards."
        },
        "availableRoomCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of qualifying rooms across the hotel for these dates and party."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. All amounts are in major currency units."
        },
        "nightlyRate": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Average accommodation rate per night for this requested stay, excluding taxes and fees."
        },
        "staySubtotal": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees."
        },
        "priceBasis": {
          "const": "accommodation_subtotal",
          "description": "Prices are accommodation subtotals, not final checkout totals."
        },
        "taxes": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "fees": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "finalTotal": {
          "type": "null",
          "description": "Determined at checkout. Null must not be displayed as zero."
        },
        "bookingUrl": {
          "type": "string",
          "format": "uri",
          "description": "Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it."
        },
        "priceLabel": {
          "enum": [
            "From",
            "Stay"
          ],
          "description": "From for the lowest qualifying hotel option; Stay for a rental."
        },
        "mapLocation": {
          "$ref": "#/$defs/PublicMapLocation",
          "description": "Exact approved public coordinate pair, or null. Never use town-center guesses."
        },
        "timeZone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Validated property IANA time zone. Use for local timestamps; null means unknown."
        }
      },
      "required": [
        "id",
        "type",
        "propertyId",
        "name",
        "propertyName",
        "location",
        "currency",
        "nightlyRate",
        "staySubtotal",
        "priceBasis",
        "taxes",
        "fees",
        "finalTotal",
        "bookingUrl",
        "priceLabel",
        "mapLocation",
        "timeZone"
      ],
      "additionalProperties": false,
      "description": "Response structure: BatchListing."
    },
    "BatchOption": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier of this resource; preserve it unchanged."
        },
        "roomId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Physical room identifier; null for a pooled room-type option."
        },
        "roomTypeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Room-type identifier for pooled inventory; null for a named room."
        },
        "name": {
          "type": "string",
          "description": "Public display name."
        },
        "capacity": {
          "type": "integer",
          "minimum": 0,
          "description": "Maximum supported guests for this exact bookable option."
        },
        "availableCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of physical units assignable throughout the entire requested stay; not a hold."
        },
        "currency": {
          "type": "string",
          "description": "Three-letter currency code. All amounts are in major currency units."
        },
        "nightlyRate": {
          "type": "number",
          "minimum": 0,
          "description": "Average accommodation rate per night for this requested stay, excluding taxes and fees."
        },
        "staySubtotal": {
          "type": "number",
          "minimum": 0,
          "description": "Accommodation subtotal for all nights after applicable pricing; excludes taxes and fees."
        },
        "priceBasis": {
          "const": "accommodation_subtotal",
          "description": "Prices are accommodation subtotals, not final checkout totals."
        },
        "taxes": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "fees": {
          "type": "null",
          "description": "Not quoted by this endpoint. Null means unknown until checkout, not zero."
        },
        "finalTotal": {
          "type": "null",
          "description": "Determined at checkout. Null must not be displayed as zero."
        },
        "bookingUrl": {
          "type": "string",
          "format": "uri",
          "description": "Signed affiliate checkout URL. Preserve unchanged; do not construct, strip parameters or cache it."
        }
      },
      "required": [
        "id",
        "roomId",
        "roomTypeId",
        "name",
        "capacity",
        "availableCount",
        "currency",
        "nightlyRate",
        "staySubtotal",
        "priceBasis",
        "taxes",
        "fees",
        "finalTotal",
        "bookingUrl"
      ],
      "additionalProperties": false,
      "description": "Response structure: BatchOption."
    },
    "BatchResult": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string",
              "description": "Exact requested listing ID or raw property ID; use to merge results with the request."
            },
            "propertyId": {
              "type": "string",
              "description": "Raw Wikiup property identifier."
            },
            "status": {
              "enum": [
                "available",
                "sold_out"
              ],
              "description": "Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported."
            },
            "listings": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/BatchListing"
              },
              "description": "Public display listings for this response. Catalog listings are unchecked; priced listings represent matching availability."
            },
            "options": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/BatchOption"
              },
              "description": "Exact bookable room/rental options matching the dates and party."
            }
          },
          "required": [
            "requestId",
            "propertyId",
            "status",
            "listings",
            "options"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string",
              "description": "Exact requested listing ID or raw property ID; use to merge results with the request."
            },
            "propertyId": {
              "type": "string",
              "description": "Raw Wikiup property identifier."
            },
            "status": {
              "const": "not_found",
              "description": "Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported."
            }
          },
          "required": [
            "requestId",
            "propertyId",
            "status"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "requestId": {
              "type": "string",
              "description": "Exact requested listing ID or raw property ID; use to merge results with the request."
            },
            "propertyId": {
              "type": "string",
              "description": "Raw Wikiup property identifier."
            },
            "status": {
              "const": "error",
              "description": "Outcome discriminator; available and sold_out are successful checks, not_found is inaccessible inventory, error is a provider failure where supported."
            },
            "code": {
              "enum": [
                "timeout",
                "provider_unavailable"
              ],
              "description": "Machine-readable provider failure code."
            },
            "retryable": {
              "const": true,
              "description": "True when the failed provider request may be retried."
            }
          },
          "required": [
            "requestId",
            "propertyId",
            "status",
            "code",
            "retryable"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Response structure: BatchResult."
    },
    "BatchAvailabilityResponse": {
      "type": "object",
      "properties": {
        "query": {
          "$ref": "#/$defs/BatchCriteria",
          "description": "Validated search inputs and defaults used to produce this response."
        },
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BatchResult"
          },
          "description": "Per-property or per-request results. Inspect individual outcomes rather than treating every HTTP 200 as complete."
        },
        "complete": {
          "type": "boolean",
          "description": "Whether the operation completed without provider failures. For paginated catalog/search, true only on a complete single-page search."
        },
        "meta": {
          "type": "object",
          "properties": {
            "requested": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of requested listing/property targets."
            },
            "checkedProperties": {
              "type": "integer",
              "minimum": 0,
              "description": "Properties successfully processed in this response."
            },
            "failedProperties": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of properties with provider failures; inaccessible properties are not counted."
            },
            "generatedAt": {
              "type": "string",
              "format": "date-time",
              "description": "Response generation instant (ISO 8601). Format guest-visible timestamps in the relevant property timeZone; this is not a booking date."
            }
          },
          "required": [
            "requested",
            "checkedProperties",
            "failedProperties",
            "generatedAt"
          ],
          "additionalProperties": false,
          "description": "Pagination and completion metadata."
        }
      },
      "required": [
        "query",
        "results",
        "complete",
        "meta"
      ],
      "additionalProperties": false,
      "description": "Response structure: BatchAvailabilityResponse."
    },
    "BatchCriteria": {
      "type": "object",
      "properties": {
        "checkIn": {
          "type": "string",
          "format": "date",
          "description": "Arrival calendar date in the property timezone, YYYY-MM-DD."
        },
        "checkOut": {
          "type": "string",
          "format": "date",
          "description": "Departure calendar date, YYYY-MM-DD; checkout is not an occupied night."
        },
        "adults": {
          "type": "integer",
          "minimum": 0,
          "description": "Adult guest count; defaults to 2 in requests."
        },
        "children": {
          "type": "integer",
          "minimum": 0,
          "description": "Child guest count; defaults to 0 in requests."
        },
        "pets": {
          "type": "integer",
          "minimum": 0,
          "description": "Pet count; defaults to 0 in requests."
        }
      },
      "required": [
        "checkIn",
        "checkOut",
        "adults",
        "children",
        "pets"
      ],
      "additionalProperties": false,
      "description": "Response structure: BatchCriteria."
    },
    "PublicMapLocation": {
      "description": "Confirmed exact public property coordinates, or null when no public exact location is available. No approximate points or destination-center fallbacks.",
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "required": [
        "latitude",
        "longitude"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Exact approved public latitude in decimal degrees."
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Exact approved public longitude in decimal degrees."
        }
      }
    },
    "AffiliateRating": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "starRating",
        "priceTier"
      ],
      "properties": {
        "starRating": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 1,
          "maximum": 5,
          "multipleOf": 0.5,
          "description": "Requesting affiliate\u2019s editorial star ratings; 1\u20135 in half-star increments. Not guest reviews."
        },
        "priceTier": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "maximum": 5,
          "description": "Requesting affiliate\u2019s price tier, 1\u20135. Not a price quote."
        }
      },
      "description": "Editorial ratings owned by the authenticated affiliate; fetched only on request."
    },
    "ListingAddress": {
      "type": "object",
      "properties": {
        "line1": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved property street address."
        },
        "line2": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional additional property address line; null when empty."
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved property city."
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved property state/province."
        },
        "postalCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved property postal/ZIP code; a string to preserve leading zeros."
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved country value; may be a country name or code. Do not assume ISO format."
        }
      },
      "required": [
        "line1",
        "line2",
        "city",
        "state",
        "postalCode",
        "country"
      ],
      "additionalProperties": false,
      "description": "Response structure: ListingAddress."
    },
    "ListingContact": {
      "type": "object",
      "properties": {
        "phone": {
          "type": [
            "string",
            "null"
          ],
          "description": "Property business phone text, not an owner-account phone; null when absent."
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "Property business email, not an owner-account email; null when absent."
        },
        "websiteUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved HTTP(S) property website, or null for absent/invalid/credential-bearing values. Not an affiliate-attributed checkout URL."
        }
      },
      "required": [
        "phone",
        "email",
        "websiteUrl"
      ],
      "additionalProperties": false,
      "description": "Response structure: ListingContact."
    },
    "HotelRoomContent": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Opaque option ID, identical to the parent availability option id. Encode once per path segment."
        },
        "listingId": {
          "type": "string",
          "description": "Parent hotel listing ID; inns use hotel booking identity too."
        },
        "propertyId": {
          "type": "string",
          "description": "Stable property ID."
        },
        "roomId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Named room ID, or null for pooled room types."
        },
        "roomTypeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Pooled room type ID, or null for named rooms. No physical member is selected."
        },
        "name": {
          "type": "string",
          "description": "Public title or saved room/type name."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Saved public room/type description; may contain HTML. Sanitize before rendering. Null when absent; never property fallback."
        },
        "capacity": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1,
          "description": "Advertised maximum guest count, or null when unknown. Fresh availability still applies party restrictions."
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "One public amenity name."
          },
          "description": "Public room/type amenity names. Empty when absent."
        },
        "coverImage": {
          "anyOf": [
            {
              "$ref": "#/$defs/PublicImage"
            },
            {
              "type": "null"
            }
          ],
          "description": "First room/type gallery image or null; never a property-photo fallback."
        },
        "gallery": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PublicImage"
          },
          "description": "Ordered public room/type gallery, empty when absent. Excludes check-in galleries."
        },
        "galleryGroups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GalleryGroup"
          },
          "description": "Ordered photo groups referencing gallery image IDs."
        }
      },
      "required": [
        "id",
        "listingId",
        "propertyId",
        "roomId",
        "roomTypeId",
        "name",
        "description",
        "capacity",
        "amenities",
        "coverImage",
        "gallery",
        "galleryGroups"
      ],
      "allOf": [
        {
          "oneOf": [
            {
              "properties": {
                "roomId": {
                  "type": "string"
                },
                "roomTypeId": {
                  "type": "null"
                }
              }
            },
            {
              "properties": {
                "roomId": {
                  "type": "null"
                },
                "roomTypeId": {
                  "type": "string"
                }
              }
            }
          ]
        }
      ],
      "description": "Public details and photos for one active hotel room or pooled room type."
    },
    "RoomContentResponse": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "room": {
          "$ref": "#/$defs/HotelRoomContent",
          "description": "Date-free public content for one eligible hotel option. Not an availability quote or a reservation."
        }
      },
      "required": [
        "room"
      ]
    },
    "RoomCollectionResponse": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "rooms",
        "meta"
      ],
      "properties": {
        "rooms": {
          "type": "array",
          "maxItems": 12,
          "items": {
            "$ref": "#/$defs/HotelRoomContent"
          },
          "description": "Active hotel rooms or pooled types, independent of date availability. Same fields as individual room detail."
        },
        "meta": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "page",
            "nextPage"
          ],
          "properties": {
            "page": {
              "type": "integer",
              "minimum": 1,
              "description": "Requested page, starting at 1."
            },
            "nextPage": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1,
              "description": "Next page number, or null when all rooms have been returned."
            }
          },
          "description": "Pagination for this room collection; follow nextPage until null."
        }
      }
    }
  }
}
