Documentation · HOS Core
HOS Core 0.1
The operational minimum that makes the first arrival-readiness scenario portable: nine entities, opaque identifiers, typed external references, a four-dimension Unit status model, and extensions that can never corrupt the Core.
Draft for review.
Names and fields may change before 0.1 is final. The specification text is published under CC BY 4.0; schemas are Apache-2.0 (see licensing). Every example is synthetic. Comments and counter-proposals are welcome through the technical contributor path.
Scope
What Core 0.1 covers, and what it deliberately leaves out.
Nine entities, identifiers and external references, the Unit status model, time rules, sensitivity classes and extensions. Facts about them are specified in HOS Events 0.1.
Commands in 0.2, policies and audit in 0.3, agent manifests in 0.4, certification. They open only when the evidence supports them.
No database, cloud, language or broker is prescribed. Authority stays with the system of record. Data is minimal and pseudonymous.
Core entities
Nine entities, each with a narrow meaning and a clear boundary.
| Entity | Minimum HOS 0.1 data | Boundary | Required fields |
|---|---|---|---|
| Tenant | Security, policy and data-autonomy boundary. | A Property belongs to one Tenant at a time. | tenant_id |
| Property | Tenant, IANA time zone, country, business-date policy and standard check-in and check-out times. | Establishment-level operating context. | property_id, tenant_id, timezone, country, business_date_policy |
| Unit | Property, local label or type, and four independent statuses. | A room is a local type or label of Unit. | unit_id, property_id, statuses |
| Maintenance window | A planned period when a Unit is out of service or cannot be sold: a repair, a renovation or internal use. Its statuses say which dimensions it affects. | A plan. What holds now is the Unit's maintenance and commercial status. | maintenance_id, property_id, unit_id, starts_at, ends_at, statuses |
| Reservation | Property, commercial status, planned arrival and departure, and external references. | Commercial commitment; it can yield zero, one or many Stays. | reservation_id, property_id, status, planned_arrival_date, planned_departure_date |
| Stay | Property, linked Reservation, planned and actual times, and Unit assignment history. A reservation for several units yields one Stay per unit. | Operational execution of a visit. | stay_id, property_id, reservation_id, status, planned_arrival_at, planned_departure_at, unit_assignments |
| Task | Linked Property, Unit or Stay; type, status and priority. | Minimal operational work item. | task_id, property_id, task_type, status, priority |
| Guest | Pseudonymous HOS identifiers and external references only. A producer without a stable guest identity publishes no guest_id, and never derives one from names or contact details. | No mandatory global person identity. | guest_id |
| Message | Channel, direction, time, linked Guest or Stay, and sensitivity class. | Message content is excluded from Core. | message_id, property_id, channel, direction, sent_at, sensitivity |
Identifiers and references
Opaque inside HOS, typed and sourced outside it.
Opaque identifiers
Opaque, stable HOS identifier, unique within its Tenant. It carries no business meaning and no personal data.
External references
A vendor identifier travels as a typed reference: the source system, the identifier type, the source identifier and, where known, whether it was verified with the source.
Guest identity
HOS issues no global person identity. Matching two guest references creates a reversible link that names its source, confidence, author and rationale; records are linked, never merged. A producer without a stable guest identity publishes no guest_id and never derives one from names or contact details.
Unit status model
A unit has four independent statuses, not one ambiguous availability.
Each dimension is normalized and changes on its own; every one of them can be unknown. Vendor detail stays in extensions.
| Dimension | Core values | Meaning |
|---|---|---|
| occupancy | vacant / occupied / unknown | Physical occupancy state. |
| housekeeping | dirty / clean / inspected / unknown | Readiness as reported by the housekeeping authority. |
| maintenance | operational / out_of_service / unknown | Basic operational availability; there is no detailed maintenance model in 0.1. |
| commercial | sellable / not_sellable / unknown | Commercial disposition as declared by the responsible system. |
{
"unit_id": "unit_204",
"property_id": "prop_demo",
"label": "204",
"unit_type": "double_room",
"statuses": {
"occupancy": "vacant",
"housekeeping": "inspected",
"maintenance": "operational",
"commercial": "sellable"
},
"external_refs": [
{
"source_system": "urn:hos:pms:demo",
"id_type": "room_number",
"source_id": "204",
"verification": "verified"
}
]
}Time, extensions and sensitivity
No ambiguous local time, no redefined Core field.
Time
Occurrence and recording times use RFC 3339. The Property declares an IANA time zone, a business-date policy and the standard check-in and check-out times that turn stays planned in days into instants. The business date is explicit whenever it matters.
Extensions
Vendor detail under an inverted domain namespace such as com.example. Each namespace publishes its own schema and documentation, and can never redefine a Core field or enum.
Sensitivity classes
Handling class. public: no restriction; internal: operational data for authorised participants; confidential: commercial or pseudonymous personal data; restricted: data whose disclosure could harm a person, such as special-category data.