search

visualize-admin / visualization-tool

The tool for visualizing Swiss Open Government Data. Project ownership: Federal Office for the Environment FOEN
https://visualize.admin.ch
BSD 3-Clause "New" or "Revised" License
29 stars 3 forks source link

Improve calling charts via API documentation #1583

Open bprusinowski opened 3 weeks ago

bprusinowski commented 3 weeks ago

Currently, we link to a TypeScript file with a lot of nested io-ts type definitions – it's quite hard to understand the "resolved" type we actually expect.

We should have a way to either insert resolved TS type directly into the documentation, or think about some other way of making this more accessible.

ptbrowne commented 3 weeks ago

I think that if we want to share our definitions, we should use a format that is more interoperable than the io-ts schema. I think that we could use JSON schema ? I think then we could benefit from features like autocompletion in editors like VSCode, as well as potentially more interoperability with other languages (Python).

bprusinowski commented 3 weeks ago

I think it's a good idea, we use https://github.com/vega/ts-json-schema-generator in other project with a codegen script to convert TS types to JSON Schemas and it works quite well 👍

ptbrowne commented 3 weeks ago

Ah, I had not thought of using a ts -> json-schema converter, I would have treated the json schema as the source, and hopefully find json-schema to ts-converter. At this point, I think your idea is good as it would be easier to implement and test 👍

bprusinowski commented 3 weeks ago

After working for a while with JSON Schema, I much more prefer doing this in TS -> JSON Schema direction, as we are more used to writing TS types, with all the handy features like unions, etc, and don't need to learn a new syntax :)