About

UBER (Uniform Basis for Exchanging Representations) and HAL (Hypertext Application Language) are two distinct hypermedia formats for REST APIs. UBER uses a recursive data array where each element can represent state, a link, or a templated action. HAL separates concerns into _links, _embedded, and flat state properties. Converting between them is non-trivial: an UBER element with a url property maps to a HAL link object, while an element with child data and no url maps to an embedded resource or a state property depending on context. Incorrect mapping loses navigational affordances or corrupts resource semantics. This tool performs a deterministic structural transformation following the UBER specification (draft-amundsen-uber) and the HAL specification (draft-kelly-json-hal).

Limitations apply. UBER supports action (HTTP method) and model (URI template body) which HAL links do not natively represent. This converter maps action to a non-standard method property on the link object and model sets templated to TRUE. UBER's sending and accepting arrays map to type on the HAL link. Elements with multiple rel values produce one HAL link entry per rel. Pro tip: always validate your output against a HAL validator before integrating into production clients.

Formulas

The UBER-to-HAL transformation is a structural mapping, not a mathematical formula. The conversion follows a decision tree per UBER data element:

{

_links[rel] ← { href: url } if url ≠ NULL_embedded[rel] ← convert(data) if data ≠ NULL ∧ url = NULLresource[name] ← value if value ≠ NULL ∧ url = NULL

Where rel is derived from the element's rel array (first value used as key, or id as fallback). name is the element's id or name property. The convert function is applied recursively to child data arrays producing nested HAL resources. The UBER action vocabulary maps deterministically: read → GET, append → POST, replace → PUT, partial → PATCH, remove → DELETE.

Reference Data

UBER Property	HAL Mapping	Notes
data[].id	Property key or link rel	Used as identifier when rel is absent
data[].rel	_links key	Array of rels; each gets its own link entry
data[].url	_links[rel].href	Presence of url signals a link
data[].action	_links[rel].method	Non-standard HAL extension; values: read, append, replace, remove, partial
data[].model	_links[rel].templated = TRUE	URI template present means templated link
data[].sending	_links[rel].type	First media type used
data[].accepting	_links[rel].type	Fallback if sending absent
data[].value	State property value	Scalar value on the HAL resource
data[].data (children, no url)	_embedded or state object	Nested data without url becomes embedded resource
data[].data (children, with url)	_links entries	Each child with url is a link
UBER version	Discarded	HAL has no version field
UBER error	Top-level error object	Non-standard; preserved as state
UBER action read	HTTP GET	Default when action is omitted
UBER action append	HTTP POST	Create semantics
UBER action replace	HTTP PUT	Full replace semantics
UBER action partial	HTTP PATCH	Partial update semantics
UBER action remove	HTTP DELETE	Delete semantics
rel = self	_links.self	Canonical self link
Multiple rel values	One link per rel	Same href duplicated under each rel key
name property	_links[rel].name	Disambiguation for same-rel links
transclude	Ignored	HAL has no transclude equivalent

Frequently Asked Questions

Each rel value in the UBER element's rel array produces a separate entry in the HAL _links object. The link object (href, method, templated, type, name) is duplicated under each rel key. This preserves the full navigational semantics since HAL uses rel strings as keys in the _links map.

The UBER action property is mapped to a non-standard method field on the HAL link object using the mapping: read → GET, append → POST, replace → PUT, partial → PATCH, remove → DELETE. The model property (indicating a URI template body) sets templated to true on the link. These are common HAL extensions used in practice but are not part of the core HAL specification (draft-kelly-json-hal-08).

An UBER data element that has child data elements but no url is treated as an embedded resource. It is placed under _embedded in the parent HAL resource, keyed by its rel (or id as fallback). The child data array is then recursively converted into a full HAL resource with its own _links, _embedded, and state properties. If the element has only a value and no children or url, it becomes a flat state property on the parent resource.

Yes. If the UBER document contains an error object at the top level, it is mapped to a top-level error property in the HAL output containing the error's data elements converted as state properties. HAL has no standard error representation, so this is a best-effort preservation of the error metadata.

The output conforms to the HAL+JSON structure expected by standard HAL parsers. The _links and _embedded sections follow the specification. Non-standard extensions (method, templated on non-templated links) are ignored by strict parsers but utilized by lenient ones. Validate the output with a HAL linter if your client enforces strict compliance.

The presence of the url property is the discriminator. If url exists, the element is a link and goes into _links. If url is absent but value exists and there are no child data elements, it is a state property. If url is absent but child data elements exist, it becomes an _embedded resource. This follows the UBER specification's semantic intent where url signals navigational affordance.