search

geocoders / geocodejson-spec

DRAFT An attempt to have standard geojson responses from geocoders.
37 stars 10 forks source link

[Feature] JSON Schema #25

Closed jenkin closed 1 year ago

jenkin commented 1 year ago

This PR adds a complete JSON Schema that is compliant with the spec. It restricts the official GeoJSON schema defining two additional constraints related to geocode objects in GeoJSON FeatureCollection and Feature objects.

It defines a JSON Schema for semver (see semver.org/issues/431) and for geohash.

It adds a simple toolchain managed with make to dereference and bundle external schemas (geojson as remote dependency, semver and geohash as local ones) and to compute checksum of distributed file. Human-editable files are in src/ folder, final bundle is in draft/ folder with the human-readable spec.

It also adds a simple README in root folder.

SUGGESTION: enable Github Pages on master branch to publish the schema at https://geocoders.github.io/geocodejson-spec/draft/geocodejson.schema.json with proper mime type.

Refs: #24

yohanboniface commented 1 year ago

Thanks for this work @jenkin ! Open API schema and README looks good to me! :)

I'm not exactly getting why git hooks are involved here ? Why not for example a "simple" make bundle command ? Thanks for your lights :)

jenkin commented 1 year ago

Git hooks ensure that no commit can contain invalid or outdated schema. But we can disable them and use make rules manually to reduce complexity, if you are ok I can add a commit before merge.

yohanboniface commented 1 year ago

The simpler, the better :) So I'd better go with a documented release process and make utilities, yep, if that's ok for you :)

jenkin commented 1 year ago

Et voilà! :)

yohanboniface commented 1 year ago

Grazie! :)

Looks good to me. @lonvia @nlehuby up for a look ? :)

jenkin commented 1 year ago

Hi @yohanboniface @lonvia , any news? In the meantime I've published the draft in one of my repo... ;) Best!

lonvia commented 1 year ago

Looks okay. Just one question for my understanding: the human-readable draft/README.md and the schema are completely separate? Do we need to make manually sure that they are the same?

jenkin commented 1 year ago

Just one question for my understanding: the human-readable draft/README.md and the schema are completely separate? Do we need to make manually sure that they are the same?

Yes. Actually the spec is quite simple and mainly written as comments in code blocks, so we can use the json schema as source of truth and generate the human readable spec from it with a custom script. Maybe an additional task for the next v1 release (see #26)?

yohanboniface commented 1 year ago

Good point! But I don't know how to keep those in sync without setting up a complex workflow, so I'd say it's acceptable at this stage.

@jenkin added you as owner :)