# TR-09-2 Booking Tags

- **Name:**  urn:x-vsf:tag:tr-09-2:booking-list/v1.0
  - **Description:** Booking List tag that can be used to indicate that an NMOS resource is part of one or more TR-09-2 bookings.
  - **Proponent:** [VSF](https://www.vsf.tv/)

- **Name:**  urn:x-vsf:tag:tr-09-2:current-booking/v1.0
  - **Description:** Current Booking tag that can be used to indicate the current active TR-09-2 booking.
  - **Proponent:** [VSF](https://www.vsf.tv/)

This document describes an application of the AMWA IS-04 `tags` structures to enable control systems to identify NMOS resources that are being shared across a facility boundary as described in the VSF TR-09-2 specification.

## Introduction

The aim of the TR-09-2 booking tags is to facilitate the sharing of NMOS resources between two independent media facilities.

The tags contain information that allows an NMOS resource to be identified and matched to information defined during an earlier booking process.

This booking process takes place between the facility offering the shared resource and the facility consuming the shared resource, as defined in the VSF TR-09-2 specification document.

Two TR-09-2 tags are defined: the `booking-list` tag and the `current-booking` tag.

When an NMOS resource is to be shared with another facility, the facility offering the shared resource MUST include these tags in the JSON of the NMOS resource at the point it is made available at the facility edge.

## Booking List URN

The booking list URN `urn:x-vsf:tag:tr-09-2:booking-list/v1.0` defines a list of bookings associated with the shared NMOS resource. It is defined by an array containing a list of one or more bookings.

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
      "<consumer-id>:<booking-id>:<element-id>[:<label>]"
   ]
}
```

Where `<`...`>` indicates a named parameter and `[`...`]` indicates an optional component of the string.
Several examples are given below.

| Parameter | Description | Values |
| --------- | ----------- | ------ |
| `consumer-id` | A unique identifier for the receiving facility | `^[-_a-z0-9]{1,64}$` (lower case alphanumeric, hyphen and underscore) |
| `booking-id` | A unique identifier for the booking | `^[-_a-z0-9]{1,64}$` (lower case alphanumeric, hyphen and underscore) |
| `element-id` | A unique identifier for the resource within the booking | `^[-_a-z0-9]{1,64}$` (lower case alphanumeric, hyphen and underscore) |
| `label` | A user-friendly label for the resource within the booking | `^[^:]{1,128}$` (any string not containing `:`) |

The colon character, `:`, is reserved and MUST NOT be used in any of the parameters listed.

As defined in the VSF TR-09-2 specification:
- The `consumer-id` and `element-id` MUST be provided by the facility *offering* the shared resource.
- The `booking-id` MUST be provided by the facility *consuming* the shared resource.
- The optional `label` SHOULD be provided by the facility *consuming* the shared resource.
- The `element-id` MUST be unique within a booking (as identified by `<consumer-id>:<booking-id>`).
- The `element-id` SHOULD NOT be the same as the NMOS UUID associated with the resource (from the resource's `id` field).
- The same `element-id` MAY be used for a given resource across multiple bookings.

## Current Booking URN

The current booking URN `urn:x-vsf:tag:tr-09-2:current-booking/v1.0` defines the currently active booking for the shared NMOS resource.

If one of the bookings described in the booking list is active then the list MUST contain a single entry identifying the active booking. Otherwise, the list MUST be empty.

When the current booking ends, it MUST be removed from the current booking URN. Unless it is to be used again, it SHOULD also be removed from the booking list.

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
      "<consumer-id>:<booking-id>"
   ]
}
```

Where

| Parameter | Description | Values |
| --------- | ----------- | ------ |
| `consumer-id` | The `consumer-id` parameter associated with the currently active booking | `^[-_a-z0-9]{1,64}$` (lower case alphanumeric, hyphen and underscore) |
| `booking-id` | The `booking-id` parameter associated with the currently active booking | `^[-_a-z0-9]{1,64}$` (lower case alphanumeric, hyphen and underscore) |

The `consumer-id` and `booking-id` MUST originate from the same entry in the booking list.

## Examples

### 1. NMOS Sender representing a camera with one booking which is currently active

JSON tags for Sender resource

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
      "consumer_a:booking0001:camera-1:Main Camera"
   ],
   "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
      "consumer_a:booking0001"
   ]
}
```

### 2. NMOS Sender representing a camera with multiple associated bookings, the second of which is currently active

JSON tags for Sender resource

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
      "consumer_a:booking0001:camera-1:Main Camera",
      "consumer_a:booking0002:camera-studio:Studio Camera",
      "consumer_a:booking0003:camera-2"
   ],
   "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
      "consumer_a:booking0002"
   ]
}
```

### 3. NMOS Sender representing a camera with multiple associated bookings where the element-id and label are the same across all bookings and the second booking is currently active

JSON tags for Sender resource

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
      "consumer_a:booking0001:camera-1:Main Camera",
      "consumer_a:booking0002:camera-1:Main Camera",
      "consumer_a:booking0003:camera-1:Main Camera"
   ],
   "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
      "consumer_a:booking0002"
   ]
}
```

### 4. NMOS Sender representing a camera with multiple associated bookings, none of which is currently active

JSON tags for Sender resource

```json
"tags": {
   "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
      "consumer_a:booking0001:camera-1:Main Camera",
      "consumer_a:booking0002:camera-1:Main Camera",
      "consumer_a:booking0003:camera-1:Main Camera"
   ],
   "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
   ]
}
```

## NMOS resource JSON samples

Sender with tags from example 2 above

```json
{
   "format": "urn:x-nmos:format:video",
   "caps": {},
   "device_id": "8570e409-eb39-4c28-b083-fb2be5d44abe",
   "transport": "urn:x-nmos:transport:rtp.ucast",
   "interface_bindings": [],
   "subscription": {
      "sender_id": null,
      "active": true
   },
   "id": "51e6b7ef-7061-4121-b8d3-426527d3ac4f",
   "version": "1525121173:668000000",
   "label": "H200-11B Camera",
   "description": "High definition broadcast camera",
   "tags": {
      "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
         "consumer_a:booking0001:camera-1:Main Camera",
         "consumer_a:booking0002:camera-studio:Studio Camera",
         "consumer_a:booking0003:camera-2"
      ],
      "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
         "consumer_a:booking0002"
      ]
   }
}
```

A second Sender that is part of the same active booking but has no other bookings

```json
{
   "format": "urn:x-nmos:format:video",
   "caps": {},
   "device_id": "8570e409-eb39-4c28-b083-fb2be5d44abe",
   "transport": "urn:x-nmos:transport:rtp.ucast",
   "interface_bindings": [],
   "subscription": {
      "sender_id": null,
      "active": true
   },
   "id": "1b990a6b-5cf4-4639-8e50-c6055182b149",
   "version": "1525121173:668000000",
   "label": "H200-11B Camera",
   "description": "High definition broadcast camera",
   "tags": {
      "urn:x-vsf:tag:tr-09-2:booking-list/v1.0": [
         "consumer_a:booking0002:camera-3:Reserve Camera"
      ],
      "urn:x-vsf:tag:tr-09-2:current-booking/v1.0": [
         "consumer_a:booking0002"
      ]
   }
}
```
