Describe how a HAL document (media type application/hal+json) is laid out. What do the reserved _links and _embedded properties hold, and what problem does _embedded solve?

## The model HAL (Hypertext Application Language) defines just enough structure to make JSON linkable. A HAL document is a **resource object**: its own state as ordinary JSON members, plus two reserved members whose names begin with an underscore. **_links** - an object whose keys are link relation names and whose values are link objects (or arrays of them). A link object requires href and may carry: - templated: true when href is a URI template that must be expanded before use - type: a hint at the media type of the target - name: a secondary key used to disambiguate multiple links sharing a relation - title: human-readable label - deprecation: a URL explaining that this link is going away **_embedded** - an object whose keys are, again, relation names, and whose values are resource objects or arrays of them. Each embedded resource is a full HAL resource with its own _links and possibly its own _embedded, so documents nest. ## What _embedded is for Without embedding, a collection of a hundred orders is a hundred links and a hundred round trips. _embedded lets the server ship the representations it already has in hand. The relation name says what the embedded things are to the parent (item, author, related), exactly as a link would. Two consequences follow. First, an embedded resource may legitimately be a partial representation - the server may include only the fields worth listing - so clients that need everything follow the embedded resource's own self link. Second, embedding is a caching decision: an embedded copy is frozen inside the parent's cache entry, so highly volatile or independently cacheable sub-resources are often better left as links. ## Single versus array: the classic bug HAL permits a relation's value to be either one object or an array. A collection with one member can serialise as an object and with two as an array, and naive client code that iterates unconditionally breaks at exactly one item. Real clients normalise on read; some servers pin the choice per relation and document it. Expect this as a follow-up question. ## Custom relations and curies Extension relation names are URIs, which is verbose to repeat. HAL provides curies: a reserved link relation holding an array of templated links with name and href, letting documents write ex:approve instead of https://example.com/rels/approve. The client expands the prefix using the curie template to recover the full URI. Curies are a compression device for rel names; they change nothing semantically. ## What HAL does not do HAL has no actions, no methods, no field descriptions. A cancel link tells the client the URL, not that it should POST an empty body. Formats such as Siren, or the HAL-FORMS extension with its _templates member, exist to fill that gap. HAL also imposes no conventions for pagination, filtering, or errors - you layer those on yourself. ## Implementation shape Spring HATEOAS is a common concrete example: RepresentationModel carries the links, EntityModel wraps a payload object, CollectionModel wraps a list, Link and WebMvcLinkBuilder build hrefs from controller methods so they cannot drift from the routing table, and enabling the HAL hypermedia type makes the serializer emit _links and _embedded. That last point is the real value - links derived from the routes rather than string-concatenated.