Requirement of custom properties should be forbidden

[adrenallen]

Currently, under the "Adding Custom Properties" section of the standard, custom properties are strongly discouraged. However, there is nothing indicating that a a required custom property would break the standard.

As we've seen in the past via things like EDI, if custom properties are allowed, then they will be used.

In practice, this is important, as there are many unique situations that will need accounted for, and this ensures the standard can still support them. However, per the standard at this time, each implementation could add any number of required custom properties to their endpoints, and still technically follow the standard.

This is a problem, because it allows each implementation to differ enough that the work to integrate becomes one-off work regardless of following the standard or not.

Again, going back to EDI, we see this a lot. And it has led to EDI being a mess of pseudo-standards that might get you 50% of the way to an implementation, but the rest is entirely one-off for that integration partner.

The standards here should aim to avoid that. By adding verbiage that indicates custom properties CANNOT be required for the defined minimum functionality, the standards can better prevent these unique interpretations. Custom properties can still be provided in addition to extend functionality/context, but if an API is hoping to "meet the standard" it cannot be required.

For example, under "best practices", verbiage like this should be changed to indicate customer or facility unique requests would not meet the standard.

However, the SSC strongly discourages any such customizations that vary based on other aspects of the request context, such as
which customer or facility the request is for.

[miller79]

Thanks for your feedback. We have had several conversations about this topic and continue to discuss it to avoid falling into the same cycle that happened to EDI, just like you mentioned. However, making a more decisive decision could impact some pieces of the standard that still need to be fully fleshed out. The most relevant topic is security. Since we have yet to create a strong stance on security, there may be reason for a company to use additional properties. The Security section of the spec explains our recommendations. While the full security standard may take quite some time to be fully fleshed out and agreed upon, specific pieces such as identification may be released over time, which could help to tie in those decisions.

[sorrell]

I think the scope of "Additional Custom Properties", as it stands, is too broad to create meaningful consensus. The distraction of security/headers instead of a clean focus on request/response definitions is allowing the perfect to get in the way of the good.

A meaningful stance would be focusing on the request/response bodies not having REQUIRED custom properties, as @adrenallen proposes. Since security is an ever-evolving landscape, it is doubtful that consensus will ever be achieved here. Further, if a security standard is proposed, and a subsequent breach takes place even though the guideline is followed, will that not discredit the standard?

[adrenallen]

making a more decisive decision could impact some pieces of the standard that still need to be fully fleshed out

If this is true, then I feel the standard may not be "v1". It would be difficult to encourage anyone to build against a standard that cannot make critical decisions about best practice due to it not being complete. What benefits are there for someone to follow this standard over doing it their own way today?

Since we have yet to create a strong stance on security, there may be reason for a company to use additional properties.

The standard doesn't need to make decisions on every piece of an integration, it just needs to make decisions about the minimal functionality for appointment scheduling. This standard could leave security as a "TBD" while still defining clear requirements for the endpoints as it pertains to appointment scheduling. Providing a minimum functionality of endpoint paths, required parameters, the expected output formatting/data, that would be great! That doesn't require a stance on security. As the spec is today, the required parameters and expected output from said parameters is non-standard.

To be clear, I think there is a lot of potential value here. However, these decisions will only become more difficult over time and I fear what happens when a few organizations attempt to follow the standard and find that every integration is still very non-standard. If the purpose of this standard is to reduce overhead for partner integrations then it's crucial these choices are made before anyone builds their integration.

[miller79]

Thanks for the additional details. The primary contingency appears to be the lack of clarity of what is allowable as a "required" parameter and what constitutes a breaking of the standard. Following the principles of RFC6648, we intended to keep the standard evolvable and give implementers some flexibility when gaps are discovered. We elected initially not to include a definitive statement of required fields to prevent exception cases such as security. The critical part for us is to ensure we are not making direct statements with known exceptions and, of course, try to follow existing standards as best as possible. As you have made clear with your comments, without the clarity, potentially harmful practices would be acceptable via the standard as it is currently written, which was not our intent. We hope to start a discussion if a gap is discovered.

I want to expand this discussion as there is a balance that we must uphold as we want the standards to be expandable for all users but make it programmable and clear for the clients who are interacting with multiple companies. Optimally backing the decisions with an RFC or existing standard would be best to make sure the reasons have peer-reviewed reasons to follow. Again, RFC6648 is currently referenced, but more is needed when discussing additional required fields.

To throw out some more thoughts, the definitions of required and optional will need to be defined. An optional field could technically be "required" in specific situations that ultimately cause the same or similar problems.

Thanks for your comments and suggestions. I have shared it with the team, but feedback is always welcome.