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

[cuttingclyde]

Fixes #2396 . This has now been merged with stoplightio:develop containing prior "xor" PR #2614.

Checklist

• Tests added / updated
• Docs added / updated

Does this PR introduce a breaking change?

• Yes
• 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.

[cuttingclyde]

This has now been merged with stoplightio:develop containing prior "xor" PR #2614, "feat(rulesets): add multiple xor", and rest of spectral develop branch.
I've fixed the CircleCI linting issue on PR title, it remains on commit titles.

[frankkilcommins]

Hi @cuttingclyde,

I appreciate that this started as an expand of XOR functionality and evolved as #2614 was merged.

XOR - as in exclusive or has an expected behaviour within programming languages. The remaining part of this proposal adds a exclusive boolean property (defaulting to true) which if set to false introduces non-exclusive behaviour so that the function can work as OR type behaviour.

It would be cleaner, more maintainable, and more usable to introduce a new or core function which offers this behaviour rather than misusing XOR and effectively negating the 'X' part.

Could you rework this and instead add a new core OR function?

[cuttingclyde]

That’s my recollection of what I had done, was also create the OR function in that same branch. I’ll try to look at it later today. - Clyde On Dec 17, 2024, at 9:34 AM, Frank Kilcommins notifications-at-github.com |GitHub-cuttingus| ***@***.***> wrote:  Hi @cuttingclyde<https://github.com/cuttingclyde>, I appreciate that this started as an expand of XOR functionality and evolved as #2614<#2614> was merged. XOR - as in exclusive or has an expected behaviour within programming languages. The remaining part of this proposal adds a exclusive boolean property (defaulting to true) which if set to false introduces non-exclusive behaviour so that the function can work as OR type behaviour. It would be cleaner, more maintainable, and more usable to introduce a new or core function which offers this behaviour rather than misusing XOR and effectively negating the 'X' part. Could you rework this and instead add a new core OR function? — Reply to this email directly, view it on GitHub<#2616 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ACUFXTYNGDHJ3FWS7HZMIAD2GBABFAVCNFSM6AAAAABRXVTKGCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNBYG43TKMZVHA>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[cuttingclyde]

Oh, I see what you mean. I had done that (separate OR function) in an earlier commit, then reduced it to the combined version in the latest. I’ll look back at the earlier commits and restore the OR one. - Clyde

[cuttingclyde]

@frankkilcommins , Created new PR #2765 from new branch, containing code reverted back to the state where OR function was added and both OR and XOR can take any unlimited number of properties.

I will close this PR with this comment.

This branch can also now be deleted, but I will leave it for now in case @frankkilcommins wants to compare it with the new branch for PR 2765.