Supporting custom / contrib block types

[smn]

Given that the floip spec is a standardisation and interoperability effort, it's safe to assume that the specification will likely trail behind some immediate implementation needs.

What are the proposed conventions, if any, for:

1. Announcing a custom block / extension in a flow specification file
2. Namespacing these custom (contrib?) extensions in the block definitions

Some immediate follow up questions this:

1. Would name spacing block types with Contrib.VendorID.Name suffice?
2. Is a top level key needed to announce these block types, possibly with URLs pointing to their implementation details should others also want to support it?
3. How does one signal contrib deprecation. I'm thining of a scenario when a block, previously only available as a contrib type, is now supported as a standard type. I'm anticipating this for webhooks as an example.

Ideally some of these contrib extensions would then in the future be merged into the spec and gain wider support. What can be done by implementors now to ensure that custom contributions lead to strengthening of future interoperability rather than fragmenting the specification?

[markboots]

Hi @smn , this is really helpful. It definitely aligns with our previous thinking on having a Contrib namespace for blocks.
With the idea that orgs could add their 'suggested' implementations for new blocks in a way that can be used/copied by other orgs with the same needs, you could imagine:

1. Contrib.BlockName: This block isn't part of the required spec, but it's offered by anyone to use/follow if you need that functionality. An example could be: Contrib.AirtimeTransfer. The first org that needs this might create and document it, offering it into the Contrib namespace, but it wouldn't necessarily be exclusive to that vendor for long.
2. Vendor.VendorID.BlockName: Functionality that is anticipated to stay vendor-unique forever: Vendor.IO_TURN.SomethingReallySpecial

Looking for suggestions on the migration process from Contrib to within the standard... It seems tricky if block names would need to change for existing implementations when a block "graduates" to the full spec. Any ideas?

[smn]

We'll likely look at implementing something internally initially to address the webhooks use case and see what emerges from that implementation as a possible way forward. I'll report with our learnings.

[markboots]

Following up on this issue with an implementation proposal... The goals to solve for are:

• A subset of vendors may want to implement additional functionality in a common way, even though this would not be a required part of the specification for all vendors to implement
• A common, open place to document shared functionality and vendor-specific functionality (even if its not required for all vendors) could make it easier to maintain and reference flow documentation, as well as encourage innovation and learning from each other.

Benefits:
Assuming multiple vendors have a need for similar functionality (example: airtime transfers), it improves interoperability to implement this in a common way across the vendors who need this.

Avoiding drawbacks:
If we added all these definitions to the "required" Flow Specification, it makes it harder for vendors to adopt the Flow Standard, since they are pushed to implement more functionality than they need. Therefore, this area of the specification is intended to be optional, presenting a suggested way of implementing functionality if you need it.

Block Functionality

For additional block types, two new namespaces are proposed:

Namespace Contrib:

This namespace isn't part of the required spec, but it's offered by anyone to use/follow if you need that functionality. An example could be: Contrib.AirtimeTransfer. The first vendor that needs this functionality might create and document it, offering it into the Contrib namespace, but it wouldn't necessarily be exclusive to that vendor. Any vendor could make a PR on the Flow Specification repo to add Contrib blocks.

Namespace Vendor:

This namespace is for blocks that are expected to be vendor-unique. They should be namespaced with the VENDOR_ID (ie: Reverse domain name notation, with . replaced by _). For ease of documentation, the Flow Specification repo and documentation website (https://floip.gitbook.io/flow-specification) would welcome vendor additions to the main documentation. Any PR for documentation of Vendor-namespaced blocks would be accepted.

Hypothetical examples:

• Vendor.IO_TURN.SomethingReallySpecial
• Vendor.IO_VIAMO.ConnectToCallCenterApp

Non-block functionality

Vendor-specific additions to areas beyond new Block types could also be approached in the same way, within the config environment for Containers, Flows, and Blocks, for example:

• flow.config.contrib.optional_parameter
• flow.config.vendor.<VENDOR_ID>.vendor_specific_parameter

The Flow Specification repo and documentation website would welcome these additions to the main documentation for transparency, supporting innovation, and to help other vendors identify when they might implement new functionality in a common way.

@smn @arthursarpong @safydy-r , would be great to get your thoughts!

[safydy-r]

Thanks @markboots & @smn for initiating this. Indeed, it would great to provide such contribution process to the community.

1. I agree with @markboots on this:

Looking for suggestions on the migration process from Contrib to within the standard... It seems tricky if block names would need to change for existing implementations when a block "graduates" to the full spec.

I think this would be part of the main challenge to resolve. I have no idea for now, and would love to hear from others here. I'd suggest we even have a sync meeting for brainstorming if needed. Maybe with @seifertk ?

2. @markboots, about contrib proposal under Containers, Flows, and Blocks:
   isn't this the purpose of the existing vendor_metadata ?