Change default format from jsonv2 to geocodejson

.githooks/pre-commit

@@ -1,27 +1,60 @@
 #!/bin/bash
 
-VERSION=512
-CMD=shasum
-SHA="sha$VERSION"
+INPUT_DIR=src
+OUTPUT_DIR=docs
 
-INPUT=docs/nominatim.openapi.json
-OUTPUT="$INPUT".checksum
+OAS_FILE=nominatim.openapi.json
 
-if [ ! -f $INPUT ]
+SHA_CMD=shasum
+SHA_VERSION=512
+SHA_PREFIX="sha$SHA_VERSION"
+
+NPX_CMD=npx
+SWAGGER_CLI_VERSION="4.0.4"
+PRETTY_MINI_JSON_VERSION="1.1.4"
+JSON_DEREFERENCE_CLI_VERSION="0.1.2"
+VALIDATE_CMD="$NPX_CMD -y @apidevtools/swagger-cli@$SWAGGER_CLI_VERSION validate"
+BUNDLE_OAS_CMD="$NPX_CMD -y @apidevtools/swagger-cli@$SWAGGER_CLI_VERSION bundle"
+BUNDLE_SCHEMA_CMD="$NPX_CMD -y json-dereference-cli@$JSON_DEREFERENCE_CLI_VERSION"
+MINIFY_CMD="$NPX_CMD -y pretty-mini-json@$PRETTY_MINI_JSON_VERSION"
+
+# OpenAPI spec and JSON schema files must exist
+if [ ! -f "$INPUT_DIR/$OAS_FILE" ]
+then
+    echo "$OAS_FILE file in $INPUT_DIR folder is missing, abort"
+    exit 1
+fi
+
+# npx must be installed
+if ! command -v $NPX_CMD &> /dev/null
 then
-    echo "$INPUT file is missing, abort"
+    echo "$NPX_CMD could not be found, please install it"
     exit 1
 fi
 
-if ! command -v $CMD &> /dev/null
+# OpenAPI spec must be valid
+if ! $VALIDATE_CMD $INPUT_DIR/$OAS_FILE &> /dev/null
 then
-    echo "$CMD could not be found, please install it"
+    echo "$OAS_FILE file in $INPUT_DIR folder is not a valid OpenAPI spec, please check"
     exit 1
 fi
 
-CHECKSUM=`$CMD -a $VERSION $INPUT | awk '{print $1}'`
+# Create bundles
+$BUNDLE_OAS_CMD $INPUT_DIR/$OAS_FILE 2> /dev/null | $MINIFY_CMD -o $OUTPUT_DIR/$OAS_FILE 2> /dev/null
+
+# shasum must be installed
+if ! command -v $SHA_CMD &> /dev/null
+then
+    echo "$SHA_CMD could not be found, please install it"
+    exit 1
+fi
+
+# Compute checksums
+SHA_OAS_CHECKSUM=`$SHA_CMD -a $SHA_VERSION $OUTPUT_DIR/$OAS_FILE | cut -d" " -f 1`
+
+echo "Checksum ($OUTPUT_DIR/$OAS_FILE.checksum): $SHA_PREFIX-$SHA_OAS_CHECKSUM"
+echo -n "$SHA_PREFIX-$SHA_OAS_CHECKSUM" > $OUTPUT_DIR/$OAS_FILE.checksum
 
-echo "Checksum ($OUTPUT): $SHA-$CHECKSUM"
-echo -n "$SHA-$CHECKSUM" > $OUTPUT
-git add $OUTPUT
+# Stage new checksums
+git add $OUTPUT_DIR/$OAS_FILE.checksum
 exit 0

.githooks/pre-push

@@ -1,37 +1,44 @@
 #!/bin/bash
 
-VERSION=512
-CMD=shasum
-SHA="sha$VERSION"
+INPUT_DIR=src
+OUTPUT_DIR=docs
 
-INPUT=docs/nominatim.openapi.json
-OUTPUT="$INPUT".checksum
+OAS_FILE=nominatim.openapi.json
 
