OpenAPI Definition Document Validation Failures

Steven Cinquegrana
Steven Cinquegrana
Tenth Anniversary Kudos 2 Name Dropper Participant
in SKY Developer General Discussions

We make use of the OpenAPI (aka Swagger) Definitions to generate client side code.

We've noticed recently that using later versions of the OpenAPI Code Generators, around half of the definitions fail validation.

We've narrowed down the cause to the same issues within each definition: Missing array items type/ref schemas.

Correctly formed array definitions for responses, paramaters and properties look like this:

"type": "array",
"items": {
"type": "string"
}

or

"type": "array",
"items": {
"$ref": "#/definitions/CustomField"
}

However, the API Definitions listed below are missing the items elements, usually globally within the document.

The relevant documents failing validation are:

Church Volunteer, Communication Preference, Constituent, Event, Fundraising, Gift, NXT Data Integration, Opportunity and Statistical Unit.

Or, looking at it the other way around, the following definitions pass validation:

Accounts Payable, General Ledger, Gift Batch, Gift v2, List, One Roster, Payments, School, Treasury and Webhook.

The validator error looks like this (for the Event API definition):

Validation failed. /paths/v1/events/{event_id}/participants/get/parameters/participation_level is an array, so it must include an "items" schema

(Only the first-found error is detailed.)

The fix is quite simple; just add in the items type/ref definitions, even if they're just string. (We currently manually modify the definition documents to add the items definitions.)

Anyway, I'm asking whether these definitions might be corrected at some point. I'm happy to provide further information if necessary.

Thanks.

Steve Cinquegrana | CEO and Principal Developer | Protégé Solutions

Comments

  • Ben Regier
    Ben Regier
    Sixth Anniversary Kudos 5 Name Dropper Participant

    Interesting. I've seen validation errors with some of these definitions as well but didn't know what the issue was. Good to know I can fix it for my own use if I need to.

  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant

    @Ben Regier This does the trick:

    ' Fix missing array items schemas
    sFileContents = sFileContents.Replace("""type"": ""array""
    }", """type"": ""array"",
    ""items"": {
    ""type"": ""string""}
    }")

    Looks a bit messy but this maintains the document formatting, indenting, etc. (Community posts no longer support a code format type unfortunately.)

  • Daniel Leonard
    Daniel Leonard Blackbaud Employee
    Eighth Anniversary Kudos 2 Name Dropper Participant

    @Steven Cinquegrana This is a known issue. We are reaching out to the vendor again to check the status of the issue.

  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant

    @Daniel Leonard Ok, thanks. Could you post here if/when there's any update? From our POV we'd prefer that there're not any breakages to the rest of the definitions if possible. Cheers.

  • Daniel Leonard
    Daniel Leonard Blackbaud Employee
    Eighth Anniversary Kudos 2 Name Dropper Participant

    @Steven Cinquegrana We will update this post when we hear something

  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant

    @Daniel Leonard Hi. I've noticed that many of the specs have been updated, and mostly fixed. Obviously, that's a good thing. Thanks.

    One new issue that has arisen with later code generator versions is that nullable type are not being supported by default (since about mid-2019) and the SKY specs are not currently specifying nullables with x-nullable (being OpenAPI v2.0 specs).

    An example is the VendorPaymentDefault credit_limit property:

    "VendorPaymentDefault": {
    "description": "Vendor Information.",
    "required": [
    "payment_method",
    "payment_option"
    ],
    "type": "object",
    "properties": {
    …
    "credit_limit": {
    "format": "double",
    "description": "The credit limit, if any.",
    "type": "number",
    "x-ms-summary": "Credit limit"
    },

    Generated C# code looks like this:

    public VendorPaymentDefault( … double creditLimit = default(double), …

    Note that this property is specified as type number and format double. But the API can return null values which break the generated code.

    Adding a x-nullable = true directive results in correctly generated code:

    "credit_limit": {
    "format": "double",
    "description": "The credit limit, if any.",
    "type": "number",
    "x-nullable": true,
    "x-ms-summary": "Credit limit"

    public VendorPaymentDefault( … double? creditLimit = default(double?), …

    Is there any chance that these directives can be added to the specifications where appropriate, that is, wherever a returning value can be null and the type is not intrinsically nullable? Currently, we're pre-processing the definitions to add these directives which seems a bit extreme.

    Cheers,

    Steve Cinquegrana | CEO and Principal Developer | Protégé Solutions

    PS The General Ledger definition has an error at line 6057 where the description doesn't include a string or the required schema:

    "400": {
    "description": "",

    It should look something like this:

    "400": {
    "description": "Returned when the request is not in the correct format.",
    "schema": {
    "$ref": "#/definitions/DomainErrorMessage"
    }

  • Daniel Leonard
    Daniel Leonard Blackbaud Employee
    Eighth Anniversary Kudos 2 Name Dropper Participant

    @Steven Cinquegrana I have forwarded the information to the team that owns those API's. We will reply here when we have more information.

Categories