fix: sync discovery schema/spec with IETF-RFC.md

[MahdiBaghbani]

Sorry I was late to read the previous PR and missed some details, here are my fixes:

• Draft consistency fixes (IETF-RFC.md)

  • Fix internal naming mismatches in Appendix D so implementers do not copy the wrong field or token names (for example tokenEndPoint, http-sig, http-request-signatures).

• OpenAPI alignment (spec.yaml)

  • Correct typos and example drift against the draft (capability token naming, accessTypes plural, and tokenEndPoint wording + examples).
  • Keep the draft's mixed URL forms: inviteAcceptDialog is a path, tokenEndPoint is an absolute URL.

• Discovery JSON Schema becomes JSONC and follows the draft strictly (schemas/ocm-discovery.jsonc)

  • Use JSONC so we can document the "why" next to the schema.
  • Follow the draft lead: inviteAcceptDialog must start with /, tokenEndPoint must be http(s)://....
  • Include both legacy publicKey (deprecated) and RFC 9421 publicKeys[].

[glpatcern]

Thanks Mahdi (and happy new year!). I have a comment on the comments ;)

[glpatcern]

Looks good!

[MahdiBaghbani]

The OpenAPI spec says servers.url is https://{discovery_fqdn} with no path, and paths like /shares, /notifications, /invite-accepted
So OpenAPI tools treat POST /shares as POST https://cloud.example.org/shares

In practice, discovery returns something like endPoint: https://cloud.example.org/ocm, and implementations (e.g. Reva) use that as the base and call POST https://cloud.example.org/ocm/shares
So the spec's servers.url does not match how clients are expected to build URLs from discovery

I didn't do anything about this as part of this PR, just want to know your opinion on it

[glpatcern]

The OpenAPI spec says servers.url is https://{discovery_fqdn} with no path, and paths like /shares, /notifications, /invite-accepted So OpenAPI tools treat POST /shares as POST https://cloud.example.org/shares

Thanks for raising this, it seems implementations are not using the OpenAPI toolchain (Reva is not for sure).

The issue was introduced once we added a /.well-known path outside of the /ocm "namespace". Shall we fix this by explicitly declaring /ocm/shares, /ocm/notifications etc.?

[MahdiBaghbani]

@glpatcern Yes, that's the correct thing to do but we also should note that the "ocm" isn't hardcoded, someone would return endPoint as https://cloud.example.org/opencloudmesh from discovery in .well-known/ocm

[glpatcern]

@glpatcern Yes, that's the correct thing to do but we also should note that the "ocm" isn't hardcoded, someone would return endPoint as https://cloud.example.org/opencloudmesh from discovery in .well-known/ocm

Hmm right, and in the implementations we actually do POST to endpoint + '/shares' where endpoint is taken from the discovery. We should try and find a proper way to express that in OpenAPI format