Source of truth for implementation is the canonical schema host: https://schemas.meta-aiml.org/v3.0.0/. If any page text conflicts with canonical schema files, follow canonical files. Documentation home.

Hotel

v3.0.0

PhysicalEntity

Hospitality

v3 schema for accommodation providers delivering lodging services directly to guests at physical properties with reservation, stay, and guest service operations.

Top-level required

Required modules

Capability groups

Entity properties

Canonical Files

Contract URL: https://schemas.meta-aiml.org/v3.0.0/entity/hotel.json

Example URL: https://schemas.meta-aiml.org/v3.0.0/examples/hotel_example_schema_v3.json

Inheritance Chain

https://schemas.meta-aiml.org/v3.0.0/ontology/physical_entity.json

https://schemas.meta-aiml.org/v3.0.0/archetypes/direct_service.json

Interaction archetype

DirectService

Required Top-level Fields

These fields are enforced by JSON Schema required[] at root level.

@type

ontologicalMode

interactionArchetype

domain

name

description

deliveryFormat

modules

capabilities

structuralMetadata

Non-universal required fields

interactionArchetype

Entity-specific Properties

Keys under properties.properties dedicated to this entity contract.

checkInTime

checkOutTime

contactPoints

identifiers

propertyType

roomCount

socialProfiles

starCategory

supportsLongStay

Modules Contract

Required modules

location

Optional modules

guestServices

inventory

Capabilities Contract

Required capability groups

interaction

booking

Optional capability groups

amenities

financial

location

Governance Validation Rules

Normative rule list from governanceMetadata.sdkValidationRules.

RULE-HOTL-001: @type MUST equal "Hotel"

RULE-HOTL-002: ontologicalMode MUST equal "PhysicalEntity"

RULE-HOTL-003: interactionArchetype MUST contain "DirectService"

RULE-HOTL-004: deliveryFormat MUST contain "PhysicalLocation"

RULE-HOTL-005: modules.location MUST be present

RULE-HOTL-006: capabilities.interaction MUST be present

Canonical Contract JSON

