search

geostyler / geostyler-style

Style declaration files for the GeoStyler project
https://geostyler.github.io/geostyler-style/docs/master/
BSD 2-Clause "Simplified" License
16 stars 15 forks source link

YAML from ts for documenting purposes #144

Closed pvgenuchten closed 2 years ago

pvgenuchten commented 4 years ago

I was discussing with @chrismayer that it would facilitate discussion on the geostyler spec if it were published somewhere as a YAML file. YAML is for some (e.g. me) more easy to read then ts. I was checking if there are some libs around that would offer such functionality, I found this https://github.com/manifoldco/swagger-to-ts but it is the other way around. Any ideas how to auto generate such a YAML?

We probably loose some information in the conversion as ts seems more extended then YAML, but for me it would help explaining what we're doing.

Thanx for you consideration.

jansule commented 4 years ago

AML is for some (e.g. me) more easy to read then ts

I agree that ts does not provide the most readable structure.

it would facilitate discussion on the geostyler spec if it were published somewhere as a YAML file

I'm not very experienced with yaml, but does yaml provide information about the allowed types, etc. like a schema, or is it more like an explicit instance?

When comparing to the XML world, my understanding is that a yaml corresponds to a XML whereas our typescript definition rather corresponds to XSD.

When comparing to the JSON world, there is JSON (~XML), but also json-schema (~XSD), for which there are converters btw (https://github.com/YousefED/typescript-json-schema).

So I don't think we can directly convert typescript definitions to yaml.

Did you check if there is something in the yaml world that corresponds to XSD?

Could you also take a look at https://github.com/YousefED/typescript-json-schema and let us know if this would satisfy your needs for a more readable definition?

pvgenuchten commented 4 years ago

Hi Jan, correct, yaml itself is just an encoding like json or xml, you can express any datastructure. However YAML these days is used a lot in the scope of OpenAPI. you can use it to define methods of the API, but also request and response objects. The YAML used in this scope does provide a schema for the response json which includes the type of a field.

So yes OpenAPI Spec is a special type of YAML, which is actually similar to xsd. It's the one i'm most familiar with, but i guess json schema is maybe more fit indeed.

jansule commented 4 years ago

but i guess json schema is maybe more fit indeed.

I agree.

However, I prefer to avoid having duplicate information in a project, for which we have to take care of (automated) syncing. This usually leads to different problems in the future. So I'm thinking of other ways that might address you concern, without the need of duplicate information.

If your main concern is the lack of a hierarchical/nested representation of the geostyler-style structure, the example styles provided in this repository might be of help (https://github.com/geostyler/geostyler-style/blob/master/sample.ts, https://github.com/geostyler/geostyler-style/blob/master/rastersample.ts).

Would it help, if we promote these examples more prominent in the README?

Another very simple option would be to rearrange the interfaces in our index.d.ts to list the most important ones at the top (e.g. the symbolizer interfaces).

Please let me know, if any of these options sound satisfying to you.