support loadingType as a top level field on the commonIdentifiers (#25)

# Summary

**This PR addresses Issue #14: `Provide a way to show/provide Additional
Appointment Details`**

The specification includes a framework for [adding custom
properties](https://freightapis.github.io/ssc/#section/Adding-Custom-Properties):

> For the best integration experience for all parties, the SSC
encourages the use of the API specification as-is. However, implementers
may have specific requirements which may necessitate the addition of
custom properties to the specification.

However, multiple organizations have signaled the `loadingType` will be
necessary. Since it is required for multiple organizations we can
consider adding it to the specification rather than following the above
guidelines for adding custom properties. This allows for the
`loadingType` to be well defined while eliminating the need for a future
proof vehicle for changes.

# Proposed Changes

1. `loadingType` is optional when fetching available appointments
2. `loadingType` is returned as part of the fetch available appointment
response
3. `loadingType` is required when booking an appointment

# Discussion

PR #17 is another possible solution to Issue #14. Below is some
commentary comparing this PR to #17 as well as stating how this PR meets
some requirements mentioned in the comments of Issue #14.

### Simplicity
Adding well defined fields may be simpler than using
`appointmentOptions`.

Adding the `loadingType` to the `commonIdentifiers` object makes
`loadingType` an integral part of fetching and scheduling appointments.
It is clear which `loadingType` the client needs, reducing the number of
responses when fetching appointments - only appointments that fit the
specified `loadingType` will be returned.

This also eliminates the need for client side filtering. If
`appointmentOptions` is expanded to accommodate other use cases,
excessive client side filtering may be required to find appointments
that are a good fit.

### Maintainability
Adding well defined fields may be more maintainable than
`appointmentOptions`.

```yaml    
    appointmentOptions:
      description: Options available for a specific appointment
      type: array
      items:
        anyOf:
          - $ref: '#/components/schemas/appointmentOptionLoadingType'
          - $ref: '#/components/schemas/appointmentOption'
```

The `appointmentOptions` provides specific guidelines regarding
`appointmentOptionLoadingType` while leaving the `appointmentOption`
open for future expansion. Will a future `appointmentOption` be added to
the specification? If not, `appointmentOption` could see overlap and
overuse if not formally defined as `appointmentOptionLoadingType` has
been. An open ended property bag may be harder for clients to maintain.

### Meeting Requirements

1. The solution should be as future proof as possible
2. The solution should handle clients who do not know which loading
types are available
3. The solution should handle appointments that are available for both
LIVE and DROP

#### The solution should be as future proof as possible
This PR offers no framework for future proofing the specification.
Adding a new field to the specification is an object change, requiring
clients to update, rebuild, or regenerate their object to capture the
new field. Yet this is no more effort than recognizing a new
`appointmentOption`. Adding new data to one's implementation via the
`appointmentOption` is still a breaking change because failure to read
and evaluate the new `option` may cause the client to book unsuitable
appointments.

#### The solution should handle clients who do not know which loading
types are available
`loadingType` will be optional in `commonIdentifiers`. This allows
clients to receive all available supported loading types if left blank
in the request to fetch appointments.

#### The solution should handle appointments that are available for both
LIVE and DROP
Some appointments may be available for multiple `loadingTypes`, such as
a 2PM appointment available for both `LIVE` and `DROP`. Instead of
making `loadingType` an `array`, the appointment can be duplicated like
so
```json
{
    "status": "SUCCESS",
    "appointments": [
        {
            "id": "1",
            "appointmentType": "AUTOMATIC",
            "arrivalWindow": {
                "startDateTime": "2023-04-15T14:00:00.000-05:00",
                "duration": "PT1H"
            },
            "loadingType": "LIVE"
        },
        {
            "id": "2",
            "appointmentType": "AUTOMATIC",
            "arrivalWindow": {
                "startDateTime": "2023-04-15T14:00:00.000-05:00",
                "duration": "PT1H"
            },
            "loadingType": "DROP"
        }
    ]
}
```

`Note`: Denormalization can cause the number or responses to balloon as
the size of the result set grows with both the number of fields and the
number of options for each field. Clients should consider specifying as
much as possible in the request body to make sure each available
appointment returned is relevant.

Author: MaxMcCarthy

openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: 'Appointments'
-  version: '1.0.1'
+  version: '1.1.0'
   contact:
     name: Scheduling Standards Consortium
     url: https://github.com/freightapis/ssc
@@ -726,6 +726,7 @@ paths:
                       arrivalWindow:
                         startDateTime: '2023-04-15T12:00:00.000-05:00'
                         duration: 'PT1H'
+                      loadingType: 'LIVE'
                     appointmentConfirmationNumber: 'C1234'
                     appointmentStatus: 'CONFIRMED'
                 failure:
@@ -988,6 +989,7 @@ webhooks:
                       arrivalWindow:
                         startDateTime: '2023-04-15T12:00:00.000-05:00'
                         duration: 'PT1H'
+                      loadingType: 'LIVE'
                     appointmentStatus: 'CONFIRMED'
                   occurredAt: '2023-04-15T08:02:23.123Z'
       responses:
@@ -1047,6 +1049,7 @@ webhooks:
                       arrivalWindow:
                         startDateTime: '2023-04-15T12:00:00.000-05:00'
                         duration: 'PT1H'
+                      loadingType: 'LIVE'
                   identifiers:
                     requestIdentifier: 'R1234'
                   occurredAt: '2023-04-15T08:02:23.123Z'
@@ -1078,6 +1081,7 @@ components:
             arrivalWindow:
               startDateTime: '2023-04-15T12:00:00.000-05:00'
               duration: 'PT1H'
+            loadingType: 'LIVE'
     modifiedAppointmentRequest:
       summary: Minimum Required
       description: This example is the bare minimum required to schedule/reschedule an appointment
@@ -1087,6 +1091,7 @@ components:
           stopSequenceNumber: 1
         preferredAppointment:
           id: '1234'
+          loadingType: 'LIVE'
     modifiedAppointmentResponseSuccess:
       summary: Success
       description: Example of a success response
@@ -1181,6 +1186,14 @@ components:
         - DEFERRED
         - FCFS
         - CARRIER_CONFIRMATION_REQUIRED
+    loadingType:
+      type: string
+      description: |
+        - LIVE - Live load appointment
+        - DROP - Drop appointment
+      enum:
+        - LIVE
+        - DROP
 
     # --- Core Entity Schemas --- #
     clientRequestedAppointment:
@@ -1195,6 +1208,8 @@ components:
               $ref: '#/components/schemas/availableAppointmentIdString'
             appointmentType:
               $ref: '#/components/schemas/appointmentType'
+            loadingType:
+              $ref: '#/components/schemas/loadingType' 
         - type: object
           title: Appointment Details
           description: The appointment details requested by the client
@@ -1209,6 +1224,8 @@ components:
               $ref: '#/components/schemas/dockGroup'
             dockDoor:
               $ref: '#/components/schemas/dockDoor'
+            loadingType:
+              $ref: '#/components/schemas/loadingType'              
     availableAppointment:
       type: object
       title: Available Appointment
@@ -1224,6 +1241,8 @@ components:
           $ref: '#/components/schemas/dockGroup'
         dockDoor:
           $ref: '#/components/schemas/dockDoor'
+        loadingType:
+          $ref: '#/components/schemas/loadingType'
     appointment:
       type: object
       title: Appointment
@@ -1237,6 +1256,8 @@ components:
           $ref: '#/components/schemas/dockGroup'
         dockDoor:
           $ref: '#/components/schemas/dockDoor'
+        loadingType:
+          $ref: '#/components/schemas/loadingType'
     appointmentArrivalWindow:
       type: object
       description: The window of time that a carrier is allowed to arrive for the appointment. Specified by a start time and the duration of the arrival window.