-if [ ! -f $INPUT ]
+SHA_CMD=shasum
+SHA_VERSION=512
+SHA_PREFIX="sha$SHA_VERSION"
+
+# OpenAPI spec and JSON schema files must exist
+if [ ! -f "$OUTPUT_DIR/$OAS_FILE" ]
 then
-    echo "$INPUT file is missing, abort"
+    echo "$OAS_FILE file in $OUTPUT_DIR folder is missing, abort"
     exit 1
 fi
 
-if ! command -v $CMD &> /dev/null
+# shasum must be installed
+if ! command -v $SHA_CMD &> /dev/null
 then
-    echo "$CMD could not be found, please install it"
+    echo "$SHA_CMD could not be found, please install it"
     exit 1
 fi
 
-CHECKSUM=`$CMD -a $VERSION $INPUT | awk '{print $1}'`
-
-if [ ! -f $OUTPUT ]
+# Checksums must exists
+if [ ! -f "$OUTPUT_DIR/$OAS_FILE.checksum" ]
 then
-    echo "$OUTPUT file is missing, abort"
+    echo "$OAS_FILE.checksum file in $OUTPUT_DIR folder is missing, abort"
     exit 1
 fi
 
-if ! grep "$SHA-$CHECKSUM" $OUTPUT &>/dev/null
+# Compute checksums
+SHA_OAS_CHECKSUM=`$SHA_CMD -a $SHA_VERSION $OUTPUT_DIR/$OAS_FILE | cut -d" " -f 1`
+
+if ! grep "$SHA_PREFIX-$SHA_OAS_CHECKSUM" $OUTPUT_DIR/$OAS_FILE.checksum &>/dev/null
 then
-    echo "wrong checksum, please verify"
+    echo "Wrong checksum for $OAS_FILE, please verify"
     exit 1
+else
+    echo "Checksum ($OUTPUT_DIR/$OAS_FILE): $SHA_PREFIX-$SHA_OAS_CHECKSUM"
 fi
 
-echo "Checksum ($OUTPUT): $SHA-$CHECKSUM"
 exit 0

AUTHORS.md

