openapi: Use allOf for contextual description of referenced schemas

- A $ref fully replaces sibling properties and should always be used alone: "Any members other than "$ref" in a JSON Reference object SHALL be ignored." https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3 - See also: https://stackoverflow.com/questions/33565090/json-schema-property-description-and-ref-usage OAI/OpenAPI-Specification#556 OAI/OpenAPI-Specification#1514 swagger-api/swagger-editor#1184 - NOTE: We may need to update the 2DTMS schemas as well with these changes
jerstlouis · Dec 24, 2021 · 9581b68 · 9581b68
1 parent 170c1aa
commit 9581b68
Show file tree

Hide file tree

Showing 9 changed files with 429 additions and 277 deletions.
diff --git a/openapi/ogcapi-tiles-1.bundled.json b/openapi/ogcapi-tiles-1.bundled.json
diff --git a/openapi/schemas/common-geodata/collectionInfo.yaml b/openapi/schemas/common-geodata/collectionInfo.yaml
@@ -61,8 +61,9 @@ properties:
  - http://www.opengis.net/def/crs/OGC/1.3/CRS84
  - http://www.opengis.net/def/crs/EPSG/0/4326
  dataType:
- description: Type of data represented in the collection
- $ref: '../../schemas/common-geodata/dataType.yaml'
+ allOf:
+ - description: Type of data represented in the collection
+ - $ref: '../../schemas/common-geodata/dataType.yaml'
  geometryDimension:
  description: 'The geometry dimension of the features shown in this layer (0: points, 1: curves, 2: surfaces, 3: solids), unspecified: mixed or unknown'
  type: integer

diff --git a/openapi/schemas/tms/geospatialData.yaml b/openapi/schemas/tms/geospatialData.yaml
@@ -19,8 +19,9 @@ properties:
  description: Unique identifier of the Layer. Implementation of 'identifier'
  type: string
  dataType:
- description: Type of data represented in the layer
- $ref: '../common-geodata/dataType.yaml'
+ allOf:
+ - description: Type of data represented in the layer
+ - $ref: '../common-geodata/dataType.yaml'
  geometryDimension:
  description: 'The geometry dimension of the features shown in this layer (0: points, 1: curves, 2: surfaces, 3: solids), unspecified: mixed or unknown'
  type: integer
@@ -40,8 +41,9 @@ properties:
  description: Category where the layer can be grouped
  type: string
  crs:
- description: Coordinate Reference System (CRS)
- $ref: '../common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS)
+ - $ref: '../common-geodata/crs.yaml'
  epoch:
  description: Epoch of the Coordinate Reference System (CRS)
  type: number
@@ -64,28 +66,33 @@ properties:
  description: TileMatrix identifier associated with the maxScaleDenominator
  type: string
  boundingBox:
- description: Minimum bounding rectangle surrounding the layer
- $ref: '2DBoundingBox.yaml'
+ allOf:
+ - description: Minimum bounding rectangle surrounding the layer
+ - $ref: '2DBoundingBox.yaml'
  created:
- description: When the layer was first produced
- $ref: '../common-geodata/timeStamp.yaml'
+ allOf:
+ - description: When the layer was first produced
+ - $ref: '../common-geodata/timeStamp.yaml'
  updated:
- description: Last layer change/revision
- $ref: '../common-geodata/timeStamp.yaml'
+ allOf:
+ - description: Last layer change/revision
+ - $ref: '../common-geodata/timeStamp.yaml'
  style:
- description: Style used to generate the layer in the tileset
- $ref: 'style.yaml'
+ allOf:
+ - description: Style used to generate the layer in the tileset
+ - $ref: 'style.yaml'
  geoDataClasses:
  description: URI identifying a class of data contained in this layer (useful
  to determine compatibility with styles or processes)
  type: array
  items:
  type: string
  propertiesSchema:
- description: Properties represented by the features in this layer. Can be
- the attributes of a feature dataset (datatype=geometries) or the rangeType
- of a coverage (datatype=coverage)
- $ref: 'propertiesSchema.yaml'
+ allOf:
+ - description: Properties represented by the features in this layer. Can be
+ the attributes of a feature dataset (datatype=geometries) or the rangeType
+ of a coverage (datatype=coverage)
+ - $ref: 'propertiesSchema.yaml'
  links:
  description: 'Links related to this layer. Possible link ''rel'' values are:
  ''geodata'' for a URL pointing to the collection of geospatial data.'

diff --git a/openapi/schemas/tms/tileMatrix.yaml b/openapi/schemas/tms/tileMatrix.yaml
@@ -44,11 +44,12 @@ properties:
  - bottomLeft
  default: topLeft
  pointOfOrigin:
- description: Precise position in CRS coordinates of the corner of origin (e.g.
- the top-left corner) for this tile matrix. This position is also a corner
- of the (0, 0) tile. In previous version, this was 'topLeftCorner' and 'cornerOfOrigin'
- did not exist.
- $ref: '2DPoint.yaml'
+ allOf:
+ - description: Precise position in CRS coordinates of the corner of origin (e.g.
+ the top-left corner) for this tile matrix. This position is also a corner
+ of the (0, 0) tile. In previous version, this was 'topLeftCorner' and 'cornerOfOrigin'
+ did not exist.
+ - $ref: '2DPoint.yaml'
  tileWidth:
  type: number
  description: Width of each tile of this tile matrix in pixels

diff --git a/openapi/schemas/tms/tileMatrixSet-item.yaml b/openapi/schemas/tms/tileMatrixSet-item.yaml
@@ -15,8 +15,9 @@ properties:
  type: string
  format: uri
  crs:
