search

openservicebrokerapi / servicebroker

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

We are violating the JSON schema spec in our usage of $schema #371

Closed n3wscott closed 5 years ago

n3wscott commented 6 years ago

Please see 7. The "$schema" keyword

The "$schema" keyword SHOULD be used in a root schema. It MUST NOT appear in subschemas.

We use $schema in subschemas only and not in the root schema.

See 4.5. Root schema and subschemas for the definition of root and subschemas.

I recommend moving$schema to the root of the document and omitting it from the subschemas in the catalog.

Alternatively we could make schemas a new endpoint to the catalog. Example: /v2/catalog/schema

mattmcneeney commented 6 years ago

@n3wscott Are you sure we're using $schema in a subschema?

We're using it nested in a complex object, yes, but we are (via the spec) effectively telling folks that the schema for service instance creation lives at services[i].plans[j].schemas.service_instance.create. Does the $schema key really need to be at the root of the API response JSON rather than wherever we deem the schema to live?

n3wscott commented 6 years ago

Here is why this could be important, if each verb object is able to define their own root schema, we are not allowed to use internal references and for a complex service or a service aggregator, the catalog response is very verbose and has the very real possibility that the schema is not updated consistently for shared objects (like billing account or some kind of common access metadata). This also can egde us over the schema limit for the catalog.

The more I have thought about this issue, the more I am in favor of removing the schema definition from catalog entirely and moving it to another resource. This has the benefit of the schema endpoint being cacheable for long periods of time while the catalog might update more frequently. The catalog should then have a $ref link to the object it defines in the master schema document.

mattmcneeney commented 5 years ago

Closing this as I think this is more of a meta discussion and the work done to add configuration parameter schemas to the catalog was merged a couple of releases ago and seems to be working well.