API Evangelist Conversation with Lorna Mitchell, OpenAPI Specification Maintainer with the OpenAPI Initiative

Hello again, Kin Lane, API Evangelist for another one of my API Evangelist conversations, where we sit down with interesting folks who are doing interesting things with APIs. Let’s not waste any time, let’s find out who we got back today. Hello again, and for the new folks, tell a little bit about who you are, what you do.

Hi everybody, I’m Lorna. I’m an API enthusiast, I would say. I’ve been working mostly in APIs as a backend software developer for many years. I’m on the technical steering committee for OpenAPI, I write and speak about APIs and about developer experience, and yeah, I’m an open source maintainer, and I love all this stuff.

Well, I don’t think “enthusiast” is the right, you are very enthusiastic, but I would find other words to describe what you bring to the table and why you’re here. So, third time back, we’ve talked about command line interface, working with OpenAPI, kind of some general stuff. Last time we dove directly into overlays. This time I would like to learn more about the intersection of OpenAPI extensions and the API experience. So let’s start with OpenAPI extensions. What’s an OpenAPI extension?

The OpenAPI specification supports what we call extensions, and they used to be called vendor extensions, so you’ll sometimes hear them called that way, although now they’re really not vendor specific. A lot of often a lot of vendors will support the same extension. So within your OpenAPI description, that will be the x-whatever fields that you see, where people are taking, adding data which isn’t officially described in OpenAPI but makes sense for their use case. A good example is, if you’ve done documentation, generated readable, human-readable docs from your API using an OpenAPI description, you might have used the x-logo extension to add your logo into the resulting web page that gets created.

And you kind of touched on a little bit the intersection with experience. So onboarding, how does, how do extensions impact the API experience?

Extensions really round out the API experience, I think. There’s a lot that you can do with API experience just with the core fields, so things like using good descriptions, using good examples, that’s a big part of the experience. But where the extensions go a little bit further is where you’re improving something that can be quite specific. So it might be that you’re adding particular extensions for your API gateway, or for your SDK code gen, those are really good examples. We talked about, I already mentioned docs, you see this x-display-name field used a lot in tags, because we have a tag label and a description but it doesn’t really have a human-readable name. It might do in 3.2, I have a proposal out, but of course we can’t promise because it’s not released yet. So those are common things where this just makes things clearer, nicer, easier for the user. And in some cases the tool destinations really benefit from information that might not be in every OpenAPI description, that you might not be able to infer, maybe if you’re generating it.

And maybe, I mean, if someone hasn’t seen the discussion we had about overlays, this would be a good thing to look back at, because you could use overlays just to add the appropriate fields for, for example, generating an SDK in a particular tech stack, because every tech stack benefits from having its own annotation, its own extensions.

So anyone can extend the specification. What’s your guidance for folks when it comes to understanding what the core spec does, what overlays are for, and when should I feel confident enough to be able to extend it?

I think knowing what the core spec does is a really great starting point, and I’m happy that you called that out. I sometimes see extensions where I know this exists, but maybe you haven’t seen it, or you’re using a tool that doesn’t support it if you’re stuck on an outdated version of OpenAPI itself. So if you’re on 3.0, or I still see 2.0 in places, then you will be using extensions to fill in functionality that’s in the newer versions but you don’t have access to it yet. And in that case, rather than adding an extension now, I would consider upgrading, because that’ll give you a bunch of tools that are ready to work with the new way to do it. A great example is webhooks. I do see 3.0 specifications that use the x-webhooks, which a few tools support, but if you upgraded to 3.1, all the tools would support just webhooks.

Yeah, it’s an important part of the evolution of the spec, I think, there’s kind of a relationship there, how strong it is or weak it is, as far as influencing the spec. I think extensions play an important role. But you mentioned earlier they were called vendor extensions, and I still slip up, and I actually think I’ve been yelled at a couple times by Marsh and others, no, don’t, and so I’ve trained myself to say extensions. And then I’ve looked at extensions across the specs, but what recommendation do you have for naming them? Because some go very, you know, hey, this is x-Gateway, this is x-Auth, the namespacing of that seems to be kind of in conflict.

Yeah, I definitely would still prefix with a vendor extension, like you see the x-Amazon-API-Gateway things, that makes sense, because even another API gateway might not adopt those standards, and so it does make sense to prefix. I think if you’re doing something incredibly generic, like we had x-deprecated for a while and now deprecated is a field in the specification itself, that doesn’t need to be vendor prefixed, like this works for everybody, it works for a bunch of different tools. So the more niche it is, the more I’d be tempted to try and make clear who it is. I think there’s a big gap in OpenAPI, which we’re already looking at, talking about, but I just want to acknowledge that it’s there, is that we have a very empty registry of extensions, and it would be good to round up the ones that we know are in active use and try and describe how they should be used, because otherwise you get the situation where the same x-something contains completely different data structures expected by different tools. And if we could just write something down, then, you know, there’s two ways to do something, or probably 10 ways, if we all did it the same way. The point of OpenAPI is to help us to interoperate and give the community a huge choice of tools for everything that they do, and that really helps that.

I know that you’ve been looking at a lot of different organizations’ OpenAPI descriptions, I’m guessing you see quite a lot of extensions used.

