Open msporny opened 1 year ago
msporny
commented
1 year ago At present, there seems to be a couple of considerations for input options to each VC API endpoint:
The following items are under debate:
msporny
commented
1 year ago The group discussed this on 2023-03-21
@PatStLouis asked ... @dlongley noted that he thinks that a JSON-LD Context is not required (regarding q 2). @dlongley noted that regarding 1, people can use reverse domain names or URLs, and maybe people want to do that to prevent conflicts. Any options that get put in here are specific to a particular implementation. Clients that use that implementation can use those options, but they shouldn't expect those options to be compatible with other implementations. There is no concept of any open world model here, you always know which implementation your client is talking to, this is a closed world system that we're trying to talk about extensions for. Don't know how prescriptive we need to be other than talking about adding an extension, shouldn't expect it to work with another implementation without a group of implementers deciding that some option will work across multiple implementations, but that's essentially what this group is for. @PatStLouis a concern -- if people can define options that are required for their imlementation, how does that translate to test suites? If endpoint requires specific option, how can they demonstrate they're an implementation of VC API? @dlongley noted that if endpoint requires specific option that's not in the spec and endpoint doesn't work without it, then you're not compliant with VC API (presuming different authz models might break this rule), but if you require extra options to be passed in, you're probably not fully compliant with what spec says. How does this translate into test suites? Options that are proprietary don't go in interop test suite, unless people tryi to get that option into spec. @PatStLouis ok, makes sense. In order to maintain interop, these extra options need to stay optional. @jandrieu I don't think I like option mechanism to have required aspect of options, that's where they should put extensible options that they support and only they support and if they have one that's required... if there isn't an option/field, (example: "Add SSN field", service provider should be able to do that and make it mandatory). @dlongley said we could allow behaviour if we had clear text, by doing that, make standard libraries that work against API (which can take in additional options), those libraries would still work but worried about awkwardness related to that. Might end up splitting ecosystem in such a way that implementations add lots of required options that any client using them would struggle to swap implementation out -- worried about vendor lock in -- we can't stop people from doing that, but we should be clear with language, more you do that, more there will be vendor lock in... not a good thing for clients. @jandrieu yes, +1 for clear language, this is the innovation that will make interop harder, when you do that sort of customization, more abstract level -- bigger concern, if they can't put options in options field, they'll expose additional endpoints... that would be worse -- proprietary stuff in well know extensible options property rather than build complicated extra routes. @PatStLouis Going back to initial question, regarding options should be allowed to be required, how do you demonstrate that you're an implementer of VC API? How can we maintain demonstrability of VC API? @jandrieu two things -- we have a test suite, and that test suite only tests common features (so special features won't be a part of that test suite), however also expect that test suite has if a given implementation needs a particular property in their options, test suite should be able (in instrumentation for using test endpoint, provide that information). @dlongley I'd like to agree with Joe, don't know if it would be better or worse for implementers to create custom endpionts to do special things vs. adding flags/options that behave in well defined ways. Not sure what's better or worse, if there's something they want to do, they'll do it regardless of whether we say they can or can't. We can't make the statement, but we can give them guidance... don't know what right answer there is -- do it through options on existing endpoints or tell them to do another endpoint? There are trade-offs. @PatStLouis two quick comments -- if there are unique implementations, test suites can configure that... issue with scalability, if spec grows, there is a scalability issue to cover every aspect, if implementer contributes to test suite to test their solution... give yourself 100% on an exam (feels strange)... 2nd point -- at beginning, option for proof type, then decided that should be instance-specific, this same approach should be first approach towards options -- if you require a certian option, can you solve it via an instance configuration? Extra options could be solved via different instances... once there is a tangible use case for a "required" option, that might help things. @dlongley big +1 to what Patrick said, we should say: "If you can solve your problem via instance configuration, you should." -- if we raise PR, what were possible problems -- having lots of different required options across different implementations is harmful for interop, if you can hide those behind config setup, you should do that -- should be preferred... better interop, pushes differences in implementations to setup step instead of it being a part of every client interaction. @PatStLouis if there is a required option, requirement to have it documented somewhere? @dlongley we can't enforce documentation through our spec... options registry? Are different implementations trying to coalesce around useful option... there's a lot of extra work that could go into that... option discovery? Rather us not go down that path... admit that any implementation that adds extra options, behooves them to document it, but the spec can't make them do anything.
Raise a PR that does the following:
It is not clear how one extends the VC API endpoint options (or objects). This discussion started in issue #198 and #287. A discussion in #198 resulted in the group wanting to define the extensibility rules for VC API endpoint options. This issue is raised to gather what those rules should be.