Is the openAPI spec (eventually) normative or informative? #118
Comments
|
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? |
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).
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 transcriptw3c/did-resolution#118markus_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 fi 645A les 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://w3c-ccg.github.io/vc-api/#verify-credential 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. |
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.
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.
The text was updated successfully, but these errors were encountered: