Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
1 parent
b6cf2d9
commit 2698347