# Response format (Hydra/JSON-LD)

Every response from the Korus Ticket API uses **JSON-LD** with the **Hydra** vocabulary. If you have not worked with
this format before, this page explains the conventions you will encounter in every API response.

## What is JSON-LD?

JSON-LD is a standard way of giving JSON properties unambiguous meaning by linking them to a shared vocabulary. In
practice, it adds a small number of `@`-prefixed keys alongside your regular data fields. You do not need to process
these keys — they exist for semantic interoperability — but it helps to know what they mean.

The Hydra vocabulary (`http://www.w3.org/ns/hydra/core#`) extends JSON-LD with collection and pagination concepts.

## Common fields on every resource

| Field | Description |
|  --- | --- |
| `@context` | URL or inline object that defines the meaning of each property in the response. |
| `@id` | The canonical IRI (URL path) that uniquely identifies this resource. Use this as the value whenever the API asks for an IRI. |
| `@type` | The type name of the resource (e.g. `BookingOrder`, `TicketingCatalog`). |


### Example — single resource

```json
{
  "@context": "/contexts/BookingOrder",
  "@id": "/v1/booking/orders/0194b132-448c-7d1b-bb13-f8e09ae5c18f",
  "@type": "BookingOrder",
  "id": "0194b132-448c-7d1b-bb13-f8e09ae5c18f",
  "reference": "KT-ORD-6799E80128885",
  "status": "confirmed"
}
```

The `@id` and the `id` fields both identify the same resource. The `@id` is the full IRI path; `id` is the bare UUID.
When another resource references this order (for example as part of a reservation), it will use the `@id` value
(`/v1/booking/orders/0194b132-448c-7d1b-bb13-f8e09ae5c18f`) rather than the bare UUID.

## Collection responses

When an endpoint returns a list of resources, the response wraps them in a **Hydra collection envelope**.

| Field | Description |
|  --- | --- |
| `@type` | Always `Collection` for list responses. |
| `member` | Array of resource objects. This is the list you iterate over. |
| `totalItems` | Total number of items matching the query, across all pages. |
| `view` | Pagination links — see [Pagination](/using-the-api/pagination). |
| `search` | Optional IRI template describing available filter parameters. |


### Example — collection response

```json
{
  "@context": "/contexts/TicketingCatalog",
  "@id": "/v1/ticketing/catalogs",
  "@type": "Collection",
  "totalItems": 2,
  "member": [
    {
      "@id": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e",
      "@type": "TicketingCatalog",
      "id": "0194abdc-3a71-72b0-a9b9-89d4be0cd73e",
      "name": "OL Tickets"
    },
    {
      "@id": "/v1/ticketing/catalogs/0194b200-1234-7abc-def0-112233445566",
      "@type": "TicketingCatalog",
      "id": "0194b200-1234-7abc-def0-112233445566",
      "name": "Puy du Fou"
    }
  ],
  "view": {
    "@id": "/v1/ticketing/catalogs?page=1",
    "@type": "PartialCollectionView",
    "first": "/v1/ticketing/catalogs?page=1",
    "last": "/v1/ticketing/catalogs?page=1",
    "previous": null,
    "next": null
  }
}
```

Your code should always read from the `member` array, not from the top-level object.

## IRIs as references

Resources reference each other using their `@id` IRI rather than embedding the full object. For example, an offer
references its product like this:

```json
{
  "product": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/products/0194abfe-1c04-7ade-9bc3-dbcfefb12652"
}
```

When the API asks you to pass a reference to a resource — for instance, an offer IRI when creating a reservation — use
this full path string directly:

```json
{
  "offer": "/v1/ticketing/catalogs/0194abdc-3a71-72b0-a9b9-89d4be0cd73e/offers/0194ac40-fda7-78c1-8fcb-26fc2df25894"
}
```

## Blank nodes

Some embedded objects (such as `ReservationItem` or `OrderCustomer`) do not have a stable IRI of their own. Instead,
their `@id` starts with `/.well-known/genid/`. These are called **blank nodes**. You can read their properties normally
but you should not store or use the `/.well-known/genid/` IRI as a stable identifier.

```json
{
  "@type": "OrderCustomer",
  "@id": "/.well-known/genid/659ea7d58fe6d29dcf2e",
  "firstname": "John",
  "lastname": "Doe"
}
```