Should URL options be terms or absolute URLs?

[msporny]

Some HTTP API calls take options. Some options, like type and verificationMethod take a fully qualified URL. At present, the values are terms that map to absolute URLs, such as assertionMethod and Ed25519Signature2018. Is that the right thing to do, and if so, how are we justifying that choice?

This came up here: #197 (comment)

For us to continue to use terms, we could say "All terms are defined in the Linked Data Security Registry (currently, the security vocabulary)"... but even that's a bit shaky. We could hard code the options in the spec, but that isn't a very good extensibility story.

How are we justifying the terms that we are using in the specification, and what is the extensibility story for them?

[kezike]

You mentioned a @context option in the linked comment. To expand on that idea, could we make that property optional, so that if it is included the user can use LD terms in the contained vocabularies; else they must spell out the absolute URLs (a la JSON-LD)? Or is that overkill?

[msporny]

@kezike Yes, that would be ideal. However, there are people in the community that might object strongly for JSON-LD sneaking it's way into a, what is now, just a JSON API.

The question is how strict the API validators be? I expect most will say "JSON Schema and OAS is good enough." We just need to figure out how to message it in the spec.

[kezike]

@msporny OK, that's fair enough. In that case, here's a follow-up question: isn't the usage of the type property already introducing the notion of LD in the API. It suggests that the server would need to know how to extract terms from the linked vocabulary anyway, correct? I suppose the difference is that without @context, we require LD functionality but not necessarily JSON-LD functionality. Generally, is that the assumption that we are making throughout the vc-http-api?

P.S. - Not trying to be difficult here, just want to make sure we are on the same page :)

[msporny]

Not trying to be difficult here, just want to make sure we are on the same page :)

Not at all, you're asking great questions. :)

I don't know if we have consensus on the mental model here, but you're proposing one that feels consistent.

isn't the usage of the type property already introducing the notion of LD in the API.

Yes, one could say that... and even that triggers some anti-LD people. It's a bit funny because VCs /are/ JSON-LD -- there is no getting around that... but Microsoft has been trying very hard to avoid the LD aspects of the ecosystem and instead is trying to just keep using JWTs and wrapping things that look like VCs (some variations of that are perfectly fine).

It suggests that the server would need to know how to extract terms from the linked vocabulary anyway, correct?

This is true for JSON-LD-based VCs... and as I said, others in the ecosystem would like to not use those, but their own versions of VCs that are not LD-based. We're trying to (probably unsuccessfully) cater to that part of the ecosystem.

I suppose the difference is that without @context, we require LD functionality but not necessarily JSON-LD functionality. Generally, is that the assumption that we are making throughout the vc-http-api?

Yep, you got it... and I think is a defensible mental model and a decent compromise. It still triggers some people that want nothing to do with LD or JSON-LD... but they seem to be ok living with it (even though they're pretty vocal against the mental model).

Hope that helps -- again, great questions -- you're asking exactly the right ones. :)

[msporny]

We discussed this on the 2022-04-19 call -- @kezike noted that it would be good to align with industry norms, @dlongley noted that the "context" is already set here since we're dealing w/ VC-JWTs or Data Integrity -- no need to adopt JSON-LD complexity when context is known. @jandrieu noted he liked what @dlongley was saying, but allowing people to innovate faster than standards process -- is there an option that terms defined in VC API specs are not fully qualified, but people can use fully qualified URL to use new type of term. @dlongley noted "general extensibility to API". Depending on how extensibility happens, if we're ignoring unknown JSON terms, then that gives people space to do that, perhaps some APIs are locked down more than that. @msporny noted that we could allow non-fully qualified names. @jandrieu noted that non fully qualified names lead to interop failures -- need to fully qualify in some way. @dlongley we are providing JSON Schema that rejects extra items, these APIs are slightly more locked down -- not against having a statement about experimenting with names, they need to be fully qualified -- might fall into anti-pattern of browser-qualified CSS terms or "X-" experimental headers. @jandrieu not sure if it's the same case -- no ability to have future term that maps to an old term -- but we can do that by adding term to the spec and identifying as "thing existed first elsewhere". JSON-LD property must be in VC API -- we don't have extensibility. What we need to support is different components in ecosystem -- issuer app and verifier app innovate independently. If issuer has new service, and verifier doesn't support, don't want things to be dropped... pass it through. @kezike one of the concerns was not spelling out terms via absolute URLs. @jandrieu Who is arguing against JSON-LD? @msporny I am, to a degree, don't want to fight the JSON-LD fight when we don't have to. @jandrieu Important that we understand extensibility story since /exchanges can be arbitrary; don't want to move past false dichotomy. @dlongley agree a lot with what @jandrieu said -- JSON-LD is a tool, if tool is unnecessary in some space, don't use the tool. We need to be clear about where those lines are -- might be more of a spectrum. When @jandrieu starts talking about extensibility wrt. workflows JSON-LD makes a lot of sense, but when we're talking about options to API, possibly not. @dlongley asked -- what are the options -- like cryptosuites -- mostly closed space, no need to have too much extensibility there... but workflows, need much larger discussion. @jandrieu if it's not a fully qualified URL, then it must be a term defined in a VC API definition (possibly a JSON-LD context)... how do you have options that are not in the VC API spec?

Next step: Create issue to discuss extensibility solution for terms across all API inputs.

[msporny]

Closing in favor of issue #335, which attempts to define the extensibility solution for input options to the VC API.