openservicebrokerapi / servicebroker

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

Change how we link to type definitions inside the spec #451

Closed luksa closed 6 years ago

luksa commented 6 years ago

I suggest we change the way we link to the definitions of OSBAPI types in the spec.

For example, let's take the row that shows the "schemas" field in https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md#plan-object.

I suggest we replace the word "object" in the second column with the following text: "Schema object". As shown here, the name of the type links to the description of said type.

Similarly, the second column in the "plans" row under Service Objects would be "array of Plan objects" or simply "[]Plan" instead of "array-of-objects" as we have now.

luksa commented 6 years ago

Something along the lines of: https://github.com/luksa/servicebroker/blob/9620a17665768dcde2f4d6a426d7d7eea2f6f9a1/spec.md#plan-object

duglin commented 6 years ago

@luksa want to open a PR so people can see the proposed edits in context? ok if I assign this and #450 to you?

luksa commented 6 years ago

Closing (fixed by #459)