Test definitions point at a Response Object where an OAS schema path is expected #200

Problem description

In all four code/Test_definitions/*.feature files, the 200-response schema steps read:

And the response body complies with the 200RetrieveIdentifier schema at "#/components/responses/200RetrieveIdentifier"

31 steps are affected: 10 in device-identifier-matchIdentifier.feature and 7 in each of the three device-identifier-retrieve*.feature files.

#/components/responses/200RetrieveIdentifier resolves to an OpenAPI Response Object (description, headers, content), not to a schema. The Testing Guidelines step takes an OAS schema JSON path; the schema for this response is one level further down, at #/components/responses/200RetrieveIdentifier/content/application~1json/schema.

This is a follow-on to #194. The four 200-response bodies (200RetrieveIdentifier, 200RetrieveType, 200RetrievePPID, 200MatchIdentifier) are declared as inline allOf composites under components/responses and have never had a named schema, so the previous #/components/schemas/200RetrieveIdentifier paths pointed at a node that does not exist. #194 moved the pointers to a node that does exist, but not to a schema node.

Reference — Commonalities r4.3 Testing Guidelines, "response schema validations", which lists two accepted forms for this step: https://github.com/camaraproject/Commonalities/blob/r4.3/documentation/API-Testing-Guidelines.md

Expected behavior

Give the four 200-response bodies named schemas and point the steps at those, e.g.:

  responses:
    200RetrieveIdentifier:
      description: A physical device identifier has been found for the specified mobile device subscription
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RetrieveIdentifierResponse'
          examples:
            ...
  schemas:
    RetrieveIdentifierResponse:
      required:
        - lastChecked
        - imei
      allOf:
        - $ref: '#/components/schemas/CommonResponseBody'
        - $ref: '#/components/schemas/DeviceIdentifier'
        - $ref: '#/components/schemas/DeviceType'

with the 31 steps then reading:

And the response body complies with the OAS schema at "#/components/schemas/RetrieveIdentifierResponse"

This matches how other CAMARA API repositories are structured — the 200 response body schema is named in components/schemas and $refed from components/responses — and it makes the response bodies nameable in generated documentation. It does not change the wire contract, so it is not a breaking change for API consumers. It touches the API definition as well as the test definitions, and is worth doing before the initial public release.

Alternative solution

Leave the response bodies inline and use the implicit form of the step:

And the response body complies with the OAS schema for this operation and status code

This is the other form listed in the Testing Guidelines, and it is the one intended for a response whose schema is declared inline: there is no path to resolve and none to keep in sync. It is the smaller change, confined to the four .feature files, but it leaves the response bodies unnamed and this repository structured differently from other CAMARA API repositories.

Additional context

Two smaller items in the same steps, worth fixing alongside either option:

• The step phrase complies with the 200RetrieveIdentifier schema at is specific to this repository. The Testing Guidelines and other CAMARA API repositories use complies with the OAS schema at.
• The oas_spec_schema column of the ..._device_identifiers_not_schema_compliant Examples tables still uses paths without the leading # (/components/schemas/PhoneNumber), while the inline steps now use #/... — 16 rows across the four files.