Required assertion function for lists of strings

[tatomyr]

Is your feature request related to a problem? Please describe.

Redocly CLI configurable rules allow using the required assertion function to check whether an object contains specified keys.
However, currently there's no way to check if a list contains specific words.

Describe the solution you'd like

Either allow the required assertion to be applied against lists of strings, or introduce a separate assertion function (i.e. contains) which will take a list of required words to check.

Describe alternatives you've considered

Implementing a custom assertion function through a plugin.

Additional context

This came from a real case when we couldn't enforce page and items properties to be set in the required list for a specific kind of schemas:

type: object
properties:
  object:
    type: string
    const: list
  page:
    $ref: ../Page.yaml
  items:
    type: array
    minItems: 0
    items:
      $ref: ./PullRequest.yaml
required:
  - object
  - page # <-- required to be in the `required`
  - items # <-- required to be in the `required`

[lornajane]

I think contains would work well, the values of an array are too different to the keys of an object for us to reuse the keyword. We do already have enum, but would we consider adding containAny to compare with requireAny - so people could for example set a set of entries of which at least one must appear? I'm thinking of the tags array that must have either internal or external, or something like that.

[tatomyr]

Good point on the containsAny! If there's no other suggestions, let's go with yours.

[adamaltman]

And contains would mean it contains them all? I like it.

[tatomyr]

And contains would mean it contains them all?

Yes, the same way the required assertion works.

[adamaltman]

I would increase the priority of this. As I understand a use case is parameter (list) enforcement. For example, requiring certain parameters are defined for getting collections.

[adamaltman]

Here is a look at how we do it:

    subject:
      type: Parameter
      property: name
    assertions:
      pattern: /^(after|before|limit|filter|sort|search)$/
    where:
      - subject:
          type: PathItem
          matchParentKeys: /.*\/\{\w+\}\/\w+(?:-\w+)?$/
        assertions:
          defined: true
      - subject:
          type: Operation
          filterInParentKeys:
            - get
        assertions:
          defined: true
      - subject:
          type: Parameter
          property: in
        assertions:
          const: query
    message: Pagination query must be one of after, before, limit, filter, sort or search

Maybe we should share this to the cookbook and not increase the priority. As I understand contains may actually have a different meaning -- it may allow for something not within the list? Whereas our rule doesn't allow for extra parameters.

[lornajane]

Let's share to the cookbook whether we increase the priority or not!

[Ayush9026]

/assign @Ayush9026 I will solve this.

[jeremyfiel]

I have a similar use case where I want to check if parameters has particular fields defined, and if so, require a schemaProperties in the response body

This was an attempt to help promote Redocly as a solution for a Stack answer. I can't submit this answer because I'm unable to assert query parameters are defined. If I remove the parameter assertion, the rule works as expected

https://stackoverflow.com/questions/78487150/is-it-possible-for-spectral-or-another-tool-to-enforce-query-parameter-respo

 rule/stack:
    where: 
      - subject: 
          type: Operation
          filterInParentKeys: 
            - get
        assertions: 
          defined: true
      - subject: 
          type: ParameterList
        assertions:
          requireAny:  // I'm having an issue with this list. 
            - PaginationOffset
            - PaginationPageSize
            - PaginationSorts
      - subject: 
          type: Response
          filterInParentKeys: 
            - '200'
        assertions: 
          defined: true
      - subject: 
          type: MediaType
          filterInParentKeys: 
            - 'application/json'
        assertions: 
          defined: true
    subject: 
      type: Schema
      property: paginationStats
    assertions: 
      defined: true

openapi: 3.0.3
info:
  title: test
  version: 1
paths:
  /organizations/{organizationId}/childorgs:
      get:
        summary: Returns all child orgs for a given parent org.
        operationId: getChildOrgs
        parameters:
          - name: organizationId
            in: path
            description: The parent organization's ID
            required: true
            schema:
              type: string
          - $ref: '#/components/parameters/PaginationSorts'
          - $ref: '#/components/parameters/PaginationPageSize'
          - $ref: '#/components/parameters/PaginationOffset'
        responses:
          '200':
            description: ok
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    childOrgs:
                      type: array
                      items:
                        $ref: '#/components/schemas/ChildOrg'
                    paginationSats: // misspelled to throw the error
                      $ref: '#/components/schemas/PaginationStats'
components:
  parameters:
    PaginationSorts:
      name: sorts
      in: query
      description: Sorts to apply to the results
      required: false
      schema:
        type: array
        items:
          type: string
    PaginationPageSize:
      name: pageSize
      in: query
      description: Number of items to return per page
      required: false
      schema:
        type: integer
        format: int32
    PaginationOffset:
      name: offset
      in: query
      description: Number of items to skip
      required: false
      schema:
        type: integer
        format: int32
  schemas:
    PaginationStats:
      type: object
      properties:
        totalItems:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32

[jeremyfiel]

I also have a similar use case to Adam's...

If a path uri has a specific pattern, then a specific query parameter must be defined.
Again, I can't reach in the parameters to verify it's existence.

  rule/operation-parameters-meta-must-include-$filter:
    severity: warn
    message: all Meta endpoints MUST define a $filter parameter
    where:
      - subject:
          type: PathItem
          matchParentKeys: 'meta$'
        assertions:
          defined: true
    subject: 
      type: ParameterList
    assertions:
      required:
        - 'query_filter'

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  /thing/meta:
    get:
      parameters:
      - $ref: "#/components/parameters/query_filter"
      responses: 
        '200':
          description: ""
          content: 
            application/json: 
              schema: {}
components: 
  parameters: 
    query_filter:
      name: '$filter'
      in: query
      required: false
      schema:
        type: string

---

Adam's rule works but the error points at all the other parameter definitions whereas I would expect the error to point at the Parameters keyword.