Yeah, yeah, I’ve come across, harvesting OpenAPIs, you know, they have Twilio PII for their European GDPR stuff, all the gateway stuff you talked about, the APImatic has SDK. I see a lot of SDK ones emerging out there, because I think that requires the most rigorous, complete OpenAPI definition. And there actually used to be a project out there, I have to look into it again, about the semantics of extensions and having a common set of semantics, we need to revisit that. Do you feel like people who create extensions have some sort of obligation to come keep the registry up to date, to show up and champion theirs in the TSC meeting? Because I feel like people are using it as a, oh, I don’t know the spec, I’m just going to extend it willy-nilly, and then, or if they do know the spec and they extend it in a valid way, they just kind of keep it to themselves. Do you think there’s some responsibility they should have?

I think so, but again I think it depends on the use case. If you’re extending your OpenAPI description in a way that you think lots of other people want to extend it, or if you expect other tools or other organizations could make use of this, then yes, I think you should be sharing that more widely. And that’s evidence, I am sure, you are seeing multiple extensions called something similar but not quite, or like we just said, returning different data structures for essentially the same function.

Yeah, so that’s where having a registry and nailing down your version of how you would like us all to standardize on it. You know, I don’t think people understand that OpenAPI, you know, we have the open technical meetings every week, and people can just come and advocate for what they want. And when people suggest or ask for new fields or other additions in future versions of the specification, if we can see that it’s widely used as an extension right now, like, oh well, then we definitely need it. If it’s not super niche or only for one tiny narrow use case or something, then yeah, it should be in the definition. And if we can see it used consistently across a bunch of different organizations as an extension, that shows me that there’s a real use case, it’s well understood, and we should just adopt it. So there are some things which the extension just eventually leads to official adoption at the next minor release, which is when we can add fields.

Yeah, that’s interesting. I think it has a roadmap and kind of the way of contributing to the core spec, but I feel like the relief valve on the spec is going to be somewhat alleviated by overlays too, because I would say there’s some overlay reasons people create extensions. And it feels like, should people bring these extension conversations and overlay questions to the TSC meeting? Is this the forum that we should be having these conversations?

I think definitely bring them to the meeting, or use the discussions, the GitHub discussions on the main specification repo, because I think hearing that conversation as part of the main project really informs how we think about what can change. Yes, there are a bunch of extensions that I think, now we have overlays, you might only want to have them in overlays. The example that we both gave here, which is the SDK generators, really benefit from a lot of additional metadata per destination technology stack, right, all the APImatic extensions, the Speakeasy extensions, that differs for which language it is you’re generating. And some of those OpenAPI descriptions can be enormous because they’ve got all this extra stuff that’s just for one destination output. I’ve been talking a lot this year about OpenAPI pipelines, about having a description and then enhancing it or filtering it down to something smaller as appropriate for each audience or output. Overlays, where you add just the correct annotations or extensions for a specific generator, and this is where you keep it, you keep it here, get ready to do Ruby, boom, Ruby, we don’t have to have all of that inside our OpenAPI description all the time.

I think that’s magic. And I think overlays is huge, and also it allows more people to add more extensions at different stages of the life cycle.

It also allows us as API consumers to take an OpenAPI description and patch it as we need to, if it’s, for whatever reason, not perfect for the thing we were going to use it for. So I think it empowers consumers as well as producers.

Interesting. So a couple things I want to unpack there for folks. One, go to the OpenAPI GitHub repo for the spec and search, when you want to extend something, do something, search for it first to see what’s out there, get to know if someone’s already talking about it. And I would add, Google it too, because there’s probably a conversation, but start with the repo, and let’s try to keep these contained within there. And then, you don’t have to show up to the TSC meeting if you’re intimidated by it, you’re not a good speaker, whatever, there’s a lot of asynchronous conversation opportunities to figure things out there. But the other thing that I kind of heard there is, I’ve long tried to push for some sort of specification for the API life cycle, and I’ve failed many times, and probably for good reasons, I think generally a lot of my suggestions were bad ideas. But what I just heard you saying with overlays is, so the problem was we couldn’t agree on define or design or whatever the stage of the life cycle, so we never got to do the work of figuring out what needs to be done at that life cycle point stage. But what you’re saying is overlays is going to bring us, we don’t have to worry about this until it’s going out the door, because it’s docs or it’s localization or something like that. So rather than talking about the life cycle, we can just talk about when a certain experience matters, right?

Yeah, I think so. And I think there’s also something there around being able to look at your OpenAPI description through different life cycle lenses, so where are we. You know, I often hear, oh, I can’t document this super secret experimental endpoint that we just added, but we don’t want everyone to know, so we cannot describe it in the OpenAPI description. And it’s like, now you can, but you need to tag it, or add the experimental tag or label or whatever, so that in an overlay you can filter it before you publish it to that wider audience, but you can still see it in your internal docs preview and get your stakeholders into the conversation. So all of those “I can’t add this, I can’t change that, it’s generated and therefore nothing can be done,” especially some of those older generators, none of that’s true, and we can repeatedly make those changes with overlays. And so stuff like the life cycles and the different stages of the operations, I think it really opens the door.

Yeah, it’s so important. So it feels like a kind of renewed time right now for a lot of these discussions. I think people had a lot of anxiety about life cycle, overlays, experience, different things, but we’re at time, so we’re going to have to save it for a future one. I appreciate you coming by and sharing with us, Lorna, thank you.

Always a pleasure, thank you.

Good stuff. All right, definitely head over to, start with the OpenAPI GitHub repo, search, join in on the discussions there if you have questions, overlays, extensions. I think it’s a really interesting time in the OpenAPI Initiative for this stuff, because of overlays, but also Arazzo specs, and working on the next minor release of OpenAPI, as well as there’s a lot of talk for 4.0. So go get involved, either synchronously or asynchronously, it’s a good time to move things forward. All right, until the next one, thanks y’all.