search

cf-json / cf-json.github.io

Apache License 2.0
0 stars 2 forks source link

CF-JSON Schema / TS type definitions #21

Open infacto opened 1 year ago

infacto commented 1 year ago

The specification only contains an example with some description. It would be great if we could describe the CF-JSON with proper specs. This could be a JSON Schema and/or TypeScript type definitions (d.ts). Avoid types like any or object. And mark optional (or required) properties.

@aportagain cc

aportagain commented 1 year ago

Thanks for the suggestion @infacto , I agree that a machine-readable specification would be nice to have. What we currently have is a specification that's only human-readable... and probably in parts only barely :)

aportagain commented 1 year ago

I don't think an exhaustive machine-readable spec is feasible, unless someone else comes up with that for the CF conventions themselves. Are you familiar with these? The current version 1.10 is over 230 pages (human-readable) and counting, plus other bits referenced there, for example the infamous "The values of the units attributes are character strings that are recognized by UNIDATA’s Udunits package"... it's a bit of a beast!

aportagain commented 1 year ago

But we could try to describe / constrain the one or two highest levels, at least to some degree, for example dimensions, variables, attributes, and at least also for variables their shape, attributes and data. Do you think that would be helpful and worthwhile?

infacto commented 1 year ago

Well, a month has passed and I haven't worked on it since. I need to remember what the issues were... I think it's about describing an object with all mandatory or possible properties. If this exists. I'm not familiar with CF JSON, weather data etc. I'm just a web developer who wanted to create an API and related types. And I wondered if there are developer related stuff like specification. So, yes an outline of the CF-JSON type would be a good idea. I think this is good human readable stuff too if done right. And allows you to get the information faster than going through hundreds of lines of text. But I'm not sure how dynamic or customizable CF-JSON is. But even then, it would be more helpful to describe these specifications in a schema or interface. In the end it's about describing the CF-JSON for e.g. a HTTP API. The basic type (optional extendable). Otherwise I'll have to crawl over examples and create my own base type. It's exhausting and never complete or accurate. Similar to reverse engineering. It does not have to be for developers or developer language proven. JSON schema or TypeScript type definition is not necessary. It's sufficient to list all properties and describe with possible types or values. And what properties are required or optional, etc. For example in a table with property name, type, required flag and description or comment. Instead of just describing an example. Examples are great and also very helpful. But in specification documents I expect specification. :) But it's just a suggestion...