Align OGC API - Processes ruleset with final v2.0 spec (18-062r3)

The Processes rulesets were based on an earlier draft. Reconcile the four
covered conformance classes with the final v2.0 spec:

- Bump conformance-class and requirement URIs from 1.0 to 2.0 (core, job-list,
  json, ogc-process-description).
- Fix requirement identifiers to match the spec (slash -> hyphen for
  process-exception-no-such-process and the job-results-exception-* rules) and
  correct the underscore doc-link anchors.
- Resolve the ogc-process-description v2 schema TODO (point process.yaml at the
  master branch, which tracks 2.0; the schemas.opengis.net 2.0 tree is not
  published yet).
- Drop the execution POST from the JSON media-type rule; v2 no longer lists it
  (execution output is content-negotiated).
- Add the two new statically-checkable requirements: job-result-op-0th (path
  /jobs/{jobID}/results/{outputID}/0) and job-results-exception-no-such-output.
- Add type: object to the example results schema so it validates against the
  v2 results.yaml, and add the /0 path to the example.

Update and extend tests accordingly.

Author: joostfarla

src/specs/ogc-api/examples/processes.json

@@ -250,6 +250,32 @@
           }
         }
       }
+    },
+    "/jobs/{jobID}/results/{outputID}/0": {
+      "get": {
+        "summary": "retrieve the first value of a single result of a job",
+        "description": "Retrieves the first (0th) value of a single output of a job.",
+        "operationId": "getResultOutputValue",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/jobID"
+          },
+          {
+            "$ref": "#/components/parameters/outputID"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/JobResult"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -1049,6 +1075,7 @@
         "additionalProperties": false
       },
       "results": {
+        "type": "object",
         "additionalProperties": {
           "$ref": "#/components/schemas/inlineOrRefData"
         }

src/specs/ogc-api/rulesets/processes-core.test.ts

@@ -169,13 +169,13 @@ describe('/req/core/process-description-success', () => {
   });
 });
 
