Giters

opengeospatial / ogcapi-processes

Home Page:https://ogcapi.ogc.org/processes

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

How can I extend a response schema?

mcucchi9 opened this issue · comments

commented

Hi,

I'm developing an API based upon the OGC API - Processes standard, using the Python framework FastAPI.
I would like to extend the schema of the GET /jobs/{job_id} endpoint's response so that it returns predefined additional fields, and I would also like those additional fields to be shown in the OpenAPI documentation.
Stated in other words, I would like my API to have a response schema for the cited endpoint which is an extension of the schema defined in the OGC API - Processes.

I read in the OGC API - Processes - Part1: Core document, Par. 7.2.2, Note 1:

The term “…​based upon the OpenAPI 3.0 schema…​” used in the requirements of this specification means that OpenAPI 3.0 is used to define:

all the required properties of the respective request/response schema,
and any optional properties of the respective request/response schema.
It also means that unless explicitly excluded these schemas are extensible with additional properties not defined in the schema using the additionalProperties mechanism defined in the OpenAPI 3.0 specification.

From this I assume that, since the GET /jobs/{job_id} endpoint's response schema (statusInfo.yaml) does not explicitly exclude it, I can extend it with additional properties.

Anyway, it is not entirely clear to me how should I use the "additionalProperties" mechanism in this context.

Thanks in advance.

commented

@mcucchi9 yes, you can add additional members to the statusInfo.yaml schema. Compliant OGC API Processes clients will simply ignore the additional fields. You can also add them to the OpenAPI document too ... but again you have to be aware that complaint clients may not recognize your extensions and will ignore them.

commented

Ok, so I can simply define my statusInfo.yaml with an additional myAdditionalField field as follow:

type: object
required:
   - jobID
   - status
   - type
properties:
   processID:
      type: string
   type:
      type: string
      enum:
        - process
   jobID:
      type: string
   status:
      $ref: "statusCode.yaml"
   message:
      type: string
   created:
      type: string
      format: date-time
   started:
      type: string
      format: date-time
   finished:
      type: string
      format: date-time
   updated:
      type: string
      format: date-time
   progress:
      type: integer
      minimum: 0
      maximum: 100
   links:
      type: array
      items:
         $ref: "link.yaml"
   myAdditionalField:
      type: string

and still be compliant to OGC API - Processes, is that correct?

commented

@mcucchi9 yup ... as long as all the fields defined in the specification are there and they are filled in according to the requirements in the specification, you can add anything else you like. The conformance test and compliant clients should simply ignore myAdditionalField.

commented

Perfect, thanks!

commented

If you want to keep the distinction explicit between wihch fields are from OGC API - Processes and the ones provided by your implementation, you can define the schema this way:

allOf: 
  - $ref: https://schemas.opengis.net/ogcapi/processes/part1/1.0/openapi/schemas/statusInfo.yaml
  - type: object
    properties:
      ... # anything you want here
commented

13-NOV-2023: Closing.