From 7dbe87c4c272b6adfbb75044cc7f087543784533 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 2 Aug 2021 15:32:05 -0400 Subject: [PATCH 1/2] fix redoc build and cleanup warnings --- .circleci/build-openapi.sh | 3 +-- .circleci/config.yml | 8 +++---- build/index.html | 45 ++++++++++++++++++++++---------------- build/swagger-config.yaml | 10 ++------- core/README.md | 2 +- fragments/filter/README.md | 32 +++++++++++++++++---------- implementation.md | 17 +++++++++----- item-search/README.md | 6 ++++- package.json | 12 +++++----- 9 files changed, 76 insertions(+), 59 deletions(-) diff --git a/.circleci/build-openapi.sh b/.circleci/build-openapi.sh index 6c205a8d..a8843011 100755 --- a/.circleci/build-openapi.sh +++ b/.circleci/build-openapi.sh @@ -9,8 +9,7 @@ FNAMES=`find . -name "openapi.yaml" -not -path "./fragments/*" -not -path "./nod for fin in $FNAMES; do fout=./build/$fin mkdir -p ${fout%/*} - #speccy resolve $fin > $fout - swagger-cli bundle $fin -o $fout -t yaml + openapi bundle --ext yaml --output $fout $fin cp build/index.html ${fout%/*}/ done diff --git a/.circleci/config.yml b/.circleci/config.yml index f7a56114..c7749fe6 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -24,7 +24,7 @@ jobs: validate: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:14 steps: - checkout - save_cache: @@ -44,7 +44,7 @@ jobs: build: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:14 steps: - *restore_repo - *restore_dependencies @@ -58,7 +58,7 @@ jobs: publish: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:14 steps: - *restore_repo - *restore_dependencies @@ -72,7 +72,7 @@ jobs: check-core-changes: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:14 steps: - *restore_repo - *restore_dependencies diff --git a/build/index.html b/build/index.html index 11f95e02..4c067958 100644 --- a/build/index.html +++ b/build/index.html @@ -1,20 +1,27 @@ - - - - - - - STAC API - - -
- - - + + + + + STAC API + + + + + + + + + + + + + + \ No newline at end of file diff --git a/build/swagger-config.yaml b/build/swagger-config.yaml index 707dd08c..1ba7c05b 100644 --- a/build/swagger-config.yaml +++ b/build/swagger-config.yaml @@ -7,13 +7,7 @@ apis: paths: exclude: - "^\/$" - - url: 'build/ogcapi-features/openapi.yaml' - #- url: 'build/ogcapi-features/extensions/transaction/openapi.yaml' - # dereference: - # circular: ignore - url: 'build/item-search/openapi.yaml' - #dereference: - # circular: ignore + - url: 'build/ogcapi-features/openapi.yaml' - url: 'build/ogcapi-features/extensions/version/openapi.yaml' - #dereference: - # circular: ignore + - url: 'build/ogcapi-features/extensions/transaction/openapi.yaml' diff --git a/core/README.md b/core/README.md index 4aee959b..00cccb33 100644 --- a/core/README.md +++ b/core/README.md @@ -55,7 +55,7 @@ The following Link relations should exist in the Landing Page (root). | `root` | `/` | STAC Core | The root URI | | `self` | `/` | OAFeat | Self reference, same as root URI | | `service-desc` | `/api` (recommended) | OAFeat OpenAPI | The OpenAPI service description. Uses the `application/vnd.oai.openapi+json;version=3.0` media type to refer to the OpenAPI 3.0 document that defines the service's API | -| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects +| `child` | various | STAC Core | The child STAC Catalogs & Collections. Provides curated paths to get to STAC Collection and Item objects | Additionally, a `service-doc` endpoint is recommended. diff --git a/fragments/filter/README.md b/fragments/filter/README.md index 297f9940..0f21be8b 100644 --- a/fragments/filter/README.md +++ b/fragments/filter/README.md @@ -147,8 +147,10 @@ The implementation **must** support these conformance classes: It is **recommended** that the implementation also support the Basic Spatial Operators and Basic Temporal Operators classes: -- Basic Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-spatial-operators`) defines the `INTERSECTS` predicate -- Basic Temporal Operators: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-temporal-operators`) defines the `ANYINTERACTS` predicate +- Basic Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-spatial-operators`) + defines the `INTERSECTS` predicate +- Basic Temporal Operators: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:basic-temporal-operators`) + defines the `ANYINTERACTS` predicate Additionally, the implementation **must** support at least one of the "CQL Text" or "CQL JSON" conformance classes that define the CQL format used in the filter parameter: @@ -163,19 +165,25 @@ CQL JSON in POST requests. The Filter Extension defines support for implementing the following conformance classes. Implementation of these is often limited by the operations supported by the implementation's datastore, for example, Elasticsearch does not support the spatial -operations required by the Enhanced Spatial Operators. If implemented for Item Search, the conformance class URI should follow -the same pattern relative to OAFeat CQL. - -- Enhanced Comparison Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-comparison-operators`) defines the `LIKE`, `BETWEEN`, and `IN` operators. It is **recommended** to implement this class. -- Enhanced Spatial Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-spatial-operators`) defines the same operators as OAF Part 3 CQL Enhanced Spatial Operators. -- Enhanced Temporal Operators (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-temporal-operators`) defines the same operators as OAF Part 3 CQL Enhanced Temporal Operators. +operations required by the Enhanced Spatial Operators. If implemented for Item Search, the conformance class +URI should follow the same pattern relative to OAFeat CQL. + +- Enhanced Comparison Operators + (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-comparison-operators`) defines the `LIKE`, + `BETWEEN`, and `IN` operators. It is **recommended** to implement this class. +- Enhanced Spatial Operators + (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-spatial-operators`) defines the + same operators as OAF Part 3 CQL Enhanced Spatial Operators. +- Enhanced Temporal Operators + (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:enhanced-temporal-operators`) defines the + same operators as OAF Part 3 CQL Enhanced Temporal Operators. - Functions (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:functions`) defines the same operators as OAF Part 3 CQL Functions. - Arithmetic: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:arithmetic`) defines the same operators as OAF Part 3 CQL Arithmetic. - Arrays: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:arrays`) defines the same operators as OAF Part 3 CQL Arrays. -- Queryable Operands: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:queryable-operands`) allows the use - of queryables (e.g., properties) in any position of a clause, not just in the first position. This allows predicates - like `property1 == property2` be expressed, whereas the Basic CQL conformance class only requires comparisons against literal - values. +- Queryable Operands: (`https://api.stacspec.org/v1.0.0-beta.2/item-search#filter:queryable-operands`) allows the + use of queryables (e.g., properties) in any position of a clause, not just in the first position. This allows + predicates like `property1 == property2` be expressed, whereas the Basic CQL conformance class only requires + comparisons against literal values. Additionally, if an API implements the OGC API Features endpoint, it is **recommended** that the OAFeat Part 3 Filter, Features Filter, and Basic CQL conformance classes be implemented, which allow use of CQL filters against the diff --git a/implementation.md b/implementation.md index e9ca4451..16f2177c 100644 --- a/implementation.md +++ b/implementation.md @@ -30,8 +30,8 @@ permitting the `If-Match` request header. The datetime parameter used by the Item Search and Features conformance classes allows the same values as the [OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for -either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`) or a closed or single open ended interval that also -uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`). +either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime (e.g., `1990-12-31T23:59:59Z`) +or a closed or single open ended interval that also uses RFC 3339 datetimes (e.g., `1990-12-31T23:59:59Z/..`). RFC 3339 is a profile of ISO 8601, adding these constraints to the allowed values: - a complete representation of date and time (fractional seconds optional). @@ -41,7 +41,7 @@ RFC 3339 is a profile of ISO 8601, adding these constraints to the allowed value A simple regex for an RFC 3339 datetime is: -``` +```regex ^(\d\d\d\d)\-(\d\d)\-(\d\d)(T|t)(\d\d):(\d\d):(\d\d)([,.]\d+)?(Z|([-+])(\d\d):(\d\d))$ ``` @@ -55,8 +55,13 @@ RFC 3339 datetime or an interval) is: 1. uppercase the string (this avoids needing to match on both (t|T) and (z|Z)) 2. split the string on `/` to determine if it is a single datetime or an interval -3. For the single value or each value of the split, check if it is either an open interval (the empty string or `..`), or if it matches the RFC3339 datetime regex. Only one of the interval ends may be open. -5. ISO8601 parse datetime strings using a library such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python), [dateutil](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse) (Python), or [Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into language standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in Python datetime library does not handle `Z` as a timezone. +3. For the single value or each value of the split, check if it is either an open interval (the empty string or `..`), + or if it matches the RFC3339 datetime regex. Only one of the interval ends may be open. +4. ISO8601 parse datetime strings using a library such as [pyiso8601](https://github.com/micktwomey/pyiso8601) (Python), + [dateutil](https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse) (Python), or + [Luxon](https://github.com/moment/luxon/) (JavaScript). Frequently, date libraries built into language + standard libraries do not parse ISO8601 datetimes correctly, for example, the built-in Python datetime + library does not handle `Z` as a timezone. Below are a few examples of valid RFC 3339 datetimes. Note the uses of fractional seconds, the use of `.` or `,` as the fractional seconds separator, Z or z as a timezone, @@ -77,4 +82,4 @@ These are several examples of datetime intervals: - `../1990-12-31T23:59:59Z` - `1990-12-31T23:59:59Z/` - `1990-12-31T23:59:59Z/..` -- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z` \ No newline at end of file +- `1990-12-31T23:59:59Z/1991-12-31T23:59:59Z` diff --git a/item-search/README.md b/item-search/README.md index dfe19efe..8b693e87 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -118,7 +118,11 @@ See [examples](examples.md) for some example requests. Only one of either **intersects** or **bbox** should be specified. If both are specified, a 400 Bad Request response should be returned. -**datetime** The datetime parameter use the same allowed values as the [OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. This allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be found in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling). +**datetime** The datetime parameter use the same allowed values as the +[OAF datetime](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_parameter_datetime) parameter. +This allows for either a single [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) datetime or an +open or closed interval that also uses RFC 3339 datetimes. Additional details about this parameter can be +found in the [Implementation Recommendations](../implementation.md#datetime-parameter-handling). **bbox** Represented using either 2D or 3D geometries. The length of the array must be 2\*n where *n* is the number of dimensions. The array contains all axes of the southwesterly most extent diff --git a/package.json b/package.json index b4fac66f..f7133d0a 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "repository": "https://github.com/radiantearth/stac-api-spec", "license": "Apache-2.0", "scripts": { - "serve": "redoc-cli serve core/openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "serve": "redoc-cli serve $npm_config_class/openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", "check": "npm run check-markdown && npm run check-openapi", "check-markdown": "remark . -f -r .circleci/rc.yaml --ignore-pattern stac-spec/", "check-openapi": "npm run check-openapi-core && npm run check-openapi-commons && npm run check-openapi-ogcapi-features && npm run check-openapi-item-search && npm run check-openapi-fragments", @@ -19,16 +19,16 @@ "check-stac-spec-changes": "git diff --quiet HEAD ${npm_config_compare_to} -- stac-spec" }, "dependencies": { - "@stoplight/spectral": "^5.7.1", - "gh-pages": "^3.1.0", + "@redocly/openapi-cli": "^1.0.0-beta.54", + "@stoplight/spectral": "^5.9.2", + "gh-pages": "^3.2.3", + "redoc-cli": "^0.12.2", "remark-cli": "^8.0.1", "remark-lint": "^7.0.1", "remark-lint-no-html": "^2.0.1", "remark-preset-lint-consistent": "^3.0.1", "remark-preset-lint-markdown-style-guide": "^3.0.1", "remark-preset-lint-recommended": "^4.0.1", - "remark-validate-links": "^10.0.2", - "swagger-cli": "^4.0.4", - "swagger-combine": "^1.3.0" + "remark-validate-links": "^10.0.2" } } From c37dfc512cc2748af60db130453eda28d47185cc Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 3 Aug 2021 09:26:48 -0400 Subject: [PATCH 2/2] re-add redoc config --- build/index.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/build/index.html b/build/index.html index 4c067958..11b22352 100644 --- a/build/index.html +++ b/build/index.html @@ -20,7 +20,12 @@ - +