-describe('/req/core/process-exception/no-such-process', () => {
+describe('/req/core/process-exception-no-such-process', () => {
   test('Fails when process description 404 response is absent', async () => {
     const oasDoc = clone(exampleDoc);
     delete (oasDoc.paths['/processes/{processID}'].get.responses as Record<string, unknown>)['404'];
     const violations = await spectral.run(oasDoc);
 
-    expect(violations).toContainViolation('/req/core/process-exception/no-such-process', 1);
+    expect(violations).toContainViolation('/req/core/process-exception-no-such-process', 1);
   });
 
   test('Fails when process description 404 response schema is invalid', async () => {
@@ -192,7 +192,7 @@ describe('/req/core/process-exception/no-such-process', () => {
 
     const violations = await spectral.run(oasDoc);
 
-    expect(violations).toContainViolation('/req/core/process-exception/no-such-process', 1);
+    expect(violations).toContainViolation('/req/core/process-exception-no-such-process', 1);
   });
 });
 
@@ -389,6 +389,24 @@ describe('/req/core/job-result-op', () => {
   });
 });
 
+describe('/req/core/job-result-op-0th', () => {
+  test('Fails when the 0th job result path is absent', async () => {
+    const oasDoc = clone(exampleDoc);
+    delete (oasDoc.paths as Record<string, unknown>)['/jobs/{jobID}/results/{outputID}/0'];
+    const violations = await spectral.run(oasDoc);
+
+    expect(violations).toContainViolation('/req/core/job-result-op-0th', 1);
+  });
+
+  test('Fails when the 0th job result GET operation is absent', async () => {
+    const oasDoc = clone(exampleDoc);
+    delete (oasDoc.paths['/jobs/{jobID}/results/{outputID}/0'] as Record<string, unknown>).get;
+    const violations = await spectral.run(oasDoc);
+
+    expect(violations).toContainViolation('/req/core/job-result-op-0th#get', 1);
+  });
+});
+
 describe('/req/core/job-results-async-one', () => {
   test('Fails when 200 response is absent', async () => {
     const oasDoc = clone(exampleDoc);
@@ -409,22 +427,32 @@ describe('/req/core/job-results-async-many', () => {
   });
 });
 
-describe('/req/core/job-results-exception/invalid-query-parameter-value', () => {
+describe('/req/core/job-results-exception-invalid-query-parameter-value', () => {
+  test('Fails when 400 response is absent', async () => {
+    const oasDoc = clone(exampleDoc);
+    delete (oasDoc.paths['/jobs/{jobID}/results'].get.responses as Record<string, unknown>)['400'];
+    const violations = await spectral.run(oasDoc);
+
+    expect(violations).toContainViolation('/req/core/job-results-exception-invalid-query-parameter-value', 1);
+  });
+});
+
+describe('/req/core/job-results-exception-no-such-output', () => {
   test('Fails when 400 response is absent', async () => {
     const oasDoc = clone(exampleDoc);
     delete (oasDoc.paths['/jobs/{jobID}/results'].get.responses as Record<string, unknown>)['400'];
     const violations = await spectral.run(oasDoc);
 
-    expect(violations).toContainViolation('/req/core/job-results-exception/invalid-query-parameter-value', 1);
+    expect(violations).toContainViolation('/req/core/job-results-exception-no-such-output', 1);
   });
 });
 
-describe('/req/core/job-results-exception/no-such-job', () => {
+describe('/req/core/job-results-exception-no-such-job', () => {
   test('Fails when 404 response is absent', async () => {
     const oasDoc = clone(exampleDoc);
     delete (oasDoc.paths['/jobs/{jobID}/results'].get.responses as Record<string, unknown>)['404'];
     const violations = await spectral.run(oasDoc);
 
-    expect(violations).toContainViolation('/req/core/job-results-exception/no-such-job', 1);
+    expect(violations).toContainViolation('/req/core/job-results-exception-no-such-job', 1);
   });
 });

src/specs/ogc-api/rulesets/processes-core.ts

@@ -4,14 +4,16 @@ import type { IFunctionResult, RulesetDefinition } from '@geonovum/standards-che
 import { oas3_0 } from './formats';
 import { truthy } from '@geonovum/standards-checker/spectral/functions';
 
-export const OGC_API_PROCESSES_CORE_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core';
+export const OGC_API_PROCESSES_CORE_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/conf/core';
 
 export const OGC_API_PROCESSES_CORE_DOC_URI = 'https://docs.ogc.org/DRAFTS/18-062r3.html#req_core_';
 
+// The v2.0 schemas are not yet published under https://schemas.opengis.net/ogcapi/processes/part1/2.0/
+// (18-062r3 is still a draft), so the `master` branch — which tracks the 2.0 revision — is the live source.
 export const SCHEMAS_URI_PREFIX = 'https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/';
 
 const processesCore: RulesetDefinition = {
-  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/req/core',
+  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/req/core',
   description: 'OGC API - Processes - Part 1: Core - Requirements Class "Core"',
   formats: [oas3_0],
   rules: {
@@ -167,7 +169,7 @@ const processesCore: RulesetDefinition = {
         function: truthy,
       },
     },
-    '/req/core/process-exception/no-such-process': {
+    '/req/core/process-exception-no-such-process': {
       given: '$.paths[?(@property.match(/^\\/processes\\/[^/]+$/))].get.responses',
       message: 'If the operation is executed using an invalid process identifier, the response SHALL be HTTP status code `404`.',
       documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'process-exception-no-such-process',
@@ -401,6 +403,28 @@ const processesCore: RulesetDefinition = {
         function: truthy,
       },
     },
+    '/req/core/job-result-op-0th': {
+      given: '$.paths',
+      message: 'The server SHALL support the HTTP GET operation at the path `/jobs/{jobID}/results/{outputID}/0`.',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-result-op-0th',
+      severity: 'error',
+      then: {
+        function: hasPathMatch,
+        functionOptions: {
+          pattern: '^\\/jobs\\/[^/]+\\/results\\/[^/]+\\/0$',
+        },
+      },
+    },
+    '/req/core/job-result-op-0th#get': {
+      given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results\\/[^/]+\\/0$/))]',
+      message: 'The server SHALL support the HTTP GET operation at the path `/jobs/{jobID}/results/{outputID}/0`.',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-result-op-0th',
+      severity: 'error',
+      then: {
+        field: 'get',
+        function: truthy,
+      },
+    },
     '/req/core/job-results-async-one': {
       given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results\\/[^/]+$/))].get.responses',
       message: 'A successful retrieval of a single result SHALL be reported with HTTP status code `200`.',
@@ -430,10 +454,30 @@ const processesCore: RulesetDefinition = {
         },
       ],
     },
-    '/req/core/job-results-exception/invalid-query-parameter-value': {
+    '/req/core/job-results-exception-invalid-query-parameter-value': {
       given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results$/))].get.responses',
       message: 'If a query parameter has an invalid value, the response SHALL have HTTP status code `400`. {{error}}',
-      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception-invalid-query-parameter-value',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception_invalid-query-parameter-value',
+      severity: 'error',
+      then: [
+        {
+          field: '400',
+          function: truthy,
+        },
+        {
+          field: '400',
+          function: hasSchemaMatch,
+          functionOptions: {
+            schemaUri: SCHEMAS_URI_PREFIX + 'common-core/exception.yaml',
+          },
+        },
+      ],
+    },
+    '/req/core/job-results-exception-no-such-output': {
+      given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results$/))].get.responses',
+      message:
+        'If the operation requests an output identifier that does not exist, the response SHALL have HTTP status code `400`. {{error}}',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception-no-such-output',
       severity: 'error',
       then: [
         {
@@ -449,7 +493,7 @@ const processesCore: RulesetDefinition = {
         },
       ],
     },
