microsoft / microsoft/planetary-computer-apis
Avoid $ref in /queryables
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 129
- Forks
- 33
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 1
Description
Neither a bug nor really a feature, so opening a blank issue.
The /queryables endpoints refer to external schemas using $ref. This leads to a lot of downstream HTTP requests in clients, e.g. STAC Browser. For example requesting https://planetarycomputer.microsoft.com/api/stac/v1/queryables has a single field defined, which pretty much just refers to a very simple JSON Schema of like 30 bytes: { "type": "string", "minLength": 1 }. For this simple schema. the client has to sends 8(!) http requests returning a total of nearly 10.000 bytes. Could this be improved?
Two alternative solutions could be considered:
- Inline at least the simple schemas.
- Bundle the schema on the server-side and return the bundled schema.
I'd prefer version 2 as it just is much more lightweight on the clients, which don't need to carry a full $ref parser library. $refs itself are also pretty ill-defined with a lot of different implementation, so the interoperability is pretty bad. The JSON Schema community is currently discussing this, but that will take more time: https://github.com/json-schema-org/referencing https://phil.tech/2022/bundling-openapi-with-javascript/
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the /queryables endpoints and how their JSON Schemas are generated and served. Compare the proposed bundling and inlining approaches, then verify that the response avoids unnecessary external $ref requests while preserving the queryables schema.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, python
- Domain
- api
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100