@@ -12,6 +12,6 @@ Alessio Cimarelli (https://github.com/jenkin)
 
 Contributors
 ------------
-
+Alan Sprecacenere (https://github.com/tegola)
 
 The version control system provides attribution for specific lines of code.

CHANGELOG.md

@@ -12,11 +12,15 @@ Here we track upcoming changes so you can see what changes you might expect in u
 
 ### Added
 - MINOR
-  - Nominatim OpenAPI Specification in JSON format.
+  - Nominatim OpenAPI Specification in JSON format (`/search`, `/lookup` endpoints).
   - Makefile rules to simplify project management.
   - Git hooks to compute spec checksum (sha512). Refs: #6.
+  - GeocodeJSON json schema. Refs: #2.
+  - Utilities to bundle OAS spec.
 
 ### Changed
-
+- MINOR
+  - Schema management outside this repo (please rerun `make hooks`).
+
 ### Fixed
 

Makefile

@@ -1,25 +1,45 @@
 SWAGGER_UI_VERSION ?= v5.4.2
 SWAGGER_ED_VERSION ?= next-v5-unprivileged
+SWAGGER_CLI_VERSION ?= 4.0.4
+AJV_CLI_VERSION ?= 5.0.0
+PRETTY_MINI_JSON_VERSION ?= 1.1.4
+JSON_DEREFERENCE_CLI_VERSION ?= 0.1.2
+HTTP_SERVER_VERSION ?= 14.1.1
+HTTP_SERVER_PORT ?= 8080
 SWAGGER_UI_PORT ?= 8091
 SWAGGER_ED_PORT ?= 8092
 
-ui:
-	echo "Swagger UI running at http://localhost:$(SWAGGER_UI_PORT)"
-	docker run --rm -p $(SWAGGER_UI_PORT):8080 -v $(PWD)/docs/nominatim.openapi.json:/tmp/nominatim.openapi.json -e SWAGGER_JSON=/tmp/nominatim.openapi.json swaggerapi/swagger-ui:$(SWAGGER_UI_VERSION)
-	echo "Shutdown Swagger UI"
+all: build validate checksum verify
 
-editor:
-	echo "Swagger Editor running at http://localhost:$(SWAGGER_ED_PORT)"
-	docker run --rm -p $(SWAGGER_ED_PORT):8080 -v $(PWD)/docs/nominatim.openapi.json:/tmp/nominatim.openapi.json -e SWAGGER_FILE=/tmp/nominatim.openapi.json swaggerapi/swagger-editor:$(SWAGGER_ED_VERSION)
-	echo "Shutdown Swagger Editor"
+build:
+	@echo "Building the Nominatim OpenAPI spec bundle"
+	npx -y @apidevtools/swagger-cli@$(SWAGGER_CLI_VERSION) bundle src/nominatim.openapi.json | npx -y pretty-mini-json@$(PRETTY_MINI_JSON_VERSION) -o docs/nominatim.openapi.json
 
-hooks:
-	echo "Installing git hooks"
-	cp .githooks/* .git/hooks/
+validate:
+	@echo "Validating the Nominatim OpenAPI spec bundle"
+	npx -y @apidevtools/swagger-cli@$(SWAGGER_CLI_VERSION) validate docs/nominatim.openapi.json
 
 checksum:
-	echo "Compute spec checksum"
+	@echo "Computing spec checksum"
 	.githooks/pre-commit
 
 verify:
 	.githooks/pre-push && echo "Checksum ok"
+
+ui:
+	@echo "Swagger UI running at http://localhost:$(SWAGGER_UI_PORT)"
+	docker run --rm -p $(SWAGGER_UI_PORT):8080 -v $(PWD)/src/nominatim.openapi.json:/tmp/nominatim.openapi.json -e SWAGGER_JSON=/tmp/nominatim.openapi.json swaggerapi/swagger-ui:$(SWAGGER_UI_VERSION)
+	echo "Shutdown Swagger UI"
+
+editor:
+	@echo "Swagger Editor running at http://localhost:$(SWAGGER_ED_PORT)"
+	docker run --rm -p $(SWAGGER_ED_PORT):8080 swaggerapi/swagger-editor:$(SWAGGER_ED_VERSION)
+	echo "Shutdown Swagger Editor"
+
+serve:
+	@echo "Serving playground at http://localhost:$(HTTP_SERVER_PORT)"
+	npx -y http-server@$(HTTP_SERVER_VERSION) -p $(HTTP_SERVER_PORT) ./docs
+
+hooks:
+	@echo "Installing git hooks"
+	cp .githooks/* .git/hooks/

README.md

@@ -1,6 +1,6 @@
 # Nominatim OpenAPI Specification
 
-Unofficial OpenAPI specification for Nominatim API provided by OpenStreetMap project.
+Unofficial OpenAPI Specification (OAS) for Nominatim API provided by OpenStreetMap project (OSM).
 
 <p align="center"><img src="./docs/logo-square.png" width="50%" /></p>
 
@@ -30,12 +30,14 @@ This project aims to fill the hole and offer to community a robust, modern, and
 
 Getting started section shows how to use the [official interactive playground]((https://sparkfabrik.github.io/nominatim-openapi/)) hosted by [Github Pages](https://pages.github.com/).
 If you want to locally run your own playground, you must download this repository (via [zip download](https://github.com/sparkfabrik/nominatim-openapi/archive/refs/heads/main.zip) or `git clone`).
-All relevant files are in `docs/` folder.
 
-You can't simply open the `docs/index.html` file in your browser, because of default [Cross-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors). So you need to serve `docs/` folder using a web server running locally.
+> Source of OAS is in `src/` folder, all final files (bundled and minified) are in `docs/` folder.
+
+You can't simply open the `docs/index.html` file in your browser, because of default [Cross-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors).
+So you need to serve `docs/` folder using a web server running locally.
 
 In a javascript-ready environment (ie. with [node](https://nodejs.org/en) and [npm](https://www.npmjs.com/) installed),
-you can run `npx -y http-server ./docs` in a terminal from the project folder and point your browser to `http://localhost:8080`.
+you can run `make serve` in a terminal from the project folder and point your browser to `http://localhost:8080`.
 
 In a Docker-ready environment, you can run `make ui` to have the playground exposed on `http://localhost:8091`.
 
@@ -55,16 +57,18 @@ When ready, the following table will be updated.
 
 | Milestone | Task | TBD | To do | Doing | Done | Refs |
 | --------- | ---- | --- | ----- | ----- | ---- | ---- |
-| OpenAPI Spec | `/search` endpoint | | | ■ | | [#2](https://github.com/sparkfabrik/nominatim-openapi/issues/2) |
+| OpenAPI Spec | `/search` endpoint | | | | ■ | [#2](https://github.com/sparkfabrik/nominatim-openapi/issues/2) |
+| | `/lookup` endpoint | | | | ■ | [#4](https://github.com/sparkfabrik/nominatim-openapi/issues/4) |
 | | `/reverse` endpoint | | ■ | | | [#3](https://github.com/sparkfabrik/nominatim-openapi/issues/3) |
-| | `/lookup` endpoint | | ■ | | | [#4](https://github.com/sparkfabrik/nominatim-openapi/issues/4) |
 | | `/status` endpoint | | ■ | | | [#5](https://github.com/sparkfabrik/nominatim-openapi/issues/5) |
 | | `/details` endpoint | ■ | | | | |
+| Test suite | | ■ | | | | |
 | Node CLI | | ■ | | | | |
 
 ## Contributing
 
 Any contribution is welcome!
+
 Please read and accept our [Code of Conduct](https://github.com/sparkfabrik/nominatim-openapi/blob/main/CODE_OF_CONDUCT.md),
 then refer to [Contributing Guidelines](https://github.com/sparkfabrik/nominatim-openapi/blob/main/CONTRIBUTING.md) before opening issues or pull requests.
 
@@ -73,12 +77,16 @@ then refer to [Contributing Guidelines](https://github.com/sparkfabrik/nominatim
 First of all, search for issues or open one to share your thoughts, needs or intents with the maintainers and the community.
 Then fork and clone this repo, make your changes, commit and push them on a new branch, finally open a PR against `main` branch of this repo.
 
+Pre-requisites: [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [shasum](https://www.commandlinux.com/man-page/man1/shasum.1.html), [npx](https://www.npmjs.com/package/npx) (node and npm), [docker](https://www.docker.com/).
+
+Editable source of OAS is in `src/` folder. You can validate it running `make validate`. You can bundle it running `make build`.
+
 Please activate the Git Hooks provided in `.githooks/` folder before the first change (hooks are bash scripts). You can simply run `make hooks` to activate them.
-- **pre-commit** - compute sha512 checksum of `nominatim.openapi.json` and write on `nominatim.openapi.json.checksum` file.
-- **pre-push** - verify the `nominatim.openapi.json` checksum against `nominatim.openapi.json.checksum` file.
+- **pre-commit** - validate and bundle OAS spec, compute sha512 checksums.
+- **pre-push** - verify the checksums.
 
 In a Docker-ready environment, you can run `make editor` to have the new Swagger Editor up and running on `http://localhost:8092`.
-Automatic file loading and saving is not available, so you must copy/paste the content of `nominatim.openapi.json` in the editor and then copy/paste it back to save the changes.
+Automatic file loading and saving is not available, so you must copy/paste the content of `src/nominatim.openapi.json` in the editor and then copy/paste it back to save the changes.
 
 <p align="center"><img src="./docs/logo-wide.png" width="50%" /></p>
 
@@ -96,6 +104,16 @@ Latest version: v3.1.0
 
 > The OpenAPI Specification (OAS) is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs. Read more about how you can get control of your APIs now, understand the full API lifecycle and communicate with developer communities inside and outside your organization.
 
+### What is JSON Schema?
+
+Website: https://json-schema.org
+
+Repository: https://github.com/json-schema-org
+
+Latest version: v2020-12
+
+> JSON Schema enables the confident and reliable use of the JSON data format.
+
 ### What is Swagger UI?
 
 Website: https://swagger.io/tools/swagger-ui/
@@ -122,6 +140,22 @@ Repository: https://github.com/osm-search
 
 > Nominatim uses OpenStreetMap data to find locations on Earth by name and address (geocoding). It can also do the reverse, find an address for any location on the planet.
 
+### What is GeoJSON?
+
+Website: https://geojson.org
+
+Repository: https://github.com/geojson
+
+> GeoJSON is a format for encoding a variety of geographic data structures.
+
+### What is GeocodeJSON?
+
+Website: https://github.com/geocoders/geocodejson-spec/tree/master/draft
+
+Repository: https://github.com/geocoders/geocodejson-spec
+
+> This specification attempts to create a standard for handling geocoding results.
+
 ### What is Subresource Integrity (SRI)
 
 Website: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
@@ -138,16 +172,20 @@ Website: https://en.wikipedia.org/wiki/SHA-2
 
 Nominatim (and OpenStreetMap) project have a long story and a non trivial development path, so this OpenAPI specification reflects some features of actual software and official documentation.
 
-- The `format` parameter ([docs](https://nominatim.org/release-docs/develop/api/Search/#output-format)) accepts 5 values (`xml`, `json`, `jsonv2`, `geojson`, `geocodejson`), but only `jsonv2` (the default one) is described by this specification in `components.schemas` (see [Nominatim/issues/1697](https://github.com/osm-search/Nominatim/issues/1697#issuecomment-726232719) and [OpenAPI-Specification/issues/2031](https://github.com/OAI/OpenAPI-Specification/issues/2031) for further informations).
-- In `jsonv2` responses some numeric values are represented by strings for historical reasons (see [this discussion](https://github.com/osm-search/Nominatim/discussions/3115)), so this specification.
+- The `format` parameter ([docs](https://nominatim.org/release-docs/develop/api/Search/#output-format)) accepts 5 values (`xml`, `json`, `jsonv2`, `geojson`, `geocodejson`), where `jsonv2` is the default one, but this specification describes only the `geocodejson` format in `components.schemas` (see [Nominatim/discussions/3115](https://github.com/osm-search/Nominatim/discussions/3115#discussioncomment-6486249), [Nominatim/issues/1697](https://github.com/osm-search/Nominatim/issues/1697#issuecomment-726232719), and [OpenAPI-Specification/issues/2031](https://github.com/OAI/OpenAPI-Specification/issues/2031) for further informations).
 
 ## Open Source Software
 
 This project would not exist without open source, it is open source, and the community behind it contributes to open source.
 
 Here is a list of external contributions (code and discussions) starting from work for this project:
 - fix typos in Nominatim error messages: [Nominatim/pull/3112](https://github.com/osm-search/Nominatim/pull/3112)
-- discussion about `jsonv2` format of Nominatim responses: [Nominatim/discussions/3115](https://github.com/osm-search/Nominatim/discussions/3115)
+- discussion about `jsonv2` and `geocodejson` formats of Nominatim responses: [Nominatim/discussions/3115](https://github.com/osm-search/Nominatim/discussions/3115)
+- proposal of a JSON schema for `geocodejson` spec: [geocodejson-spec/issues/21](https://github.com/geocoders/geocodejson-spec/issues/21)
+- pull request the GeocodeJSON schema: [geocodejson-spec/pull/25](https://github.com/geocoders/geocodejson-spec/pull/25)
+- release of an unofficial schema for [GeocodeJSON](https://semver.org/) format (see [jenkin/json-schema-bricks](https://github.com/jenkin/json-schema-bricks))
+- release of an unofficial schema for [GeoHash](http://geohash.org/) format (see [jenkin/json-schema-bricks](https://github.com/jenkin/json-schema-bricks))
+- release of an unofficial schema for [SemVer](https://semver.org/) format (see [jenkin/json-schema-bricks](https://github.com/jenkin/json-schema-bricks))
 - ...
 
 ## License