search

openservicebrokerapi / servicebroker

Open Service Broker API Specification
https://openservicebrokerapi.org/
Apache License 2.0
1.2k stars 435 forks source link

Service broker can declare supported schema for parameters field #59

Closed bmelville closed 7 years ago

bmelville commented 8 years ago

Service broker will provide schema information for both service instances and bindings for each plan. The schema information is for both parameter inputs and output properties. Currently the proposal is that the schema format will be JSON schema v4.

Proposal: https://docs.google.com/document/d/1-IKI-PwPnhtbK0su1UzWA_UoyaCjL8S2d6ky3Xmuwvg/edit?usp=sharing

shalako commented 8 years ago

This issue seems more appropriate for the Kubernetes service-catalog project. The openservicebrokerapi org is not meant for development of platform controllers.

bmelville commented 8 years ago

@shalako the intention of this issue is for the parameter schema PR. I've renamed to make it more appropriate.

bmelville commented 7 years ago

Proposal doc: https://docs.google.com/document/d/1-IKI-PwPnhtbK0su1UzWA_UoyaCjL8S2d6ky3Xmuwvg/edit?usp=sharing

shalako commented 7 years ago

@avade I know you're planning to draft a proposal for the CF community for this feature. You may want to consider Brendan's existing google doc; link to it and dedup or duplicate the content in yours? I expect going forward we'll have to have a design proposal for the API and another for CF changes.

avade commented 7 years ago

I had already lifted much of the content form Brendan's doc :)

Brendan are you going to update the proposed API spec part of this doc or sharing more as an example?

If this is going to be "the" proosal doc for this feature, can I get rights to suggest edits, please?

bmelville commented 7 years ago

Hey Alex,

The API spec part was more an example section, but I'm happy to make this more the canonical doc if you'd like. I believe that you can suggest edits if you have comment rights by switching to suggest mode. If not I can give you edit rights.

B.

On Tue, Nov 29, 2016 at 11:40 AM, Alex Ley notifications@github.com wrote:

I had already lifted much of the content form Brendan's doc :)

Brendan are you going to update the proposed API spec part of this doc or sharing more as an example?

If this is going to be "the" proosal doc for this feature, can I get rights to suggest edits, please?

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/openservicebrokerapi/servicebroker/issues/59#issuecomment-263675904, or mute the thread https://github.com/notifications/unsubscribe-auth/AKwU8r_gzpQAj5w7o34U5k1hEWU42AgOks5rDH-fgaJpZM4JqRle .

avade commented 7 years ago

I have had a read through the comments and found it difficult to work out the state of the discussion.

Perhaps @bmelville / @gberche-orange could provide a summary and what needs to happen before we can accept the proposal and get started on a Cloud Foundry implementation.

gberche-orange commented 7 years ago

To my understanding, the core specification needs a decision on where schemas should be attached at :

The JSON schema extensions (x-serviceBroker-updatable, x-servicebroker-supported-in-verbs, or x-servicebroker-confidential, x-servicebroker-displayType, x-servicebroker-service-instance-required-types, x-servicebroker-service-instance-required-tags ) seem less mature and needs more explorations of the use-cases to support.

The core specifications (a.k.a. without schema extension) could a good candidate for a 2.12 feature with an experimental status. This would enable to start getting feedback from prototype implementations in CF such as:

Based on feedbacks from such prototypes, decisions could be taken on

bmelville commented 7 years ago

I think that's a great overview from Guillaume. The remaining work item is the decision on where to hang schemas, and there will likely be more to flush out, especially around the new Broker Actions proposal.

I think we have landed on method-level schemas, but it seems like there is definitely room for a lot of exploration and understanding of use-cases.

On Thu, Dec 15, 2016 at 1:30 PM, Guillaume Berche notifications@github.com wrote:

To my understanding, the core specification needs a decision on where schemas should be attached at :

  • object level (service instance, service binding) to the expense of restricting some fields only to some verbs: create/update/delete/actions)
  • method level (provision, bind, update, delete, actions) to the expense of duplicating field definitions for the ones common between verbs, such as create and update

The JSON schema extensions (x-serviceBroker-updatable, x-servicebroker-supported-in-verbs, or x-servicebroker-confidential, x-servicebroker-displayType, x-servicebroker-service- instance-required-types, x-servicebroker-service-instance-required-tags ) seem less mature and needs more explorations of the use-cases to support.

The core specifications (a.k.a. without schema extension) could a good candidate for a 2.12 feature with an experimental status. This would enable to start getting feedback from prototype implementations in CF such as:

  • the CF CLI (distributed as a plugin) that would perform
    • arbitrary params validation
    • arbitrary params prompting (even if this is not currently the direction adopted by the CLI team /CC @dkoper https://github.com/dkoper)
    • arbitrary params completions
  • generic service brokers (similar to pivotal's on-demand-broker) leveraging the schema to validate arbitrary params
  • CC validating the schema

Based on feedbacks from such prototype, decisions could be taken on

  • whether to remove the experimental status on core schema specs or amend them
  • which schema extensions to add to fullfill the missing use-cases

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openservicebrokerapi/servicebroker/issues/59#issuecomment-267449723, or mute the thread https://github.com/notifications/unsubscribe-auth/AKwU8qnDJGQQq3Orkr_Cn82QpyPd6jX9ks5rIbFsgaJpZM4JqRle .

bmelville commented 7 years ago

Hey folks,

I have updated the proposal with the method-based schema approach, and have also added a section on extensions (outside the scope of this but worth discussing a bit since there have been so many questions).

Please take another look when you have a chance.

B.

shalako commented 7 years ago

I've read the new proposal. Looks good.

gberche-orange commented 7 years ago

The "plan-attached schemasets" concepts were reviewed during the Feb 02, 2017 design session. The proposal has been updated with details, comparison table updated, along with other proposal archived for reference.

Feedback is welcome.

Next steps one feedback is collected would be:

mattmcneeney commented 7 years ago

Hi all,

As discussed in the calls earlier this week, we've made some provisional spec changes for two of the proposals:

  1. Proposal 5: Service-level schema-sets Proposal document Provisional spec

  2. Proposal 2: Method-attached schemas Proposal document Provisional spec

Feedback welcome. We discussed creating spike implementations for both of the above proposals in Cloud Foundry as a good next step.

petereberlein commented 7 years ago

Personally I would have preferred to keep the actual schemas out of the catalog, either using a dedicated endpoint or referencing URLs for each schema, but if the majority of the group prefers an all-in-one approach then I would vote for option #2, method attached schemas. Although they increase redundancy at least it is obvious which schema applies when, which contributes to simplicity. Also, if in future different osb platforms are reflected by different catalog responses (requested with an osb platform specific query), then the need for extending the more generic applies-when clause from proposal #1 is less relevant.

shalako commented 7 years ago

I spoke with the PM for the Cloud Controller, which is the client of the broker in CF. He can work with either proposal. We discussed they're likely to story the schemas with plans, even if the broker exposes them at the service level. So if a schema has no applies_when.service_plan_id, then Cloud Controller will save the schema for all plans of the service. CF clients would then get schemas only for requested plans, and either parse them by applies_when or by nested object/method.

We'll send these proposals to our CLI and web client teams for feedback.

gberche-orange commented 7 years ago

Also, if in future different osb platforms are reflected by different catalog responses (requested with an osb platform specific query), then the need for extending the more generic applies-when clause from proposal #1 is less relevant.

@petereberlein @shalako

Rethinking about last WG call discussion on having the catalog endpoint request convey the platform profile (e.g. in a context parameter): while this enables the broker response to restrict the schemas returned to the only requested platform (say CF), this is likely to make the broker federation use-cases more complex:

In the case of a federation of brokers (e.g. where a federating broker federates a number of federated brokers, supporting different platforms and possibly different OSB API versions), the federating broker likely needs to obtain all supported schemas by a federated broker at once, and would prefer avoiding to repetitively query the /catalog endpoint with all possible platforms in a context parameter or all possible X-Broker-API-Version header variations.

I still believe keeping room for future extensibility (without introducing breaking changes, such as with the applies-when construct) is useful and relevant, as we explore new use-cases and broader OSB API usage.

I hope that the "validation by implementation" phase in CF will provide additional useful feedbacks for both proposals #5 and #2.

Sorry I won't be able to make it to the weekly call today.

shalako commented 7 years ago

@gberche-orange I expect in that scenario, the federating broker would have to fetch all the schemas. A query param to filter the response would be an optional nice-to-have.

I have spoken with the team responsible for the Pivotal web UI for CF. They have expressed a preference for the simpler, more explicit declaration of schemas enabled by proposal 2.

mattmcneeney commented 7 years ago

I think that proposal 2 (method-level schemas) will be easier for platform providers to implement (they don't have to match schemas to plans, methods and operations) and easier for service broker authors to implement. Both proposals have capacity for future extensibility, so my preference would be to proceed with a test implementation of proposal 2.

avade commented 7 years ago

I agree with what @mattmcneeney is saying and also propose we proceed with proposal 2.

I like the idea of extensibility applies-when could offer, but it feels like futureproofing

petereberlein commented 7 years ago

I'd also vote for the more explicit and straightforward method level schemas option: +1

gberche-orange commented 7 years ago

Both proposals have capacity for future extensibility

@mattmcneeney Can you please detail how you envision the proposal 2 could offer extensibility for schemas that differ based on geographical locations (us-east vs us-west), OSB api version, platform profiles (CF vs k8s), bind resources (e.g. credentials vs route service), or service instance plan update ?

Besides, a minor wording clarifying fix would be helpful in proposal 2 example, see https://github.com/avade/servicebroker/commit/9ef94ce96ca65bfc9ce482d5ea5be0ad62643a84#commitcomment-21129675 )

I expect in that scenario, the federating broker would have to fetch all the schemas. A query param to filter the response would be an optional nice-to-have.

@shalako, I agree that in order to support the federation use-case (e.g. with different schemas per profiles K8S or CF), the federating broker would prefer to fetch all schemas and rely on a construct such as applies-when rather than a query param that would filter the response.

We discussed they're likely to story the schemas with plans, even if the broker exposes them at the service level. So if a schema has no applies_when.service_plan_id, then Cloud Controller will save the schema for all plans of the service. CF clients would then get schemas only for requested plans, and either parse them by applies_when or by nested object/method. [...] I have spoken with the team responsible for the Pivotal web UI for CF. They have expressed a preference for the simpler, more explicit declaration of schemas enabled by proposal 2.

@shalako I understand you considered in https://github.com/openservicebrokerapi/servicebroker/issues/59#issuecomment-282867764 to allow for future extensibility in the broker API through construct such as applies-when while optionally reducing initial complexity for clients that desire it by offering client UIs endpoints (CC endpoint for CF) that return a single schema based on filters expressed as query params (plan, object, method for now), i.e. clients don't have to handle the applies-when logic if they don't need to now.

This approach seems compatible with the feedback you received from the PCF webui team, and a fair balance of extensibility vs simplicity. Are you still considering this approach ?

mattmcneeney commented 7 years ago

@gberche-orange There are a number of ways proposal 2 could be developed to offer extensibility in the future (nested input parameters, request headers, similar applies-when logic, etc). Whilst it is obviously important to consider these future use cases, I think we should try to move forward with the simplest solution that fits the current use cases and then separately discuss what changes we would need to support more advanced use cases in the future.

To ensure this is what we are actually doing, do you have any services you are developing now that require different input parameters based on geographical locations that you could share with the group?

Thanks, Matt

duglin commented 7 years ago

IBM is ok with proposal 2: Method-attached schemas.

With respect to extensibility, and in particular the geo-based parameters, two things come to mind. First, since I think we're talking about the geo of the platform making the request people may want to consider including this geo information in the "context" object and then perhaps the spec should including a "context" object on the GET /v2/catalog request. Then the Broker can customize the list appropriately.

Second, at what point should we look at the differences between services plans and say "that's too big of a difference, make it a new service" ? In the case of differing geos I'm not sure it crosses that line, but I'm mentioning this because as we think about variants between plans and how to represent them we always have the ultimate escape clause (create a new service) if people can't express the differences between plans sufficiently.

gberche-orange commented 7 years ago

@mattmcneeney

There are a number of ways proposal 2 could be developed to offer extensibility in the future (nested input parameters, request headers, similar applies-when logic, etc).

I'm not sure to understand how the ways mentioned above would work without implying breaking changes to proposal 2.

e.g. from

      "schemas": {
        "service_instances": { 
          "create": {
            "parameters": {
              "$schema":

to the following after adding platform-profile and x-api-location dimensions

      "schemas": {
        "service_instances": { 
          "create": {
            "CF": {
               "eu-west1": {
                  "parameters": {
                      "$schema":

I think we should try to move forward with the simplest solution that fits the current use cases and then separately discuss what changes we would need to support more advanced use cases in the future.

To me this strategy fits well for iteratively building products where the cost of change is low (a.k.a impact of changes are controlled).

In the context of OSB, we are building an API (with a published change policy stating breaking changes will not be introduced), which is made available to multiple communities. Once OSB starts being adopted by multiple communities as we hope, I would expect the cost of changes to increase (with number of platforms, clients etc) and be harder to assess beforehand (because it might be harder to get feedback from a more widespread user base).

My efforts since late dec on this issue were trying to avoid that schemas get introduced with the simple input params use-case in mind, and fall short of supporting other use-cases that arise in the coming months.

I see some existing features in the spec that could have been handled by schemas (bindeable, plan_updateable)

I also understand similar abstractions have been introduced in the past in the service broker api to account for future extensibility, e.g. the bind_resource

I however might be wrong by:

Thanks anyway for having taking time to consider my concerns and alternative proposals to try to address them.

I also agree with Shannon's point on WG weekly meeting on Feb 14th that some other features have a high priority and it might not be wise delaying them to solely focus on schemas.

To ensure this is what we are actually doing, do you have any services you are developing now that require different input parameters based on geographical locations that you could share with the group?

I updated the proposal document with more precise use-cases for additional selectors:

since I think we're talking about the geo of the platform making the request people may want to consider including this geo information in the "context" object

@duglin I believe this approach falls down in the same limitation than a platform profile being passed in a context object to the catalog endpoint see https://github.com/openservicebrokerapi/servicebroker/issues/59#issuecomment-283046570 which would make the broker aggregation use-case hard to implement.

avade commented 7 years ago

Thinking about using the schema to express which platforms are supported for certain inputs, If the OSBAPI returned the schema style @gberche-orange is advocating for, I do not think that we would expose non CF plans via the Cloud Controller API for CLI's / GUIs to consume. It would mean that Cloud Foundry want to interpret and filter the schemas/plans based on platform before presenting them in the marketplace.

Then this causes platforms to build logic to choose which plans to render in the marketplace and then clients of that marketplace also needing to interpret the applies when logic.

@duglin's idea to add context to the catalogue request makes more sense to me, as the broker is expected to only return relevant services and plans for the platform. Aggregating brokers would then be required to delegate requests rather than serving up static catalog content.

Interested to hear from @vaikas-google / @pmorie. I know @pmorie and @mattmcneeney need a decision soon to unblock their respective projects.

duglin commented 7 years ago

I have to be honest, I'm having a really hard time following all of this. I think it would help me if someone could clearly articulate the exact problem we're trying to solve. For example, I thought it was a fairly limited issue: need a way to discover the list of input parameters (and their schema) that can be specified on the instance and binding create() operations.

But now we seem to have turn into some rather complex filtering issue and I'm not clear what the requirements are for this - e.g. geo seems to be one.

If we want to solve the problem of certain plans, or even services, only being available based on certain criteria then I think this is a different problem from the "parameter discovery" one and I would prefer we address it in a different issue. If, however, people think they are linked then can we get an updated problem statement so its more obvious what the exact issues are that we're trying to address?

shalako commented 7 years ago

Today on the call we agreed to proceed with the proposal known as "Method-attached schemas", or plan-level schemas.

Proposal document Provisional spec

We'll begin coordinating implementation of support for declaration of supported parameters in Cloud Foundry.

mattmcneeney commented 7 years ago

Quick question; how would everyone feel about adding the following to the spec (not necessarily in these words):

Service brokers MUST validate input parameters that are provided via calls to create, update or bind.

When looking into the validation of this work in Cloud Foundry, it would be ideal if service brokers performed validation on any input parameters to ensure they match the relevant schemas. There would be no easy way to enforce this, but it would encourage best practice so that brokers do not rely on platforms to perform validation (which may or may not exist). What are your thoughts?

angarg12 commented 7 years ago

We did that with our broker, and seems reasonable to ask brokers to validate the schema that they define.

mattmcneeney commented 7 years ago

Since this addition to the spec isn't directly related to input parameter schemas, I can create a PR for this minor change and we can continue the discussion there.

mattmcneeney commented 7 years ago

Would everyone be OK with me changing any references to "input parameters" in the spec and proposal to "configuration parameters"?

This would be more consistent to the existing CF experience, and with hindsight the word "input" is a bit meaningless.

$ cf create-service -h

NAME:
   create-service - Create a service instance

USAGE:
   cf create-service SERVICE PLAN SERVICE_INSTANCE [-c PARAMETERS_AS_JSON] [-t TAGS]

   Optionally provide service-specific configuration parameters in a valid JSON object in-line:

   cf create-service SERVICE PLAN SERVICE_INSTANCE -c '{"name":"value","name":"value"}'
duglin commented 7 years ago

re: wording change - ok with me

vaikas commented 7 years ago

I'm OK with the wording change to 'configuration parameters'

vaikas commented 7 years ago

For the MUST I'm OK with that as well. We should probably make it clear in the documentation that Controllers are not expected to do the validation so it's left to the broker. MUST is probably the best way to communicate that to the broker implementors.

duglin commented 7 years ago

I'm not following the idea of controllers vs brokers doing validation. Whoever receives a message is the one do the validation.

As for MUST vs SHOULD. The example I worry about is something like: a property is defined as an int but someone passes in "1.0". While it would be fine for a receiver of this message to reject it, I think its also ok for someone to be a bit forgiving and convert "1.0" to "1" and keep going - as long as the semantics of what the user intended can be unambiguously determined. This is why I kind of prefer a SHOULD.

mattmcneeney commented 7 years ago

In reality I expect to see multiple points of validation. A CLI or Web UI could validate any parameters that are provided against the schema, followed by the platform, and finally the service broker. I don't think this is a bad thing.

I agree with @duglin that brokers should have some leeway to interpret a "1.0" as a "1", as that will provide a better, less finicky user experience. The important thing is that we add something to the spec (applying to all fields in every call) that guides when and how errors should be returned. A broker interpreting "1.0" as "1" is acceptable (in my opinion). A broker going further than that and interpreting "1.9" as "2" could be a confusing experience.

(This is also why fetching current values is going to be important for end users)

duglin commented 7 years ago

I've been assuming we could extend the json schema with additional fields as needed by platforms. Since the f2f its been made clear we can't, so there might be an issue. We have a need to extend the schema with more info than what the json schema can support. For example, in bluemix we need to include a URL that the platform can perform a GET on to dynamically get the list values for the dropdown. I'm beginning to think that perhaps we should not use JSON schema and develop our own way of expressing our requirements.

Here's the snippet of docs from Bluemix for reference:

Using service parameters to create customized input fields

Service parameters allow you to create customized input fields in the Bluemix service creation user interface. The values entered by the user will be sent to your service broker on the request to provision the service. The parameters attribute can be added as an array to your JSON, allowing you to create custom input fields of the following types: text, password, dropdown, checkbox, or radio. The parameters attribute should be added within the metadata entry under the JSON response of GET /v2/catalog. Note: userDefinedService has been deprecated. Previously, when provisioning a service, custom service parameters could be added to your JSON by nesting them within the userDefinedService entry. Do not add these parameters under userDefinedService; instead, add them directly under metadata.

Service parameter examples

The following examples illustrate how service parameters can be used to customize a service:

Service parameter definitions

duglin commented 7 years ago

See an example here: https://gist.github.com/duglin/ee082145611f86a613d9ee95170f4ed9#file-parameters-L35

duglin commented 7 years ago

it just seems like this would be a lot easier for broker authors to create then to have to deal with json schema.

mattmcneeney commented 7 years ago

Thanks for posting this spec @duglin. We've had a good look through it and compared its capabilities to those of JSON schema. See our thoughts below!

There are two issues we want to solve with this spec change:

  1. How can platforms and service brokers validate the configuration parameters provided to create/update an instance/binding?

  2. How can client tools (UIs) provide a better user experience (through form generation, prompting for parameters, etc)?

The first problem is solved by having separate schemas for create and update on a service instance or binding. Standard JSON schema validation libraries can be used by both platforms and service brokers to quickly validate any configuration parameters that have been provided. We expect validation to happen at many levels from UIs through to service brokers to provide fast feedback.

The second problem is likely to require additional information that is not present in raw JSON schemas. This additional information can be used to describe, for example, if a field is "sensitive". This can easily be done by adding additional fields to the schema object (valid within the JSON schema specification) such as "sensitive: true". It is then the responsibility of client tools to understand these additional fields and interpret them appropriately. These additional fields are simply ignored by validation libraries.

During the F2F, we discussed how we could add additional GET endpoints (#159 - Fetching current input parameters values) could be used for pre-populating UI forms. During this discussion, we realised that if some service brokers expose parameters for create that are not allowed in an update, then it will be difficult for them to easily render this into a form. However, intelligent clients could work-around this using all of the information available (both schemas and a set of parameters).

Whilst defining our own standard for expressing requirements does allow us to add additional types (such as "password") and would allow service brokers to expose a single schema (using "forCreate" and "forUpdate" fields), it has some downsides:

Many of the additional information in the BlueMix standard (such as "displayname") could easily be added to JSON schemas (without affecting validation) for platforms to use as they wish. Whilst the BlueMix standard is good for UI generation, it will require much more work for platforms and service broker authors as they will have to implement their own validation (and cannot use recommended validation libraries).

So, to summarise, we think that JSON schemas allow for platforms and brokers to quickly and easily validate input parameters, and shouldn't cause a problem for intelligent UIs who want to present the information intuitively. The overhead of having two schemas is reasonably small, and we expect many brokers to simply offer the same schema for both create and update. If we want to add another schema to describe non-parameter information in the future (such as "dashboard_url" or "credentials"), we can simply add another schema to do that (but we think this is outside the scope of this change).

@vaikas-google It would be great to learn how Google use JSON schemas for validation and UI generation to see if there is anything we have missed in our analysis above.

All thoughts very welcome. As said on yesterday's call, we'd love to get started on this ASAP so if you could all provide feedback today/tomorrow that would be very much appreciated 😄

Samze commented 7 years ago

@duglin Interesting! There are some cool use cases here.

Taking your gist we wrote a vanilla JSON schema and used an open source UI generator. See the results here or here.This allows for full validation of the parameters and simple UI rendering. Using JSON schema allows simple client tooling to utilise these existing tools.

However as you rightly mentioned UIs might want to offer more than just what JSON schema supports in order to generate UIs correctly, e.g. sensitive, placeholder.

As Matt stated one option is to add additional keywords to JSON schema that would be ignored during validation but could be used for rendering. See a stripped down version of your gist with additional properties (placeholder, invalidmessage, optionsUrl, sensitive)

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Parameters",
  "type": "object",
  "properties": {
    "nodes": {
      "type": "string",
      "title": "Number of Data Nodes",
      "default": "1",
      "description": "Specify the number of data nodes required for your cluster",
      "placeholder": "please set me",
      "invalidmessage": "oops",
      "optionsUrl": "http://callmemaybe.com",
      "sensitive": true
    }
  }
}

The question then still remains if we want to define a set of keyword extensions as part of the specification?

Some UI generators completely separate JSONSchema and UI metadata. Both react-jsonschema-form and schemaform use an additional UI schema along with JSON schema. This provides the extra UI metadata on how forms should be rendered.

Can we provide a generic set keywords that brokers can write once and multiple clients on multiple platforms can use to generate UIs? Or is the nature of providing this additional UI decoration metadata implementation specific and outside of the scope of the spec and we leave it to the broker and platform authors to agree upon?

@Samze & @ablease

vaikas commented 7 years ago

As far as our use of schemas and validation, I'm trying to find some examples that I could share. They are internal so just want to make sure that I can share them and what I can share...

On Wed, May 24, 2017 at 2:28 AM, Matt McNeeney notifications@github.com wrote:

Thanks for posting this spec @duglin https://github.com/duglin. We've had a good look through it and compared its capabilities to those of JSON schema. See our thoughts below!

There are two issues we want to solve with this spec change:

1.

How can platforms and service brokers validate the configuration parameters provided to create/update an instance/binding? 2.

How can client tools (UIs) provide a better user experience (through form generation, prompting for parameters, etc)?

The first problem is solved by having separate schemas for create and update on a service instance or binding. Standard JSON schema validation libraries can be used by both platforms and service brokers to quickly validate any configuration parameters that have been provided. We expect validation to happen at many levels from UIs through to service brokers to provide fast feedback.

The second problem is likely to require additional information that is not present in raw JSON schemas. This additional information can be used to describe, for example, if a field is "sensitive". This can easily be done by adding additional fields to the schema object (valid within the JSON schema specification) such as "sensitive: true". It is then the responsibility of client tools to understand these additional fields and interpret them appropriately. These additional fields are simply ignored by validation libraries.

During the F2F, we discussed how we could add additional GET endpoints (

159 https://github.com/openservicebrokerapi/servicebroker/issues/159 -

Fetching current input parameters values) could be used for pre-populating UI forms. During this discussion, we realised that if some service brokers expose parameters for create that are not allowed in an update, then it will be difficult for them to easily render this into a form. However, intelligent clients could work-around this using all of the information available (both schemas and a set of parameters).

Whilst defining our own standard for expressing requirements does allow us to add additional types (such as "password") and would allow service brokers to expose a single schema (using "forCreate" and "forUpdate" fields), it has some downsides:

  • Service brokers will have to write their own validation code
  • Platforms will have to write their own validation code
  • The working group will have the overhead of defining and maintaining an additional standard

Many of the additional information in the BlueMix standard (such as "displayname") could easily be added to JSON schemas (without affecting validation) for platforms to use as they wish. Whilst the BlueMix standard is good for UI generation, it will require much more work for platforms and service broker authors as they will have to implement their own validation (and cannot use recommended validation libraries).

So, to summarise, we think that JSON schemas allow for platforms and brokers to quickly and easily validate input parameters, and shouldn't cause a problem for intelligent UIs who want to present the information intuitively. The overhead of having two schemas is reasonably small, and we expect many brokers to simply offer the same schema for both create and update. If we want to add another schema to describe non-parameter information in the future (such as "dashboard_url" or "credentials"), we can simply add another schema to do that (but we think this is outside the scope of this change).

@vaikas-google https://github.com/vaikas-google It would be great to learn how Google use JSON schemas for validation and UI generation to see if there is anything we have missed in our analysis above.

All thoughts very welcome. As said on yesterday's call, we'd love to get started on this ASAP so if you could all provide feedback today/tomorrow that would be very much appreciated 😄

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openservicebrokerapi/servicebroker/issues/59#issuecomment-303669523, or mute the thread https://github.com/notifications/unsubscribe-auth/AKwedOIBy9FSeMKuNp9zGzDfNBK3KEpiks5r8_g6gaJpZM4JqRle .

mattmcneeney commented 7 years ago

We probably won't be able to discuss this on tonight's call since we're just discussing 2.12 features, so if we could get some feedback on this issue here, that'd be super helpful for us. Thank you!

skaegi commented 7 years ago

My team (Bluemix Devops Services) has a controller that manages dev tools vs services but is otherwise very similar to CF and borrows many concepts like provisioning, binding, etc. We've been using JSON Schema for validation of parameters as well as a JSON Schema Form variant for UI for a few years now and by and large it has worked well for us.

Based on our experience we're in the camp that says JSON Schema is a good choice for input parameter validation. I think there is still need for broker-based custom validators but I believe that can be built as an extension of JSON Schema (and written up in a separate issue).

JSON Schema is relatively stable and there is an active community pushing a new round of standardization. For a UI binding for JSON Schema there is still a lot of thinking going on in the Schema Form space. It is coalescing with efforts like JSON Schema Form however still are a number of libraries that make subtly different choices.

I would suggest that JSON Schema validation is mature enough and should be considered for addition. I think it would make sense to open a separate issue for the UI binding and track it independently. I'd also be very hesitant to add any new keywords like applies-when and instead be verbose and use JSON references to avoid repeating definitions.

I would also not add any new UI specific keywords to the schema at this point until we're sure this is a good idea. In our experience mixing UI and Schema is a bit of an anti-pattern and have found the structure of the schema and form are the same only simple cases where sections and choice are not involved.

What we ended up doing was adding one keyword form where we put all of our UI info but otherwise using JSON Schema as-is. Here's a simple example:

"parameters": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "properties": {
        "username": {
            "title": "User name",
            "description": "Type the user name.",
            "type": "string"
        },
        "key": {
            "title": "Access key",
            "description": "Type your access key.",
            "type": "string"
        }
    },
    "required": ["username", "key"],
    "form": ["username", "key"]
}

Apologies if this sounded a bit preachy but I wanted to at least provide a few thoughts based on what we've learned. We're keen to work towards standardization in this space and share what we have here.

mattmcneeney commented 7 years ago

Thank you @skaegi for your detailed feedback. It's very helpful to hear from a team who have been using our proposed implementation for a few years and that your comments regarding its limitations seem to be consistent with the other feedback we have heard.

I think our plan for the first release of this will be supporting the core JSON schema keywords only, and that any possible extensions will be discussed in the future when we have strong and consistent use cases for them.

bmelville commented 7 years ago

We use JSONSchema in several products, and in some of the infrastructure that supports the brokers we're building. All support draft v4, and typically use language-specific validation libraries that support draft v3 and draft v4.

None of the tooling we've found even talks about draft v6, so I would be very hesitant adopting it as the exclusive schema standard until language specific tooling is available.

Most validators support all supported drafts, and if we require that schemas specify their version, we could support any/all supported supported versions.

My proposal would be at the minimum to support v4 initially or both v4 and v6 to allow people to utilize this now.

mattmcneeney commented 7 years ago

165 is merged - closing this issue! Well done all!

bmelville commented 7 years ago

Huge :+1: for all the people who put in all the time to make this one a success.