Modeling methods

Working proposal

This page outlines the methodology currently in use for developing the Universal Hospitality Domain Model (UHDM). The process and tooling described here are evolving as new APIs are analyzed.

Overview

The UHDM methodology follows a structured, multi-layered approach to derive a universal domain model for hospitality systems. It combines automated data extraction from real-world APIs with human curation and semantic formalization.

The process involves four main stages:

1. Reverse-engineering existing hospitality PMS APIs and schemas to extract business concepts.
2. Comparing and correlating those extractions to identify common entities and relationships.
3. Formalizing the shared concepts into a unified, technology-agnostic domain model.
4. Translating that model into a structured ontology and schema (for example, JSON-LD) suitable for interoperability, integration, and AI contexts.

Model architecture

The UHDM can be viewed as three logical layers, each feeding into the next:

┌─────────────────────────────┐
│  Canonical Layer (Ontology) │   ← curated, stable concepts
└──────────────┬──────────────┘
               ^
┌──────────────┴──────────────┐
│  Conceptual Layer (Domain)  │   ← synthesized abstractions
└──────────────┬──────────────┘
               ^
┌──────────────┴──────────────┐
│   Source Layer (APIs etc.)  │   ← extracted entities/relationships
└─────────────────────────────┘

• Source Layer – raw extractions from APIs, schemas, or databases.
• Conceptual Layer – unified “domain entities” consolidated across sources.
• Canonical Layer – the stable, publishable ontology defining UHDM semantics.

Each layer can be stored independently and version-controlled, making it easy to regenerate derived artefacts such as diagrams, schema exports, or ontology views.

Source Layer — data extraction and normalization

This layer is largely mechanical. For each API (for example Mews or Cloudbeds) we generate a source model that describes its entities, operations, and relationships.

File	Contents	Example
mews.entities.json	extracted entities with attributes and roles	Reservation, Rate, Customer
mews.operations.json	operation metadata	accountNotes/getAll
mews.relationships.json	discovered links	Reservation → Customer

All entities are stored using normalized, human-readable names (for example “Account Notes”) and include:

• type: principal, secondary, or enumeration
• attributes: field names and data types
• operations: endpoints invoking this entity

These outputs are produced automatically by extractor scripts (for example, in Python or TypeScript).

Conceptual Layer — domain synthesis

The conceptual layer consolidates multiple source models into a single abstract model.

Activities at this layer include:

• Mapping equivalent entities across systems (ReservationGroup ≈ Group Booking)
• Defining abstract parent entities (Reservation as a superclass)
• Annotating entities with implementation mappings

Example record:

{
  "entity": "Reservation",
  "description": "A commitment to provide accommodation or service to a guest.",
  "attributes": ["Check-in Date", "Check-out Date", "Guest", "Rate Plan"],
  "relationships": [
    { "to": "Guest", "type": "belongsTo" },
    { "to": "Rate Plan", "type": "uses" }
  ],
  "mappings": {
    "Mews": "Reservation",
    "Cloudbeds": "Booking",
    "Opera": "Resv"
  }
}

This layer captures meaning rather than mechanics — the human understanding of the domain.

Canonical Layer — universal ontology

Once conceptual entities stabilize, they are promoted to the canonical layer, where they gain persistent identifiers, definitions, and cross-references — forming a machine-consumable hospitality ontology.

Example JSON-LD fragment:

{
  "@id": "uhdm:Reservation",
  "@type": "uhdm:Entity",
  "rdfs:label": "Reservation",
  "rdfs:comment": "A confirmed allocation of resources or services to a guest.",
  "uhdm:hasRelationship": [
    { "@id": "uhdm:ReservationGroup" },
    { "@id": "uhdm:RatePlan" }
  ]
}

The canonical layer is the portion intended for reuse and alignment with industry standards such as schema.org/Reservation, OTA, and HTNG.

Data flow and automation

The overall workflow can be summarized as:

[OpenAPI Specs] → [Extractor Scripts]
       ↓
  Source Models (per-API)
       ↓
  Conceptual Model (merging and de-duping)
       ↓
  Canonical Ontology (manual curation + tooling)
       ↓
  Visualization / Exports (Mermaid, UML, JSON-LD)

Each stage can be partially automated, but the transition from Conceptual → Canonical will always depend on expert human judgment.

Outlook

The methodology described here defines how UHDM evolves from real-world APIs toward a formal, interoperable ontology. As tooling matures, portions of this pipeline may be open-sourced to encourage reproducible modeling and community collaboration.

---

Read next: Target PMS APIs