Deprecated argument in GraphQL API (spec 2021)

I have a GraphQL API described in accordance with the specification from October 2021.

I have an argument size that I want to remove.

type Product {
  picture(size: Int): Url
}

But I can't remove it right away without informing consumers in the API specification. I know the working draft spec allows using the @deprecated directive with arguments, but the 2021 spec doesn't allow that.

How can I delete the field in an informed manner without violating the 2021 specification?

I had an idea to deprecate the field and create a field next to it with the same name but without an argument, but unfortunately this is not a valid action.

There isn't a great solution here, but I can tell you what my team decided to do: either create "a field next to it with the same name" (+V2), or create a sibling field with a "better name" if you have a better name.

Trade-offs between versions and new names:

• If you choose to use V2, it's not as "clean", but it's easy to see what the API consumer should do and what they should use. Sometimes, you may even create a V2 before you deprecate the original, and someone reading the schema may see the V2 and begin working toward that. Additionally, these customers are already looking at picture, so they're more likely to see pictureV2 before you tell them.
• If you choose a "better name", the final schema is "clean"; it doesn't contain historical information that there used to be something different. However, if you introduce a new name, you have to be explicit when you deprecate, and you may have to communicate more carefully. The API consumer needs to read the deprecation notice to know what to do next, since it's not immediately obvious what's happening.

It's also worth nothing that the "clean" problem is a real thing, and it's not just about aesthetics. It will likely feel bad the first time you add V* to something, but I've found that at scale*, it's easier in the long run.

* "at scale" here can mean a few different things, including

• Schema Growth: When you have a large codebase or schema, which continues to grow, this question is going to come up a lot. Choosing a simple versioning strategy allows the team to not have to slow down to make a new decision each time. Just bump the version and move along.
• Customer-base Growth: When you have a large API-consumer base, a versioning strategy like this is easy to understand, so you don't have to reteach it over and over.
• Team Growth: When you have a large team, a versioning strategy that is easy for the new team members to see at a glance also doesn't have to be retaught. It's easy for the new person to "copy-pasta" and know what to do next.
• Architecture Growth: If you end up going the route of subgraphs and either federation, stitching, or something similar, having a simple and consistent strategy across all systems will lead to consistency and readability for your customer, even if you have separate teams working on separate systems.

So, if a teammate showed me your example specifically and asked what to do next, I would give these options, and they should do what is right for their product and their customer.

1. pictureV2: You know your domain and your customer. If picture is the right word, use pictureV2.
2. pictureUrl: You're returning a URL, which is a scalar. You're not returning a "picture", which might have dimensions, altText, titles, etc. Additionally, if you use the name pictureUrl today (when you're only returning a URL), in the future, if you DID want to introduce these other properties, you could use picture (the non-scalar name) for that. I don't recommend over-engineering for what "might happen", but if you name things with this principle in mind, you leave yourself open to adding features in the future without having to over-architect for maybe, today.
3. image: This term conveys the same relative meaning as "picture", but it's more common in API design.
4. imageUrl: The one I usually recommend, due to the previous two bullet points.