Refactored to schema extensions

Makefile

@@ -63,6 +63,7 @@ test-component: ## Runs component test suite
 .PHONY: validate-specification
 validate-specification: ## Validates specification
 	asyncapi validate specification.yml
+	redocly lint ./docs/contract/upstream.yml
 
 .PHONY: help
 help: ## Show help page for list of make targets

README.md

@@ -37,6 +37,7 @@ To run `make validate-specification` you require Node v20.x and to install @asyn
 
 ```sh
    npm install -g @asyncapi/cli
+   npm install -g @redocly/cli
 ```
 
 ### Configuration

ci/scripts/lint.sh

@@ -4,5 +4,6 @@ pushd dp-search-data-extractor
   go install github.com/golangci/golangci-lint/cmd/[email protected]
   make lint
   npm install -g @asyncapi/cli
+  npm install -g @redocly/cli
   make validate-specification
 popd

docs/contract/resource_metadata.yml

@@ -1,102 +1,118 @@
-title: >
-  Resource metadata for search updates, which should be supplied as both
-  a kafka message and as part of a REST API.
-type: object
-properties:
-  uri:
-    type: string
-    description: URI of upstream content item
-    format: uri
-  uri_old:
-    type: string
-    description: >
-      Optional old URI of upstream content item, this will cause the old item
-      to be removed from search.
-  content_type:
-      type: string
-      description: Content type ID, used for aggregations
-      enum:
-      - api_dataset_landing_page
-      - article
-      - article_download
-      - bulletin
-      - compendium_chapter
-      - compendium_data
-      - compendium_landing_page
-      - dataset
-      - dataset_landing_page
-      - home_page
-      - home_page_census
-      - product_page
-      - reference_tables
-      - release
-      - static_adhoc
-      - static_article
-      - static_foi
-      - static_landing_page
-      - static_methodology
-      - static_methodology_download
-      - static_page
-      - static_qmi
-      - taxonomy_landing_page
-      - timeseries
-      - visualisation
-  cdid:
-    type: string
-    description: CDID for content item, typically used with timeseries
-  dataset_id:
-    type: string
-    description: Dataset ID for content item
-  edition:
-    type: string
-  meta_description:
-    type: string
-  release_date:
-    type: string
-    format: date-time
-    description: Release date in an ISO 8601 format
-    example: "2026-02-12T07:00:00.000Z"
-  summary:
-    type: string
-    description: Summary text, typically used in search listings
-  title:
-    type: string
-    description: Title of the content item
-  topics:
-    type: array
-    description: Array of topic IDs taken from Topic API
-    items:
-      type: string
-  cancelled:
-    type: boolean
-    description: Shows if a release has been cancelled, only used with release data_type
-  finalised:
-    type: boolean
-    description: Shows if a release has been finalised, only used with release data_type
-  published:
-    type: boolean
-    description: Shows if a release has been published, only used with release data_type
-  language:
-    type: string
-  survey:
-    type: string
-  canonical_topic:
-    type: string
-  date_changes:
-    type: array
-    description: List of date changes, only used with release data_type
-    items:
+components:
+  schemas:
+    StandardPayload:
+      title: Standard payload for search updates
+      description: Resource metadata for search updates, which should be supplied as both
+          a kafka message and as part of a REST API.
       type: object
       properties:
-        change_notice:
+        uri:
           type: string
-        previous_date:
+          description: URI of upstream content item
+          format: uri
+        uri_old:
           type: string
