Compliance definition

[kkuo]

Wanted to start a thread on defining and communicating compliance so we're all aligned.

Compliance:

• If TMS removed/renamed any parts of the SSC spec, they are not in compliance
• If TMS added fields or used some sort of extension mechanism we define (approaches 1 and 2 in our meeting). They are in compliance with an asterisk.

Feature sets:

• Instead of having APIs that returns a TMS's capabilities, the TMS will publish their own API specs which documents the features from the SSC they support (I think this is implicit but just want to write it out here).
• All TMSs must be able to demonstrate the critical flows that @GranataJBH provided as a starting point can be accomplished by their subset of features. We may have to do some work here to come up with more intricate flows so the TMS can say we support flows 1.a, but not 2.b, etc, where 1.a is RPC fetch+book and 2.b is RPC fetch but getting the data back async.
• From the flows the TMS support we can assign a score. Like 4/15 flows is basic. 8/15 is great. 12/15 is outstanding, etc
• A few flows should be marked as required.
• A TMS is in compliance if they meet the criteria in compliance section and they have implemented the required flows.

We can then work with TMSs on increasing their feature set score and their compliance scores over time.

[kkuo]

Adding comment from @GranataJBH

Following up on some of the actions from last week's meeting, my plan is to kick off a discussion in the beta GitHub with the below. Want to get your feedback before making the post. From there, we can start @'ing folks to weigh in. "Starting a discussion to work through what rules we would like to establish around the customization of the SSC API(s). Ultimately, our goal is to provide an API that has a common experience across providers, but acknowledge there will be instances where a TMS may want to customize the experience to a degree in order to meet certain pre-existing conditions. As such, we'd like to propose these general rules that, if others agree, we will continue to refine with additional detail and include as a part of the Standard. General rules for customization: A TMS may make changes to the API Header for both required and optional information and still be considered compliant with the Standard. A TMS may make changes to the API request/response body for optional information and still be considered compliant with the Standard. If a TMS makes changes to the API request/response body with required information, a TMS would be considered non-compliant with the Standard."

[kkuo]

Summarizing some conversation over slack on why we can't realistically force TMSs to implement the request and response bodies faithfully and only consider those who did to be in compliance.

1. Data fragmentation. We haven't specified even with a consistent schema how TMS should return data and how carriers should interpret that data. ReasonCodes are raw strings. TMS could require carriers to parse it for some information and still be 100% schema compliant. TMS could return unsorted and duplicate appointment results yet another TMS may doing that filtering for you. So clients may have to special case their implementation anyway.
2. Capability fragmentation. There are a lot of ways to return results using webhooks, callbacks, etc. We haven't defined which capabilities are required. So each carrier will have to implement only the supported capabilities for each TMS.
3. Header and security fragmentation. We acknowledge auth mechanisms are likely different for each TMS so carriers will have to make unique implementations for each TMS anyway. Headers is basically entirely open for extension and augmentation. If we lock down the schema we may end up having TMSs abuse the headers just to be "compliant"
4. You don't know what you don't know. It's different from evaluating a spec vs actually implementing one. If a use case was later discovered to require extra fields in the spec, if we locked it down, the TMS will have to a) abandon, or b) misuse the header to be compliant, c) do their own thing. The SSC and the industry have nothing to gain from a or b and it's not due to TMS's intentionally trying be a bad actor. Sometimes these things just happen.

There is very little to gain and a lot more downsides to force request and response compliances if we also ignore points 1-4 from above.

[kkuo]

Action item: add language saying request body/response extensions by TMS are not guaranteed to be supported in future spec revisions.