Invalid `examples` syntax in the `filters` parameter

[datsirul]

The model endpoint files define the filters parameter with an examples such as:

Existing Syntax:

examples:
  -   - variantcaller:GATK4.0

or

examples:
  -   - NCIT:C3222
  -   - OBI:0100058
      - NCIT:C4813

Here are all the locations this invalid syntax can be found: https://github.com/search?q=repo%3Aga4gh-beacon%2Fbeacon-v2%20%22-%20%20%20-%22&type=code

Corrected Syntax: The correct syntax for an array example should be:

example: [variantcaller:GATK4.0]

or

example: [NCIT:C3222, OBI:0100058, NCIT:C4813]

Reference: OpenAPI Specification - Adding Examples

Note: After fixing the .yaml files, the .json should be fixed as well by running the schema conversion script located in the bin folder.

[mbaudis]

That is valid YAML and preferable over mixing indented lists and bracket annotations (there is an argument to be made for added newlines for new levels but YMMV). +1 for reminding of the correct way to edit YAML then convert; but the conversion script - which also serves as a syntax test- is happy with the current style, too. Sent from my iPhoneOn 10 Jul 2024, at 21:28, Daniel Tsirulnikov @.***> wrote: The model endpoint files define the filters parameter with an examples such as: Existing Syntax: examples:

• • variantcaller:GATK4.0 or examples:
• • NCIT:C3222
• • OBI:0100058
    • NCIT:C4813 Here are all the locations this invalid syntax can be found: https://github.com/search?q=repo%3Aga4gh-beacon%2Fbeacon-v2%20%22-%20%20%20-%22&type=code Corrected Syntax: The correct syntax for an array example should be: example: [variantcaller:GATK4.0] or example: [NCIT:C3222, OBI:0100058, NCIT:C4813] Reference: OpenAPI Specification - Adding Examples Note: After fixing the .yaml files, the .json should be fixed as well by running the schema conversion script located in the bin folder.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: @.***>

[datsirul]

Thank you @mbaudis. Some context - this was identified as part of the work we're doing to use the schema files with code generators. This syntax error is one we observed when trying to generate code based on the files.

To better illustrate the issue:

The current /analyses/endpoints.yaml file has the following code, and when opening the file in VSCode and having this extension installed, which verifies the OpenAPI syntax, we get the following error:

    filters:
      name: filters
      in: query
      schema:
        type: array
        items:
          type: string
        examples: # <-- Error: Property examples is not allowed. (yaml-schema: OpenAPI 3.0.X)
          -   - variantcaller:GATK4.0

As noted, the examples property is invalid there. If I de-indent it to be under filters, this shows another error:

    filters:
      name: filters
      in: query
      schema:
        type: array
        items:
          type: string
      examples:
          -   - variantcaller:GATK4.0 # <-- Error: Incorrect type. Expected "object(OpenAPI 3.0.X)". (yaml-schema: OpenAPI 3.0.X)

Because of the invalid syntax, this is a blocking issue for code generators like OpenAPI Generator which shows the following error and does not work:

Errors: 
        -attribute components.parameters.filters.[filters].schemas.examples is unexpected

For the examples be valid you would need to do something like this:

    filters:
      name: filters
      in: query
      schema:
        type: array
        items:
          type: string
      examples:
          example1:
             value: [variantcaller:GATK4.0]

Or change the examples to example.

[redmitry]

The Json Schema spec. defines "examples" as an array of values. In this case it is an array of arrays. The problem where you wanna put the examples:

Json Schema:

filters:
    name: filters
    in: query
    schema:
        type: array
        items:
            type: string
        examples:
            -  - variantcaller:GATK4.0
               - variantcaller:GATK3.7

or OpenAPI parameter:

filters:
    name: filters
    in: query
    schema:
        type: array
        items:
            type: string
    example:
        - variantcaller:GATK4.0
        - variantcaller:GATK3.7

IMO should be the OpenAPI, as I don't believe tools analyze the schema for examples.

Correction: Perfectly valid:

filters:
    name: filters
    in: query
    schema:
        type: array
        items:
            type: string
    examples:
        example1:
            description: some example
            value: [variantcaller:GATK4.0]

[mbaudis]

@datsirul @redmitry (Deleted earlier comment because not the right place for "kill OpenAPI" discussions here)

Oh well, for now it is probably best to fix the examples to the OpenAPI style, in the endpoints files only. But it is another argument for getting rid of OpenAPI and stick to JSON schema.