-  provisional_date:
-    type: string
-    description: A provisional date string, only used with release data_type
-    example: October-November 2024
-required:
-  - uri
-  - title
-  - content_type
+          description: >
+            Optional old URI of upstream content item, this will cause the old item
+            to be removed from search.
+        content_type:
+            type: string
+            description: Content type ID, used for aggregations
+            enum:
+            - api_dataset_landing_page
+            - article
+            - article_download
+            - bulletin
+            - compendium_chapter
+            - compendium_data
+            - compendium_landing_page
+            - dataset
+            - dataset_landing_page
+            - home_page
+            - home_page_census
+            - product_page
+            - reference_tables
+            - release
+            - static_adhoc
+            - static_article
+            - static_foi
+            - static_landing_page
+            - static_methodology
+            - static_methodology_download
+            - static_page
+            - static_qmi
+            - taxonomy_landing_page
+            - timeseries
+            - visualisation
+        cdid:
+          type: string
+          description: CDID for content item, typically used with timeseries
+        dataset_id:
+          type: string
+          description: Dataset ID for content item
+        edition:
+          type: string
+        meta_description:
+          type: string
+        release_date:
+          type: string
+          format: date-time
+          description: Release date in an ISO 8601 format
+          example: "2026-02-12T07:00:00.000Z"
+        summary:
+          type: string
+          description: Summary text, typically used in search listings
+        title:
+          type: string
+          description: Title of the content item
+        topics:
+          type: array
+          description: Array of topic IDs taken from Topic API
+          items:
+            type: string
+        language:
+          type: string
+        survey:
+          type: string
+        canonical_topic:
+          type: string
+      required:
+        - uri
+        - title
+        - content_type
+    ReleasePayload:
+      title: Release payload for search updates
+      description: Resource metadata for search updates, which should be supplied as both
+          a kafka message and as part of a REST API. Only applies to the 'release' content_type
+      type: object
+      allOf: 
+          - $ref: '#/components/schemas/StandardPayload'
+      properties:
+        cancelled:
+          type: boolean
+          description: Shows if a release has been cancelled, only used with release data_type
+        finalised:
+          type: boolean
+          description: Shows if a release has been finalised, only used with release data_type
+        published:
+          type: boolean
+          description: Shows if a release has been published, only used with release data_type
+        date_changes:
+          type: array
+          description: List of date changes, only used with release data_type
+          items:
+            type: object
+            properties:
+              change_notice:
+                type: string
+              previous_date:
+                type: string
+        provisional_date:
+          type: string
+          description: A provisional date string, only used with release data_type
+          example: October-November 2024
+      required:
+        - uri
+        - title
+        - content_type
+

docs/contract/upstream.yml

@@ -1,67 +1,73 @@
-swagger: "2.0"
+openapi: 3.0.0
 info:
   description: ""
   version: "1.0.0"
   title: "Upstream service endpoints"
   license:
     name: "Open Government Licence v3.0"
     url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
-schemes:
-  - "https"
+servers:
+  - url: /
+security: []
 paths:
   /resource:
     get:
       operationId: GetResources
       summary: "Get Resources Endpoint"
       description: "Endpoint for getting all resources that are wanted to be indexed in search"
-      produces:
-        - application/json
       parameters:
         - in: query
           name: limit
           description: "The number of resources requested, defaulted to 10 and limited to 1000."
-          type: integer
+          schema:
+            type: integer
+            default: 10
           required: false
-          default: 10
         - in: query
           name: offset
           description: >
             The offset into the complete ordered set of resources which satisfy the query, which 
             specifies the first resource to return (starting at 0). Use this parameter as a pagination 
             mechanism along with the limit parameter.
-          type: integer
+          schema:
+            type: integer
+            default: 0
           required: false
-          default: 0
       responses:
         200:
-          description: OK
-          schema:
-            $ref: "#/definitions/GetResourceResponse"
+          description: All resources response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Resources"
         400:
           description: Bad Request
         500:
           description: Internal server error
 
-definitions:
-  GetResourcesResponse:
-    type: object
-    properties:
-      count:
-        type: integer
-        description: How many resources are present in the response
-      items: 
-        type: array
-        description: Array containing results.
+components:
+  schemas:
+    Resources:
+      type: object
+      properties:
+        count:
+          type: integer
+          description: How many resources are present in the response
         items: 
-          $ref: './resource_metadata.yml'
-      limit:
-        type: integer
-        description: Max number of items we're returning in this response.
-      offset:
-        type: integer
-        description: >
-          The number of documents into the full list that this particular response is starting at, 
-          this should default to 0 if not set.
-      total_count:
-        type: integer
-        description: How many resources are available in total
+          type: array
+          description: Array containing results.
+          items: 
+            oneOf:
+              - $ref: 'resource_metadata.yml#/components/schemas/StandardPayload'
+              - $ref: 'resource_metadata.yml#/components/schemas/ReleasePayload'
+        limit:
+          type: integer
+          description: Max number of items we're returning in this response.
+        offset:
+          type: integer
+          description: >
+            The number of documents into the full list that this particular response is starting at, 
+            this should default to 0 if not set.
+        total_count:
+          type: integer
+          description: How many resources are available in total

specification.yml

@@ -56,7 +56,9 @@ components:
         Content upstream has been updated. This is the topic for supplying full metadata. It may be
         prioritised in future.
       payload:
-        $ref: './docs/contract/resource_metadata.yml'
+        oneOf:
+          - $ref: './docs/contract/resource_metadata.yml#/components/schemas/ReleasePayload'
+          - $ref: './docs/contract/resource_metadata.yml#/components/schemas/StandardPayload'
     content-updated:
       name: content-updated
       title: Content upstream has been updated