Queryables / Schemas: with $ref or dereferenced

[m-mohr]

In STAC I observe that the queryables / schemas returned by the API often use $ref to link to "relatively" simple schemas. I guess in Python and other clients that's not so much of an issue, but I'm implementing a browser-based tool (i.e. STAC Browser) that can show a form for queryables, but loading all the dozens of related schemas and dereferncing them freezes the Browser for multiple seconds. In this use-case it's really bad to have $refs, especially if you link to various files/extensions.

I'm wondering:

1. Any guidance from OGC what is preferrable? (with $ref or dereferenced)
2. Would it make sense to add a query parameter that allows to retrieve the schemas in a dereferenced form? (?dereference=1 or so). (I think so.)

[cportele]

1. In general, it is safer to send the response without $refs, since not all clients may support it. This is also what we do in our implementation. The current recommendation for how to construct the schema does not mention $ref, so implicitly I would say that the guidance is not to use $ref. Maybe that should be made explicit?

2. I have concerns about making this required to support, a recommendation should be enough. Almost all guidance on constructing the schema are in a recommendation, so this aspect should be, too. It is very easy to construct a JSON Schema that probably most clients won't be able to parse, but we also do not prohibit that, because at this point we do not have a clear understanding what a good profile of JSON Schema is, to make a firm requirement. I would see the $refs in the same context.

[m-mohr]

Thanks!

1. I think some guidance around $ref would be great.
2. Yeah, a recommendation would be enough for sure. If supported, great. If not supported, then you are out of luck anyway, but it just ignores the parameter and doesn't error. :-)

[cportele]

Meetings 2024-08-26: Add to the recommendation that $ref should not be used, because it makes it harder to parse the logical schema.