OpenAPI Specs in KDL

[esoterra]

I think KDL might be a good format for writing OpenAPI specs that's cleaner than JSON and less indent-reliant and complicated than XML. Is anyone else looking into this?

[zkat]

I love this idea :o

[Monkatraz]

I've been thinking about this too. OpenAPI spec is just a cousin of JSON schemas, so if you were to do an OpenAPI KDL format, it would also serve as a near direct basis for doing JSON schemas, which is interesting.

Although, really, if you were to make a KDL format for OpenAPI it should probably take advantage of the more XML-like KDL features and not just be a cleaner looking JSON. As long as that format converts nicely into a OpenAPI JSON, it should be fairly easy to integrate with all the existing tooling, thankfully.

[esoterra]

I agree about taking advantage of KDL features and being more than just "cleaner looking JSON" and I think there will be opportunities to do more than just directly encoding OpenAPI json in KDL. Like you said, as long as it can be converted into an OpenAPI JSON, we have some flexibility to choose how things map into KDL so that the specs are easy to read and write.

[esoterra]

I'd like to collect some practical OpenAPI spec examples and then rewrite them in KDL as a way of experimenting with how it would get mapped. Does anyone know of a good source for good example specs?

[Monkatraz]

The OpenAPI spec repository actually comes with examples. The most famous and recognizable spec is the pet store one, so I'd start there.

[esoterra]

I think this project will inherently involve answering a lot of questions about writing JSON schemas in KDL generally.
One sort of "big question" that I'm wondering about is how $refs should be translated into KDL.
An option I think is really interesting and might make spec writing very KDL-idiomatic would be to use KQL instead of URIs to identify schema refs.

Example

Here's a naive stab at what that might look like from the pet store example.

...
webhooks {
   newPet {
      post {
         requestBody {
            ...
            content "application/json" schema=r#"components > schema [val() = "Pet"]"#
            ...
         }
      }
   }
}

components {
   schema Pet {
      require id name

      property id type="integer" format="int64"
      property name type="string"
      property tag type="string"
   }
}

Translation

The translator would need to determine what schema is being referenced and what its URI will be post translation.
That value then gets used to populate the "$ref": ... in the location where the KQL was used.

Independent of how queries are themselves structured (which we can make a separate thread for), how do people think KDL document location should be identified and referenced for things like $ref?

[Monkatraz]

Considering the ubiquity of $ref, I'd either leave $ref alone or provide an equivalent shorthand (e.g. typing out #/components/schemas/ every time is verbose and annoying). It has to be translated back into JSON anyhow, so whatever replacement syntax anyone comes up with will have to somehow translate into $ref.

Now, KQL could be used to merge schemas automatically, which could be interesting. One common issue with OpenAPI specs is that you can't extend a schema easily, which causes a lot of workarounds.

UserIdentity:
  description: Basic level of information needed to describe a user.
  type: object
  required: [id, username, karma, tinyavatar, role]
  properties:
    id:         { $ref: '#/components/schemas/Reference' }
    username:   { $ref: '#/components/schemas/Username' }
    tinyavatar: { allOf: [$ref: '#/components/schemas/Base64'], nullable: true}
    karma:      { type: integer, minimum: 0, maximum: 5 }
    role:       { $ref: '#/components/schemas/UserRole' }

Here is an example. You see the tinyavatar field? That's a basic way of "extending" another schema. In this case, it's done so that we can also inform that this property may or may not be null.

[Monkatraz]

Additionally, because KDL is node based, we can do something really awesome:

webhook newPet {
  post {
    requestBody {
      ...
      content "application/json" schema=r#"components > schema [val() = "Pet"]"#
      ...
    }
  }
}

schema Pet {
  require id name

  property id type="integer" format="int64"
  property name type="string"
  property tag type="string"
}

This removes an indentation level and allows for defining schemas next to the API paths they'll be used in. When translated to JSON, these of course would have to be shoved into components/schemas, but that doesn't seem particularly difficult.

[esoterra]

1. How do you see KQL being used to combine them together? As I understand it, it's for selecting parts of a document. Would users be defining KQL queries that select some slice of a schema to incorporate? An example query would be helpful.

2. Do you see this as being (a) something that de-sugars to allOf and related workarounds and preserves the references to the parents or (b) something that where the translator performs the combination and results in a single concrete schema for the result of the merge?

[Monkatraz]

1. Well, I suppose KQL isn't needed for this. However, it could be useful in extending objects that aren't schemas. I'm not familiar enough with KQL to give you a good query.
2. I was thinking the latter (b). Tooling and readability of the JSON would benefit from having to only deal with concrete schemas.