w3c
Is the openAPI spec (eventually) normative or informative?
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.
- If this is informative, we should say so (e.g., by putting it into a note)
- 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.
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?
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...
This was discussed during the #did meeting on 13 February 2025.
View the transcript
w3c/did-resolution#118
markus_sabadello: for issue 40, I might have misstated the desire, will look into it.
markus_sabadello: This next one is around HTTP endpoint, OpenAPI definition, Ivan wondered if it should be normative or informative -- currently not in our repository, in DIF repository, but interesting question. Should OpenAPI be in our WG and should it be normative/informative.
manu: We have included an OpenAPI spec in the VC-API, but it's informative. There is an experimental Respec plugin that can render OpenAPI specs.
manu: The .oas files are informative. But in the Respec file, we "transclude" certain part of the OAS files, and that becomes normative in the specification.
manu: It's a hybrid, but it helps to avoid mistakes in the .oas files
manu: If there is ever a bug in the .oas files, the spec is normative.
https://
manu: In this example, the requests and responses come from the .oas files directly
manu: We could follow that same path here.
manu: Or we say the spec is normative and .oas is informative, but then the question is what happens if they are inconsistent
Wip: Do we need the OpenAPI spec at all?
Wip: we're just defining the resolve function, right?
markus_sabadello: Yes, the OAS for DID Resolution only has one endpoint, but there are quite some logic embedded in that related to content type and accept headers and returning just the DID Document, or DID Resolution result, all metadata stuff; we'd have to try it out.
manu: We want to make things easier for developers, having OAS files is useful.
<pchampin> +1 to make the developers life easier
ivan: Is it an option to have an OAS file that is normative -- is it stable/referenceable from W3C's point of view?
manu: The OAS spec is stable, so we can cite it.
ivan: I'm talking about the specific OAS files themselves, if they're in TR, can we just use those?
ivan: Is it an option at all? I don't see a problem keeping it out of the document, but in same repo, which is in /TR -- that's fine, it's ok.
Wip: ok, sounds good, let's move on -- figure out how to integrate.
This was discussed during the #did meeting on 10 July 2025.
View the transcript
Is the openAPI spec (eventually) normative or informative? #118
<ottomorac> w3c/
ottomorac: 118 - is OpenAPI spec going to be normative or informative
… Open question as to whether the reference to OpenAPI spec is normative or informative.There was also a question about whether we can use .OAS files for the example.
<bengo> dmitriz there is also https://
<bengo> (RT != endorsement)
markus_sabadello: I don't really know the answer to that, re OpenAPI,
… maybe informative?
… because we're actually defining HTTP binding for DID Res in the spec itself?
… so OpenAPI is just a useful additional construct
… so, not normative
ottomorac: there's also comment from Ivan - what happens when there's a conflict between spec text and OpenAPI definition?
manu: two thoughts - one is, we've been dealing with the same issue in the VC API spec for 3+ years
<manu> digitalbazaar/
manu: it led us to create a plug-in for Respec called Respec-OAS
… what this does is ensure the alignment between spec text and OAS file
… so, it takes the OAS file as input, prints it out using RFC language
… it's a bit wordy and verbose, and may not be the approach here. but just noting there's that tool
… we're actively using/maintaining it tho
… comment two - if we don't more tightly bind the two, then the OAS file should be non-normative
… so as not to lead to spec mis-implementation etc
<bengo> Ideally the normative text is in plain language, and I'm not sure OAS is
manu: so, either unify the two via the tool, or make OAS non-normative.
<bengo> (great tool for devs, not for readers)
manu: re bengo's comment -- that is exactly what the plugin tries to do, convert the OAS language into normative plain text
bengo: yeah, was just agreeing with you
ottomorac: markus, do you need some time to think on it?
markus_sabadello: my preference would be to keep it informative for now
… rather than setting up the plugin for the time being
… since it's a very simple one endpoint API
<manu> agree that it's a simple API and probably don't need the overhead of respec-oas.
<bengo> manu if the spec loads the OAS then the 'plain language' can still be normative even if the OAS is not. only it's conversion to plain language needs to be normative imho.
markus_sabadello: so, we just define spec text as normative, reference the OA as informative.
<manu> bengo, hmm, ok I think I understand what you mean -- and is what happens today w/ respec-oas (the OAS is never normative)
ottomorac: ok, so the resolution is -- move the OAS file to a DIF repo, and reference it as informative
<bengo> manu i love that, thanks for making respec-oas
The consensus seems to be that 1. We copy the OpenAPI spec from https://github.com/decentralized-identity/universal-resolver/blob/main/openapi/openapi.yaml into the did-resolution repo here, and 2. Mention that it is provided as an informative reference.