-    '/req/core/job-results-exception/no-such-job': {
+    '/req/core/job-results-exception-no-such-job': {
       given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results$/))].get.responses',
       message: 'If the job identifier is invalid, the response SHALL have HTTP status code `404`. {{error}}',
       documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception-no-such-job',
@@ -468,10 +512,10 @@ const processesCore: RulesetDefinition = {
         },
       ],
     },
-    '/req/core/job-results-exception/results-not-ready': {
+    '/req/core/job-results-exception-results-not-ready': {
       given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results$/))].get.responses',
       message: 'If the job is still running, the response SHALL have HTTP status code `404`. {{error}}',
-      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception-results-not-ready',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception_results-not-ready',
       severity: 'error',
       then: [
         {
@@ -487,10 +531,10 @@ const processesCore: RulesetDefinition = {
         },
       ],
     },
-    '/req/core/job-results-exception/results-not-available': {
+    '/req/core/job-results-exception-results-not-available': {
       given: '$.paths[?(@property.match(/^\\/jobs\\/[^/]+\\/results$/))].get.responses',
       message: 'If no outputs are available, the response SHALL have HTTP status code `404`. {{error}}',
-      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception-results-not-available',
+      documentationUrl: OGC_API_PROCESSES_CORE_DOC_URI + 'job-results-exception_results-not-available',
       severity: 'error',
       then: [
         {

src/specs/ogc-api/rulesets/processes-job-list.ts

@@ -3,12 +3,12 @@ import type { RulesetDefinition } from '@geonovum/standards-checker/spectral/cor
 import { oas3_0 } from './formats';
 import { truthy } from '@geonovum/standards-checker/spectral/functions';
 
-export const OGC_API_PROCESSES_JOB_LIST_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/job-list';
+export const OGC_API_PROCESSES_JOB_LIST_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/conf/job-list';
 
 export const OGC_API_PROCESSES_JOB_LIST_DOC_URI = 'https://docs.ogc.org/DRAFTS/18-062r3.html#req_job-list_';
 
 const processesJobList: RulesetDefinition = {
-  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/req/job-list',
+  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/req/job-list',
   description: 'OGC API - Processes - Part 1: Core - Requirements Class "Job list"',
   formats: [oas3_0],
   rules: {

src/specs/ogc-api/rulesets/processes-json.test.ts

@@ -41,14 +41,6 @@ describe('/req/json/definition', () => {
     expect(violations).toContainViolation('/req/json/definition', 1);
   });
 
-  test('Fails when sync execution result does not support media type "application/json".', async () => {
-    const oasDoc = clone(exampleDoc);
-    delete (oasDoc.components.responses.ExecuteSync.content as Record<string, unknown>)[APPLICATION_JSON_TYPE];
-    const violations = await spectral.run(oasDoc);
-
-    expect(violations).toContainViolation('/req/json/definition', 1);
-  });
-
   test('Fails when job status does not support media type "application/json".', async () => {
     const oasDoc = clone(exampleDoc);
     delete (oasDoc.components.responses.JobStatus.content as Record<string, unknown>)[APPLICATION_JSON_TYPE];

src/specs/ogc-api/rulesets/processes-json.ts

@@ -3,22 +3,24 @@ import type { RulesetDefinition } from '@geonovum/standards-checker/spectral/cor
 import { oas3_0 } from './formats';
 import { schema } from '@geonovum/standards-checker/spectral/functions';
 
-export const OGC_API_PROCESSES_JSON_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json';
+export const OGC_API_PROCESSES_JSON_URI = 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/conf/json';
 
 export const OGC_API_PROCESSES_JSON_DOC_URI = 'https://docs.ogc.org/DRAFTS/18-062r3.html#req_json_';
 
 const processesJson: RulesetDefinition = {
-  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/req/json',
+  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/req/json',
   description: 'OGC API - Processes - Part 1: Core - Requirements Class "JSON"',
   formats: [oas3_0],
   rules: {
+    // v2 lists the endpoints that SHALL support application/json as: /, /conformance, /processes,
+    // /processes/{processID}, /jobs/{jobID}. The execution endpoint is intentionally excluded — its
+    // successful output is content-negotiated and need not be JSON.
     '/req/json/definition': {
       given: [
         '$.paths["/"].get.responses.200.content',
         '$.paths["/conformance"].get.responses.200.content',
         '$.paths[?(@property.match(/^\\/processes$/))].get.responses.200.content',
         '$.paths[?(@property.match(/^\\/processes\\/[^/]+$/))].get.responses.200.content',
-        '$.paths[?(@property.match(/^\\/processes\\/[^/]+\\/execution$/))].post.responses.200.content',
         '$.paths[?(@property.match(/^\\/jobs\\/[^/]+$/))].get.responses.200.content',
       ],
       message: '200-responses of the server SHALL support the "application/json" media type. {{error}}',

src/specs/ogc-api/rulesets/processes-ogc-process-description.ts

@@ -3,12 +3,12 @@ import type { RulesetDefinition } from '@geonovum/standards-checker/spectral/cor
 import { oas3_0 } from './formats';
 
 export const OGC_API_PROCESSES_OGC_PROCESS_DESCRIPTION_URI =
-  'http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process-description';
+  'http://www.opengis.net/spec/ogcapi-processes-1/2.0/conf/ogc-process-description';
 
 export const OGC_API_PROCESSES_OGC_PROCESS_DESCRIPTION_DOC_URI = 'https://docs.ogc.org/DRAFTS/18-062r3.html#req_ogc-process-description_';
 
 const processOgcProcessDescription: RulesetDefinition = {
-  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/1.0/req/ogc-process-description',
+  documentationUrl: 'http://www.opengis.net/spec/ogcapi-processes-1/2.0/req/ogc-process-description',
   description: 'OGC API - Processes - Part 1: Core - Requirements Class "OGC Process Description"',
   formats: [oas3_0],
   rules: {
@@ -20,8 +20,9 @@ const processOgcProcessDescription: RulesetDefinition = {
       then: {
         function: hasSchemaMatch,
         functionOptions: {
-          // TODO: Upgrade to v2.0 schema
-          schemaUri: 'https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/process.yaml',
+          // v2.0 process schema. The schemas.opengis.net/.../2.0/ tree is not published yet (draft),
+          // so the `master` branch — which tracks the 2.0 revision — is the live source.
+          schemaUri: 'https://raw.githubusercontent.com/opengeospatial/ogcapi-processes/master/openapi/schemas/processes-core/process.yaml',
         },
       },
     },