MarquezProject / marquez

Collect, aggregate, and visualize a data ecosystem's metadata
https://marquezproject.ai
Apache License 2.0
1.75k stars 314 forks source link

Open API Spec does not list null as valid values #2009

Open studiosciences opened 2 years ago

studiosciences commented 2 years ago

I'm seeing a discrepancy in the Open API spec and the results. Optional fields should not return null unless that is one of the type options. Either the APIs should return undefined for optional fields, or all fields should be listed as required and null added as a possible return type.

    IncompleteRun:
      type: object
      properties:
        id:
          description: The ID of the run.
          type: string
          format: uuid
        createdAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was created.
          type: string
          format: date-time
        updatedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was updated.
          type: string
          format: date-time
        nominalStartTime:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal start time of the run.
          type: string
          format: date-time
        nominalEndTime:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal end time of the run.
          type: string
          format: date-time
        state:
          description: The current state of the run.
          type: string
          enum: [NEW, RUNNING, COMPLETED, FAILED, ABORTED]
        startedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the start time of the run.
          type: string
          format: date-time
        endedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the end time of the run.
          type: string
          format: date-time
        durationMs:
          type: integer
          description: The total duration of the run. Measured in milliseconds.
        args:
          description: The arguments of the run.
          type: object
        facets:
          $ref: '#/components/schemas/RunFacets'
      example:
        id: 870492da-ecfb-4be0-91b9-9a89ddd3db90
        createdAt: 2019-05-09T19:49:24.201361Z
        updatedAt: 2019-05-09T19:49:24.201361Z
        nominalStartTime: null
        nominalEndTime: null
        state: RUNNING
        startedAt: 2019-05-09T15:17:32.690346
        endedAt: null  #NOTHING ABOVE SAYS THAT THIS CAN BE NULL
        durationMs: null
        args: {'email': 'me@example.com', 'emailOnFailure': 'false', 'emailOnRetry': 'true', 'retries': '1'}
        facets: {}
studiosciences commented 2 years ago

Not actually sure which of these files is nullable, but this does fix our type generation issues:

IncompleteRun:
      type: object
      properties:
        id:
          description: The ID of the run.
          type: string
          nullable: true
          format: uuid
        createdAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was created.
          type: string
          nullable: true
          format: date-time
        updatedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the run was updated.
          type: string
          nullable: true
          format: date-time
        nominalStartTime:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal start time of the run.
          type: string
          nullable: true
          format: date-time
        nominalEndTime:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the nominal end time of the run.
          type: string
          nullable: true
          format: date-time
        state:
          description: The current state of the run.
          type: string
          nullable: true
          enum: [NEW, RUNNING, COMPLETED, FAILED, ABORTED]
        startedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the start time of the run.
          type: string
          nullable: true
          format: date-time
        endedAt:
          description: An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the end time of the run.
          type: string
          nullable: true #ADD NULLABLE TO EVERYTHING
          format: date-time
        durationMs:
          type: integer
          description: The total duration of the run. Measured in milliseconds.
          nullable: true
        args:
          description: The arguments of the run.
          type: object
          nullable: true
        facets:
          $ref: '#/components/schemas/RunFacets'
      required: #ADD REQUIRED LIST
        - id
        - createdAt
        - updatedAt
        - nominalStartTime
        - nominalEndTime
        - state
        - startedAt
        - endedAt
        - durationMs
        - args
      example:
        id: 870492da-ecfb-4be0-91b9-9a89ddd3db90
        createdAt: 2019-05-09T19:49:24.201361Z
        updatedAt: 2019-05-09T19:49:24.201361Z
        nominalStartTime: null
        nominalEndTime: null
        state: RUNNING
        startedAt: 2019-05-09T15:17:32.690346
        endedAt: null
        durationMs: null
        args: {'email': 'me@example.com', 'emailOnFailure': 'false', 'emailOnRetry': 'true', 'retries': '1'}
        facets: {}