https://schemas.meta-aiml.org/v3.0.0/entity/hotel.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://schemas.meta-aiml.org/v3.0.0/entity/hotel.json",
  "$id": "https://schemas.meta-aiml.org/v3.0.0/entity/hotel.json",
  "@type": "Hotel",
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Hotel Entity Schema",
  "description": "v3 schema for accommodation providers delivering lodging services directly to guests at physical properties with reservation, stay, and guest service operations.",
  "examples": [
    {
      "description": "Business hotel with digital check-in and conference room booking",
      "reference": "hotel_example_business"
    },
    {
      "description": "Resort hotel with package plans and family-oriented amenities",
      "reference": "hotel_example_resort"
    }
  ],
  "type": "object",
  "additionalProperties": false,
  "allOf": [
    {
      "$ref": "../ontology/physical_entity.json"
    },
    {
      "$ref": "../archetypes/direct_service.json"
    }
  ],
  "properties": {
    "@type": {
      "const": "Hotel"
    },
    "ontologicalMode": {
      "const": "PhysicalEntity"
    },
    "interactionArchetype": {
      "type": "array",
      "contains": {
        "const": "DirectService"
      },
      "items": {
        "type": "string",
        "enum": [
          "DirectService"
        ]
      }
    },
    "domain": {
      "const": "Hospitality"
    },
    "businessModel": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Transactional",
          "PackagePricing",
          "Subscription"
        ]
      }
    },
    "deliveryFormat": {
      "type": "array",
      "contains": {
        "const": "PhysicalLocation"
      },
      "items": {
        "type": "string",
        "enum": [
          "PhysicalLocation",
          "WebApp",
          "MobileApp"
        ]
      }
    },
    "name": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "description": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedText"
    },
    "shortDescription": {
      "$ref": "../components/multilingual_format.json#/$defs/LocalizedTextOrString"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "foundingDate": {
      "type": "string",
      "format": "date"
    },
    "properties": {
      "type": "object",
      "properties": {
        "propertyType": {
          "type": "string",
          "enum": [
            "hotel",
            "resort",
            "boutique",
            "aparthotel",
            "hostel"
          ]
        },
        "starCategory": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5
        },
        "roomCount": {
          "type": "integer",
          "minimum": 1
        },
        "checkInTime": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "checkOutTime": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "supportsLongStay": {
          "type": "boolean"
        },
        "contactPoints": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/ContactPoint"
          }
        },
        "socialProfiles": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/SocialProfile"
          }
        },
        "identifiers": {
          "type": "array",
          "items": {
            "$ref": "../components/common_defs.json#/$defs/Identifier"
          }
        }
      }
    },
    "capabilities": {
      "type": "object",
      "required": [
        "interaction",
        "booking"
      ],
      "properties": {
        "interaction": {
          "$ref": "../components/capability_groups.json#/$defs/InteractionCapabilities"
        },
        "booking": {
          "$ref": "../components/capability_groups.json#/$defs/BookingCapabilities"
        },
        "financial": {
          "$ref": "../components/capability_groups.json#/$defs/FinancialCapabilities"
        },
        "location": {
          "$ref": "../components/capability_groups.json#/$defs/LocationCapabilities"
        },
        "amenities": {
          "$ref": "../components/capability_groups.json#/$defs/AmenitiesCapabilities"
        }
      }
    },
    "modules": {
      "type": "object",
      "required": [
        "location"
      ],
      "properties": {
        "location": {
          "type": "object",
          "properties": {
            "address": {
              "$ref": "../components/address_format.json#/$defs/PostalAddress"
            },
            "geoCoordinates": {
              "$ref": "../components/address_format.json#/$defs/GeoCoordinates"
            }
          }
        },
        "inventory": {
          "type": "object",
          "properties": {
            "roomTypeCatalog": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "dynamicPricingEnabled": {
              "type": "boolean"
            },
            "overbookingProtectionEnabled": {
              "type": "boolean"
            }
          }
        },
        "guestServices": {
          "type": "object",
          "properties": {
            "digitalKeyEnabled": {
              "type": "boolean"
            },
            "conciergeChatEnabled": {
              "type": "boolean"
            },
            "roomServiceOrderingEnabled": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "structuralMetadata": {
      "type": "object",
      "properties": {
        "topology": {
          "const": "binary"
        },
        "roles": {
          "const": [
            "user",
            "platform"
          ]
        },
        "valueSource": {
          "const": "platform_provided"
        },
        "transactionFlow": {
          "const": "direct"
        },
        "networkEffects": {
          "const": "none"
        },
        "serviceOrientation": {
          "type": "string",
          "enum": [
            "short_stay",
            "extended_stay",
            "hybrid"
          ]
        }
      }
    },
    "targetAudience": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "siteCapabilities": {
      "type": "object",
      "properties": {
        "supportedDevices": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "desktop",
              "mobile",
              "tablet"
            ]
          }
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "accessibilityFeatures": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "@type",
    "ontologicalMode",
    "interactionArchetype",
    "domain",
    "name",
    "description",
    "deliveryFormat",
    "modules",
    "capabilities",
    "structuralMetadata"
  ],
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "entity",
    "status": "draft",
    "lastValidated": "2026-02-20T12:00:00Z",
    "validator": "META-AIML QA"
  },
  "semanticAnnotations": {
    "classificationRationale": "Hotel is modeled as PhysicalEntity + DirectService because accommodation is physically delivered at property location by the service provider.",
    "disambiguationNotes": "Different from listing aggregators and travel marketplaces that primarily mediate third-party inventory."
  },
  "governanceMetadata": {
    "entityVersion": "3.0.0",
    "introducedIn": "META-AIML v3.0.0",
    "stabilityLevel": "draft",
    "sdkValidationRules": [
      "RULE-HOTL-001: @type MUST equal \"Hotel\"",
      "RULE-HOTL-002: ontologicalMode MUST equal \"PhysicalEntity\"",
      "RULE-HOTL-003: interactionArchetype MUST contain \"DirectService\"",
      "RULE-HOTL-004: deliveryFormat MUST contain \"PhysicalLocation\"",
      "RULE-HOTL-005: modules.location MUST be present",
      "RULE-HOTL-006: capabilities.interaction MUST be present"
    ]
  }
}

Filled Example Instance

https://schemas.meta-aiml.org/v3.0.0/examples/hotel_example_schema_v3.json

{
  "@context": [
    "https://schemas.meta-aiml.org/v3.0.0/context.jsonld"
  ],
  "@id": "https://data.meta-aiml.org/v3.0.0/examples/hotel/cedar-grand-hotel",
  "$id": "https://data.meta-aiml.org/v3.0.0/examples/hotel/cedar-grand-hotel",
  "@type": "Hotel",
  "schemaVersion": "3.0.0",
  "aimlVersion": "3.0.0",
  "title": "Example Filled Hotel Entity Example (Cedar Grand Hotel)",
  "ontologicalMode": "PhysicalEntity",
  "interactionArchetype": [
    "DirectService"
  ],
  "domain": "Hospitality",
  "businessModel": [
    "Transactional",
    "PackagePricing",
    "Subscription"
  ],
  "deliveryFormat": [
    "PhysicalLocation",
    "WebApp",
    "MobileApp"
  ],
  "name": {
    "en": "Cedar Grand Hotel",
    "es": "Hotel Cedar Grand",
    "fr": "Hotel Cedar Grand"
  },
  "description": {
    "en": "Cedar Grand Hotel is a fictional upscale city hotel offering direct booking, digital check-in, concierge support, and bundled stay packages for business and leisure travelers.",
    "es": "Cedar Grand Hotel es un hotel urbano ficticio de categoria alta con reserva directa, check-in digital y paquetes de estancia para viajeros de negocio y ocio.",
    "fr": "Cedar Grand Hotel est un hotel urbain fictif haut de gamme avec reservation directe, enregistrement numerique et offres de sejour pour affaires et loisirs."
  },
  "shortDescription": {
    "en": "Upscale city hotel with direct reservations, digital check-in, and concierge services.",
    "es": "Hotel urbano premium con reservas directas, check-in digital y servicios de conserjeria.",
    "fr": "Hotel urbain premium avec reservations directes, enregistrement numerique et conciergerie."
  },
  "url": "https://cedar-grand-hotel.example",
  "foundingDate": "2015-04-06",
  "createdDate": "2026-02-20T20:07:00Z",
  "lastModified": "2026-02-20T20:07:00Z",
  "examples": [
    {
      "scenario": "Conference season occupancy surge",
      "note": "AI should prioritize room availability logic, package pricing, and overbooking protection signals for direct bookings."
    },
    {
      "scenario": "Late-night guest service requests",
      "note": "AI should route requests through concierge and digital key workflows without treating the site as an OTA marketplace."
    }
  ],
  "properties": {
    "propertyType": "hotel",
    "starCategory": 4,
    "roomCount": 286,
    "checkInTime": "15:00",
    "checkOutTime": "11:00",
    "supportsLongStay": true,
    "contactPoints": [
      {
        "contactType": "customer_service",
        "telephone": "+1-312-555-0138",
        "email": "reservations@cedar-grand-hotel.example",
        "url": "https://cedar-grand-hotel.example/reservations",
        "areaServed": "Chicago Metro",
        "availableLanguages": [
          "en",
          "es",
          "fr"
        ]
      },
      {
        "contactType": "general",
        "telephone": "+1-312-555-0102",
        "email": "guest-services@cedar-grand-hotel.example",
        "url": "https://cedar-grand-hotel.example/contact",
        "areaServed": "Chicago Metro",
        "availableLanguages": [
          "en",
          "es"
        ]
      }
    ],
    "socialProfiles": [
      {
        "platform": "instagram",
        "url": "https://instagram.com/cedargrandhotel",
        "username": "cedargrandhotel"
      },
      {
        "platform": "facebook",
        "url": "https://facebook.com/cedargrandhotel",
        "username": "cedargrandhotel"
      },
      {
        "platform": "linkedin",
        "url": "https://www.linkedin.com/company/cedar-grand-hotel",
        "username": "cedar-grand-hotel"
      }
    ],
    "identifiers": [
      {
        "type": "url",
        "value": "https://cedar-grand-hotel.example"
      },
      {
        "type": "custom",
        "value": "HOTL-CGH-001"
      }
    ]
  },
  "capabilities": {
    "interaction": {
      "features": [
        "messaging",
        "rating",
        "reviews",
        "notifications"
      ],
      "interactionMethods": [
        "online_form",
        "phone_call",
        "chat",
        "email"
      ],
      "availableActions": [
        "book_room",
        "modify_booking",
        "request_early_checkin",
        "contact_concierge",
        "read_reviews"
      ],
      "hasMessaging": true,
      "hasComments": false,
      "hasRating": true,
      "hasReviews": true,
      "hasSocialGraph": false,
      "hasFeed": false,
      "hasNotifications": true,
      "hasMatching": false,
      "realTimeCommunication": true,
      "moderationEnabled": true,
      "privacyControls": [
        "public",
        "private"
      ]
    },
    "booking": {
      "features": [
        "reservation",
        "availabilityCheck",
        "scheduling",
        "calendarSync",
        "instantBooking",
        "cancellation",
        "reminder"
      ],
      "acceptsReservations": true,
      "requiresDeposit": true,
      "cancellationPolicy": "48_hours",
      "minimumAdvanceBooking": "PT1H",
      "maximumAdvanceBooking": "P365D",
      "realTimeFeatures": [
        "real_time_availability",
        "instant_confirmation"
      ],
      "bookingChannels": [
        "website",
        "mobile_app",
        "phone"
      ]
    },
    "financial": {
      "features": [
        "payments",
        "invoicing",
        "refunds",
        "billing",
        "subscriptionManagement"
      ],
      "paymentMethods": [
        "credit_card",
        "debit_card",
        "digital_wallet",
        "bank_transfer"
      ],
      "acceptsCreditCards": true,
      "currencies": [
        "USD",
        "EUR"
      ],
      "priceRange": "mid_to_upscale",
      "commissionModel": "flat_fee",
      "commissionRate": 0,
      "supportsSubscriptions": true,
      "supportsInvoicing": true,
      "refundPolicy": "partial_refund"
    },
    "location": {
      "features": [
        "physicalAddress",
        "geoCoordinates",
        "directions",
        "mapIntegration",
        "routing"
      ],
      "hasPhysicalAddress": true,
      "hasGeoCoordinates": true,
      "hasMultipleLocations": false,
      "hasParking": true,
      "parkingType": "onsite",
      "isWheelchairAccessible": true,
      "publicTransitAccess": true,
      "deliveryZones": [],
      "serviceRadius": 0
    },
    "amenities": {
      "features": [
        "wifi",
        "parking",
        "accessibility",
        "childFriendly"
      ],
      "hasWifi": true,
      "wifiSpeed": "high_speed",
      "hasPowerOutlets": true,
      "hasOutdoorSeating": false,
      "hasVegetarianOptions": false,
      "hasVeganOptions": false,
      "hasGlutenFreeOptions": true,
      "petPolicy": "restricted",
      "isChildFriendly": true,
      "hasPlayArea": false,
      "hasHighchairs": true,
      "hasChangingFacilities": true,
      "isQuiet": true,
      "hasPrivateRooms": true
    }
  },
  "modules": {
    "location": {
      "address": {
        "streetAddress": "420 West Lakeshore Drive",
        "addressLocality": "Chicago",
        "addressRegion": "IL",
        "postalCode": "60601",
        "addressCountry": "US"
      },
      "geoCoordinates": {
        "latitude": 41.8887,
        "longitude": -87.6189,
        "accuracy": 8
      }
    },
    "inventory": {
      "roomTypeCatalog": [
        "standard_king",
        "deluxe_double",
        "executive_suite",
        "accessible_king"
      ],
      "dynamicPricingEnabled": true,
      "overbookingProtectionEnabled": true
    },
    "guestServices": {
      "digitalKeyEnabled": true,
      "conciergeChatEnabled": true,
      "roomServiceOrderingEnabled": true
    },
    "reviews": {
      "ratingSources": [
        {
          "provider": "google_business_profile",
          "sourceType": "public_page",
          "sourceUrl": "https://www.google.com/maps/place/Cedar+Grand+Hotel",
          "format": "html",
          "updateCadence": "daily"
        },
        {
          "provider": "tripadvisor",
          "sourceType": "public_page",
          "sourceUrl": "https://www.tripadvisor.com/Hotel_Review-g35805-d123450987",
          "format": "html",
          "updateCadence": "daily"
        }
      ],
      "retrievalPolicy": {
        "requiresLiveFetch": true,
        "recommendedRefreshHours": 24
      }
    }
  },
  "structuralMetadata": {
    "topology": "binary",
    "roles": [
      "user",
      "platform"
    ],
    "valueSource": "platform_provided",
    "transactionFlow": "direct",
    "networkEffects": "none",
    "serviceOrientation": "hybrid"
  },
  "targetAudience": [
    "business_travelers",
    "leisure_travelers",
    "conference_attendees",
    "family_travelers"
  ],
  "siteCapabilities": {
    "supportedDevices": [
      "desktop",
      "mobile",
      "tablet"
    ],
    "languages": [
      "en",
      "es",
      "fr"
    ],
    "accessibilityFeatures": [
      "keyboard_navigation",
      "screen_reader_labels",
      "text_scaling",
      "high_contrast_mode"
    ]
  },
  "validationMetadata": {
    "schemaVersion": "3.0.0",
    "phase": "example_instance",
    "status": "reference",
    "lastValidated": "2026-02-20T20:07:00Z",
    "validator": "META-AIML SDK v3"
  },
  "semanticAnnotations": {
    "classificationRationale": "Hotel is modeled as PhysicalEntity plus DirectService because accommodation and guest support are delivered directly by the operator at a physical property.",
    "disambiguationNotes": "This model is not an online travel marketplace. External rating links are references for live retrieval and not embedded static review snapshots.",
    "intendedUse": "Canonical filled reference for hotel websites publishing static schema for AI interpretation and navigation."
  },
  "governanceMetadata": {
    "entityVersion": "3.0.0",
    "introducedIn": "META-AIML v3.0.0",
    "stabilityLevel": "reference",
    "sdkValidationRules": [
      "RULE-HTGF-001: @type MUST equal \"Hotel\"",
      "RULE-HTGF-002: ontologicalMode MUST equal \"PhysicalEntity\"",
      "RULE-HTGF-003: interactionArchetype MUST contain exactly one value: \"DirectService\"",
      "RULE-HTGF-004: deliveryFormat MUST include \"PhysicalLocation\"",
      "RULE-HTGF-005: capabilities MUST include interaction and booking groups",
      "RULE-HTGF-006: modules.location MUST include valid address and geoCoordinates",
      "RULE-HTGF-007: modules.reviews MUST use source links and MUST NOT embed aggregate snapshots",
      "RULE-HTGF-008: structuralMetadata constants MUST align with DirectService archetype"
    ]
  }
}

All entities Clinic Restaurant