OpenAPIKit Validation (a novel approach?)


I am closing in on a potential implementation for an open-ended validation suite as part of OpenAPIKit. The feature hardly needs motivation, but the approach could use feedback both in how I am executing the validations and in the API I have created for specifying what "validity" means.

The reason I am reaching out to the community is to hopefully get a bit of feedback on the approach before I commit to it more than I already have. It can be difficult to draw review attention on a niche project like this, so hopefully I can cash in on the fact that OpenAPIKit is incubating with the WG and also offer my debt in return, to be reclaimed at a future date when you yourself are seeking out peer review of an idea! You also get my gratitude, but what's that really worth?

What have I created

I have created a suite of types and functions that allow the user of OpenAPIKit to define arbitrary rules to impose on an OpenAPI document for it to be considered valid. These rules are applied by a new validate() function on the OpenAPI.Document type. There are some free rules available to fill gaps in what the Swift type system is able to mandate about an OpenAPI document, but the real girth of this feature-set is the ability to define new validation rules.

Why is it (maybe) interesting

Two reasons, primarily:

  1. I am (mis)-using the fact that OpenAPIKit defines an Encodable interface for the entire OpenAPI document to base a validation suite on the pre-existing tendency of encoding via Encodable to visit all parts of an OpenAPI document. This leads to a validation technique much like one that would be employed by defining visitor behavior against an AST in various AST-based transformation suites that exist for other languages. It also has the nice side-effect of the location in the OpenAPI document always being available to a validation function in the form of the CodingKey array exposed during encoding.
    I've done this by creating a vey simple Encoder and although I've written it into the OpenAPIKit library there is actually very little about it that makes it specialized for this purpose; I could see it being applied elsewhere without too many changes.
  2. I have made liberal use of KeyPaths and operator & function overloads to create a syntax for building out validation rules that I've quickly grown used to; I could easily imagine this API being ugly to some readers and possibly even an objectively bad idea (I hope not, though).

Where can you start

The draft PR lives here. I would love feedback, either left on the PR or in this thread. If you are at all interested in the API for defining validation rules, you may want to start with the documentation for the new feature. If you are more interested in how I've used Encodable, you may want jump straight to the code.


Thanks in advance if you have time to check this out, but obviously we are all busy and this post is really just about providing the opportunity to those with interest in reviewing!


1 Like