Merge pull request #665 from waterlink/change-which-field-acts-as-an-identity-for-maintenance-info-object

Clarify how maintenance_info objects should be compared.

Author: mattmcneeney

spec.md

@@ -362,7 +362,7 @@ use these error codes for the specified failure scenarios.
 | AsyncRequired | This request requires client support for asynchronous service operations. | The query parameter `accepts_incomplete=true` MUST be included the request. |
 | ConcurrencyError | The Service Broker does not support concurrent requests that mutate the same resource. | Clients MUST wait until pending requests have completed for the specified resources. |
 | RequiresApp | The request body is missing the `app_guid` field. | The `app_guid` MUST be included in the request body. |
-| MaintenanceInfoConflict | The `maintenance_info` field provided in the request does not match the `maintenance_info` field provided in the Service Broker's [Catalog](#catalog-management). | The Platform SHOULD fetch the latest version of the Service Broker's [Catalog](#catalog-management). |
+| MaintenanceInfoConflict | The `maintenance_info.version` field provided in the request does not match the `maintenance_info.version` field provided in the Service Broker's [Catalog](#catalog-management). | The Platform SHOULD fetch the latest version of the Service Broker's [Catalog](#catalog-management). |
 
 Unless otherwise specified, an HTTP status code in the 4xx range MUST result in
 the Service Broker's resources being semantically unchanged as a result of
@@ -547,9 +547,11 @@ schema being used.
 
 | Response Field | Type | Description |
 | --- | --- | --- |
-| version | string | This MUST be a string conforming to a [semantic version 2.0](https://semver.org/spec/v2.0.0.html). The Platform MAY use this field to determine whether a maintenance update is available for a Service Instance. |
+| version* | string | This MUST be a string conforming to a [semantic version 2.0](https://semver.org/spec/v2.0.0.html). The Platform MAY use this field to determine whether a maintenance update is available for a Service Instance. |
 | description | string | This SHOULD be a string describing the impact of the maintenance update, for example, important version changes, configuration changes, default value changes, etc. The Platform MAY present this information to the user before they trigger the maintenance update. |
 
+\* Fields with an asterisk are REQUIRED.
+
 ```
 {
   "services": [{
@@ -951,7 +953,7 @@ Service Broker will use it to correlate the resource it creates.
 | organization_guid* | string | Deprecated in favor of `context`. The Platform GUID for the organization under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. |
 | space_guid* | string | Deprecated in favor of `context`. The identifier for the project space within the Platform organization. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. |
 | parameters | object | Configuration parameters for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. |
-| maintenance_info | [Maintenance Info](#maintenance-info-object) | If a Service Broker provides maintenance information for a Service Plan in its [Catalog](#catalog-management), a Platform MAY provide the same maintenance information when provisioning a Service Instance. This field can be used to ensure that the end-user of a Platform is provisioning what they are expecting since maintenance information can be used to describe important information (such as the version of the operating system the Service Instance will run on). If a Service Broker's catalog has changed and new maintenance information is available for the Service Plan being provisioned, then the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. |
+| maintenance_info | [Maintenance Info](#maintenance-info-object) | If a Service Broker provides maintenance information for a Service Plan in its [Catalog](#catalog-management), a Platform MAY provide the same maintenance information when provisioning a Service Instance. Any field except for `maintenance_info.version` will be ignored. This field can be used to ensure that the end-user of a Platform is provisioning what they are expecting since maintenance information can be used to describe important information (such as the version of the operating system the Service Instance will run on). If a Service Broker's catalog has changed and new maintenance information version is available for the Service Plan being provisioned, then the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. |
 
 \* Fields with an asterisk are REQUIRED.
 
@@ -1002,7 +1004,7 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 | 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. The `operation` string MUST match that returned for the original request. This triggers the Platform to poll the [Last Operation for Service Instances](#polling-last-operation-for-service-instances) endpoint for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. |
 | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. |
 | 409 Conflict | MUST be returned if a Service Instance with the same id already exists or is being provisioned but with different attributes. |
-| 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous provisioning for the requested Service Plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. This MUST also be returned if the `maintenance_info` provided in the request does not match the `maintenance_info` described for the Service Plan in the Service Broker's [catalog](#catalog-management). In this case, the response body MUST contain error code `"MaintenanceInfoConflict"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"The maintenance information for the requested Service Plan has changed."`. |
+| 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous provisioning for the requested Service Plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. This MUST also be returned if the `maintenance_info.version` provided in the request does not match the `maintenance_info.version` described for the Service Plan in the Service Broker's [catalog](#catalog-management). In this case, the response body MUST contain error code `"MaintenanceInfoConflict"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"The maintenance information for the requested Service Plan has changed."`. |
 
 Responses with any other status code MUST be interpreted as a failure and the
 Platform might need to perform [Orphan Mitigation](#orphan-mitigation).
@@ -1141,7 +1143,7 @@ Broker SHOULD return a meaningful error message in response.
 | plan_id | string | If present, MUST be the ID of a Service Plan from the Service Offering that has been requested. If this field is not present in the request message, then the Service Broker MUST NOT change the Service Plan of the Service Instance as a result of this request. |
 | parameters | object | Configuration parameters for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. See "Note" below. |
 | previous_values | [PreviousValues](#previous-values-object) | Information about the Service Instance prior to the update. |
-| maintenance_info | [Maintenance Info](#maintenance-info-object) | If a Service Broker provides maintenance information for a Service Plan in its [Catalog](#catalog-management), a Platform MAY provide the same maintenance information when updating a Service Instance. This field can be used to perform maintenance on a Service Instance (for example, to upgrade the underlying operating system the Service Instance is running on). If a Service Broker's catalog has changed and new maintenance information is available for the Service Plan that the Service Instance being updated is using, then the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. |
+| maintenance_info | [Maintenance Info](#maintenance-info-object) | If a Service Broker provides maintenance information for a Service Plan in its [Catalog](#catalog-management), a Platform MAY provide the same maintenance information when updating a Service Instance. Any field except for `maintenance_info.version` will be ignored. This field can be used to perform maintenance on a Service Instance (for example, to upgrade the underlying operating system the Service Instance is running on). If a Service Broker's catalog has changed and new maintenance information version is available for the Service Plan that the Service Instance being updated is using, then the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. |
 
 \* Fields with an asterisk are REQUIRED.
 
@@ -1228,7 +1230,7 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc
 | 200 OK | MUST be returned if the request's changes have been applied or MAY be returned if the request's changes have had no effect. The expected response body is `{}`. |
 | 202 Accepted | MUST be returned if the Service Instance update is in progress. The `operation` string MUST match that returned for the original request. This triggers the Platform to poll the [Polling Last Operation for Service Instances](#polling-last-operation-for-service-instances) endpoint for operation status. Note that a re-sent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. |
 | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. |
-| 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested Service Plan). Additionally, this MUST be returned if the Service Broker only supports asynchronous update for the requested Service Plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. Additionally, this MUST be returned if the `maintenance_info` provided in the request does not match the `maintenance_info` described for the Service Plan in the Service Broker's [catalog](#catalog-management). In this case, the response body MUST contain error code `"MaintenanceInfoConflict"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"The maintenance information for the requested Service Plan has changed."`. |
+| 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested Service Plan). Additionally, this MUST be returned if the Service Broker only supports asynchronous update for the requested Service Plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. Additionally, this MUST be returned if the `maintenance_info.version` provided in the request does not match the `maintenance_info.version` described for the Service Plan in the Service Broker's [catalog](#catalog-management). In this case, the response body MUST contain error code `"MaintenanceInfoConflict"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"The maintenance information for the requested Service Plan has changed."`. |
 
 Responses with any other status code MUST be interpreted as a failure.
 When the response includes a 4xx status code, the Service Broker MUST NOT