feat(functions): expand xor function and add exclusive option for or functionality

Fixes #2396 . This has now been merged with stoplightio:develop containing prior "xor" PR https://github.com/stoplightio/spectral/pull/2614.

Checklist

[X] Tests added / updated
[X] Docs added / updated

Does this PR introduce a breaking change?

[ ] Yes
[X] No

(Just saw JeanArhancet's similar pull request, feat(rulesets): add multiple xor .)

FDX (see below) has extended XOR here to support from 1 to any number of properties. This would match the XOR logical function, that as long as exactly one of the (1 or more) properties is defined, then the rule passes. With just one property defined in the functionOptions, xor becomes redundant with defined function.

Updated error response messages to account for possibility of schema matching any number of properties or schema not matching any of any number of functionOption properties.

Updated functionOptions error messages to show example arrays containing from one to three ("and etc") properties.

Since then can take an array which implements AND-ing of rule requirements, this PR also defines and adds an exclusive (default true) option to XOR function to provide OR behavior. exclusive: false works just like xor for requiring at least one matching property, but then permits more than one matching property as valid and satisfying the rule.

Updated functions documentation for xor changes to allow more than two properties and new exclusive option to permit multiple matches.

Additional context

The Financial Data Exchange (FDX, https://financialdataexchange.org) industry consortium for Open Banking delivers 13 OpenAPI 3.1 files with nearly 17,000 lines, 47 paths, 70 operations and 374 defined schemas, We enforce our FDX API Style Guide using 48 custom spectral rules and 23 overrides over 870 ruleset lines. We wanted to enforce that type was defined for each schema, but a schema can get its type in 3 (or 4) ways: type, $ref, or oneOf . (We are not using allOf to define type.) This was ideal for an unresolved xor rule with properties type, $ref, or oneOf . We initially implemented this as a custom function which met our needs, so are now contributing this to the spectral community. Our rule using our custom xor function:

  fdx-property-type-defined:
    description: A valid type must be set for each property (fdx-schema-type ensures oneOf and $ref entities have type defined)
    message: '{{property}} property has zero or multiple defined types from: "type", "oneOf", "$ref"'
    severity: error
    given:
      - $..properties[*]
    # Do not resolve here so $ref can be used as xor function option
    resolved: false
    then:
      # This uses custom fdx_xor function which enforces XOR for any number of properties ([TODO] spectral xor only allows 2 values)
      function: fdx_xor
      functionOptions:
        properties:
          - type
          - oneOf
          - $ref

Secondly, there is an OR-rule opportunity to ensure that defined schemas contain sufficient documentation, as a style guide requirement. In particular, each schema ought to have its use / purpose described for users, which can be done in any of title, summary, or description fields. This is an ideal place for an or function, since any one of those can provide the required schema documentation text, but two or three of them is also just as valid (or better!). A similar example (also included in this PR's tests), would be requiring a helpful example for a type: string schema, which could be provided by any of format, example, or pattern fields in the API spec, but again more than one is acceptable.

stoplightio / spectral

feat(functions): expand xor function and add exclusive option for or functionality #2616