- description: Coordinate Reference System (CRS)
- $ref: '../../schemas/common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS)
+ - $ref: '../../schemas/common-geodata/crs.yaml'
  links:
  description: Links to related resources. A 'self' link to the tile matrix set definition is required.
  type: array

diff --git a/openapi/schemas/tms/tileMatrixSet.yaml b/openapi/schemas/tms/tileMatrixSet.yaml
@@ -34,16 +34,17 @@ properties:
  items:
  type: string
  crs:
- description: Coordinate Reference System (CRS)
- $ref: '../common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS)
+ - $ref: '../common-geodata/crs.yaml'
  wellKnownScaleSet:
  description: Reference to a well-known scale set
  type: string
  format: uri
  boundingBox:
- description: Minimum bounding rectangle surrounding the tile matrix set, in the
- supported CRS
- $ref: '2DBoundingBox.yaml'
+ allOf:
+ - description: Minimum bounding rectangle surrounding the tile matrix set, in the supported CRS
+  - $ref: '2DBoundingBox.yaml'
  tileMatrices:
  type: array
  description: Describes scale levels and its tile matrices

diff --git a/openapi/schemas/tms/tilePoint.yaml b/openapi/schemas/tms/tilePoint.yaml
@@ -9,8 +9,9 @@ properties:
  items:
  type: number
  crs:
- description: Coordinate Reference System (CRS) of the coordinates
- $ref: '../common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS) of the coordinates
+ - $ref: '../common-geodata/crs.yaml'
  tileMatrix:
  description: TileMatrix identifier associated with the scaleDenominator
  type: string

diff --git a/openapi/schemas/tms/tileSet-item.yaml b/openapi/schemas/tms/tileSet-item.yaml
@@ -10,20 +10,21 @@ properties:
  description: A title for this tileset
  type: string
  dataType:
- description: Type of data represented in the tileset
- $ref: '../../schemas/common-geodata/dataType.yaml'
+ allOf:
+ - description: Type of data represented in the tileset
+ - $ref: '../../schemas/common-geodata/dataType.yaml'
  crs:
- description: Coordinate Reference System (CRS)
- $ref: '../../schemas/common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS)
+ - $ref: '../../schemas/common-geodata/crs.yaml'
  tileMatrixSetURI:
  description: Reference to a Tile Matrix Set on an offical source for Tile Matrix
  Sets such as the OGC NA definition server (http://www.opengis.net/def/tms/).
  Required if the tile matrix set is registered on an open official source.
  type: string
  format: uri
  links:
- description: |
- Links to related resources. A 'self' link to the tileset
+ description: Links to related resources. A 'self' link to the tileset
  as well as a 'http://www.opengis.net/def/rel/ogc/1.0/tiling-scheme' link
  to a definition of the TileMatrixSet are required.
  type: array

diff --git a/openapi/schemas/tms/tileSet.yaml b/openapi/schemas/tms/tileSet.yaml
@@ -45,8 +45,9 @@ properties:
  items:
  type: string
  dataType:
- description: Type of data represented in the tileset
- $ref: '../common-geodata/dataType.yaml'
+ allOf:
+ - description: Type of data represented in the tileset
+ - $ref: '../common-geodata/dataType.yaml'
  tileMatrixSetLimits:
  description: Limits for the TileRow and TileCol values for each TileMatrix in
  the tileMatrixSet. If missing, there are no limits other that the ones imposed
@@ -56,34 +57,39 @@ properties:
  items:
  $ref: 'tileMatrixLimits.yaml'
  crs:
- description: Coordinate Reference System (CRS)
- $ref: '../common-geodata/crs.yaml'
+ allOf:
+ - description: Coordinate Reference System (CRS)
+ - $ref: '../common-geodata/crs.yaml'
  epoch:
  description: Epoch of the Coordinate Reference System (CRS)
  type: number
  boundingBox:
- description: Minimum bounding rectangle surrounding the tile matrix set, in the
- supported CRS
- $ref: '2DBoundingBox.yaml'
+ allOf:
+ - description: Minimum bounding rectangle surrounding the tile matrix set, in the supported CRS
+  - $ref: '2DBoundingBox.yaml'
  created:
- description: When the Tile Set was first produced
- $ref: '../common-geodata/timeStamp.yaml'
+ allOf:
+ - description: When the Tile Set was first produced
+ - $ref: '../common-geodata/timeStamp.yaml'
  updated:
- description: Last Tile Set change/revision
- $ref: '../common-geodata/timeStamp.yaml'
+ allOf:
+ - description: Last Tile Set change/revision
+ - $ref: '../common-geodata/timeStamp.yaml'
  layers:
  minItems: 1
  type: array
  items:
  $ref: 'geospatialData.yaml'
  style:
- description: Style involving all layers used to generate the tileset
- $ref: 'style.yaml'
+ allOf:
+ - description: Style involving all layers used to generate the tileset
+ - $ref: 'style.yaml'
  centerPoint:
- description: Location of a tile that nicely represents the tileset. Implementations
- may use this center value to set the default location or to present a representative
- tile in a user interface
- $ref: 'tilePoint.yaml'
+ allOf:
+ - description: Location of a tile that nicely represents the tileset. Implementations
+ may use this center value to set the default location or to present a representative
+ tile in a user interface
+ - $ref: 'tilePoint.yaml'
  tileMatrixSetURI:
  description: Reference to a Tile Matrix Set on an offical source for Tile Matrix
  Sets such as the OGC NA definition server (http://www.opengis.net/def/tms/).