Service broker create instance schemas

[Samze]

As a service broker author, I can register a single plan with a create service instance schema #145580729

As a client tooling author, I can retrieve a create service instance schema for a plan #146453595

Why

The Open Service Broker API is proposing allowing brokers to define JSON schema for their configuration parameters. This will allow tooling to validate parameters and UIs to auto generate forms.

Schemas are to be defined as part of the catalog on a plan and support create/update parameters on a service instance and create parameters on a service binding (update does not exist yet).

The updated spec can be found here.

Example of what a new catalog with schemas will look like:

{
     ....
    "plans": [{
      "name": "fake-plan-1",
      "id": "d3031751-XXXX-XXXX-XXXX-a42377d3320e",
      "description": "Shared fake Server, 5tb persistent disk, 40 max concurrent connections",
      "schemas": {
        "service_instance": {
          "create": {
            "parameters": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "billing-account": {
                  "description": "Billing account number used to charge use of shared fake server.",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }]
}

What

This PR just adds basic support for create instance schemas. Schemas are parsed during registration, stored in the service plan model and retrieved on the /v2/service_plan/:guid api endpoint. If a broker does not provide a schema, then we default to an empty schema.

• Add create_instance_schema to plan model object
• Add migration to service_plans to include text blob for create_instance_schema
• Modify service catalog objects to represent and validate schemas on broker registration
• Propagate schema errors back to users on failed registration
• Expose schemas on /v2/service_plans/:guid
• New presenter for service_plans to format and provide default schemas when nil
• Added new 2.13 service broker api spec

Notable things that are not in this PR but are addressed in future stories are:

1. Validating that the provided schema is valid JSON Schema v4 draft.
2. Placing limits on the size of schemas that can be stored.
3. Support for update instance / create binding.

Notes

1. For the proposed 2.13 there can be a maximum of 3 schemas attached to a plan, create/update instance and create binding. We think the best way to represent this in the DB is by adding fields to the plan. This seemed simpler than alternatives, such as adding new DB tables.
2. During parsing of the catalog we interrogate the expected JSON to pull out the create schema to store. When presented on the API /v2/service_plans/:guid, we reconstruct this JSON. However, by doing this it means we separate the concerns of presentation to storage. This means we could iterate on our presentation separate to the OSBAPI spec if needed.
3. We have added the 2.13 broker api spec which verifies that this functionality works but have not bumped to 2.13. The bump to 2.13 will happen when it has been accepted by the working group. This allows us to experiment with this change.
4. We want to support schemas that are up to 128 of KB's in size and enforce this by the DB column type. You can set the limit on a varchar but not a text blob. Unfortunately MySql has a row limit of 64KB, but this excludes text and blobs. This means we must use the text type and will have to validate size before storing the schema. More info here.
5. We have no updated the docs yet as this is still an experimental change.

Feedback appreciated!

PR

• I have viewed signed and have submitted the Contributor License Agreement
• I have made this pull request to the master branch
• I have run all the unit tests using bundle exec rake
• I have run CF Acceptance Tests on bosh lite

Sam & @ablease

cc: @matthewmcnew @st3v

[cfdreddbot]

Hey Samze!

Thanks for submitting this pull request! I'm here to inform the recipients of the pull request that you and the commit authors have already signed the CLA.

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/147446125

The labels on this github issue will be updated when the story is started.

[ljfranklin]

Merged in here. Thanks for the PR, very thorough!