OpenAPI Gateway vocabulary for resources fronting multiple services

[dickhardt]

Removed from R3 before publication, to be settled before it goes back in. The operation identifier scope rules it accompanied are unaffected and remain in the draft.

The problem it addressed

A resource that fronts several OpenAPI-described backend services behind one resource identifier — an API gateway — cannot use the plain urn:aauth:vocabulary:openapi vocabulary cleanly. That vocabulary assumes one OpenAPI document per resource, and operationId is unique only within a document, so two services can each define createEvent and a bare identifier no longer resolves.

R3 currently requires such a resource to do one of two things (#operation-identifier-scope):

• present the services as one valid definition at the discovery endpoint, renaming colliding identifiers, or
• expose them under separate resource identifiers, letting the auth token's aud distinguish them.

Both are workable. Neither is free: the first pushes a rename burden onto the gateway and breaks identifier parity with the upstream services, the second multiplies resource identifiers for what an operator thinks of as one resource.

What was removed

A third vocabulary, urn:aauth:vocabulary:openapi-gateway, where:

• the r3_vocabularies discovery value is a JSON object mapping service labels to OpenAPI spec URLs rather than a single URL;
• each operation entry is a (service, operationId) pair;
• operationId need only be unique within one service's specification.

Why it was pulled

• It is the only vocabulary whose discovery value is not a URL. That special case leaked into the general r3_vocabularies description, which had to say a vocabulary MAY define a structured discovery value. One vocabulary should not reshape the metadata contract for all of them.
• Service labels become grant-bearing identifiers. They are resource-chosen, appear in R3 documents and auth token claims, and relabeling silently invalidates existing grants even when the underlying specification has not changed. The draft said labels SHOULD be stable, which states the hazard without resolving it.
• The pattern is not OpenAPI-specific. A gateway fronting several MCP servers or several gRPC services has the same collision. Solving it once per vocabulary does not scale; if qualification is the answer it likely belongs in the operation entry structure generally, or in the discovery layer, rather than as a parallel vocabulary per format.

To decide

1. Is multi-service aggregation behind one resource identifier a case R3 should support directly, or is "use separate resource identifiers" the right answer and the gateway case simply out of scope?
2. If supported, is qualification per-vocabulary (a -gateway variant for each format) or general (an optional qualifier in operation entries across all vocabularies)?
3. Whatever carries the qualifier, what makes grants survive relabeling — or is label stability simply a deployment requirement stated normatively?

Implementer input from anyone running a gateway in front of AAuth resources would be especially useful here.