Is the openAPI spec (eventually) normative or informative?

[iherman]

At this moment, there is a reference in the section on HTTP(S) binding to https://github.com/decentralized-identity/universal-resolver/blob/main/openapi/openapi.yaml.

1. If this is informative, we should say so (e.g., by putting it into a note)
2. if this is normative, then the yml file should be brought over to the W3C spec either by normative reference locally or by inclusion.

Personally, my preference would be (2), but I am not sure if that is possible. E.g., I do not know whether openAPI is technically stable for W3C usage.

[peacekeeper]

I don't have much experience with this, is it common for W3C specs to include normative API definitions? I think OpenAPI does have stable versions.

But what happens if there is some kind of conflict between the spec text and the OpenAPI definition?

[iherman]

I don't have much experience with this, is it common for W3C specs to include normative API definitions? I think OpenAPI does have stable versions.

It is up to the WG, so I do not see why not. In a way, all W3C recommendations that publish an API using WebIDL do that, just using a different formalism (there are many reasons why we should not use WebIDL).

But what happens if there is some kind of conflict between the spec text and the OpenAPI definition?

Then we have a problem :-) That is why the requirement for (normative) references is that the definition must be, technically, stable.

If that is the case with OpenAPI, then my issue is moot and can be closed. But I am not familiar enough with that world to decide that...