Manu Sporny: Seems to be working all right welcome everyone to the VC API call this is March 15th 2022 our agenda is in chat on the agenda today just our typical agenda review introductions relevant Community updates and then we have a lot of PRS to go over which is great thanks to everyone that did PRS thank you Mike Prorock and everyone else that contributed so yeah we've got a long list of things to get through today. ✪
Manu Sporny: It like we're just doing PR reviews for the whole any other changes or updates to the agenda is there anything else folks would like to talk about. ✪
Manu Sporny: All right if not let's go ahead and get started. ✪
Topic: Agenda Review, Introductions, Relevant Community Updates
Manu Sporny: First topic up is agenda review introductions relevant Community updates I think everyone. ✪
Manu Sporny: I think yeah we everyone everyone knows everyone here so I think we're good. ✪
Manu Sporny: So we don't need introductions reintroductions any relevant Community updates. ✪
Manu Sporny: All right I think the mic I don't know if it's worth talking a bit more about kind of the VC API as it relates to like the VC 20 working group. ✪
Manu Sporny: Continuation of the discussion that started on the ccg call earlier today thoughts are brand I don't know what your thoughts were on that as well. ✪
Mike Prorock: I don't know if Brenda comments it my concern is primarily if we can't take at least a core set of you know issue verify holder type operations and Define a clean rest API and some kind of normative fashion like that that eventually right it doesn't have to be a part of working group to I think we can use working group 20 to flush it out. ✪
Mike Prorock: If we get strong pushback on and I think he brought this up towards the end of the ccg meeting right like I would like a statement in there that says yep we intend to take this normative at some point you know but you know those these are things that concern me about especially seeing some of the politicking towards the end of the did working group and some of the politicking going on even in just getting those Charter to state where people agree with it right. ✪
Mike Prorock: Right these are things that make me nervous. ✪
Brent Zundel: How much pushback we're going to get in the VC working group to bring some of these things in there not a little bit more settled and I think the notion of. ✪
Brent Zundel: Saying here's a note and Republican it as a user guide that talks about this community draft report and here's how you would make use of that to do this over HTTP and rest requests I think the more concrete it is getting into that the better chance they'll be of. ✪
Brent Zundel: People not caring so much that it shows up there but I. ✪
Brent Zundel: I will never not be surprised at what some people end up feeling deeply about and so the cleaner it is going into it I think the better chance we have. ✪
Manu Sporny: Thank you Brian I agree with that brand and I also agree you know Mike that there's you know concern right so you know I think the elephant in the room is like it's pretty clear that open ID Foundation is going to Define V Capi or sorry a thing that moves VCs and in the timeline I've heard is by Q3 or Q4 of this year it will be done in. ✪
Manu Sporny: The question you know then is where does the VC API playing that and what should the VC 20 working group say about that. ✪
Manu Sporny: And yeah I'm you know I'm I'm as concerned as everyone else is around that. ✪
Manu Sporny: And I don't think it's very clear like what we should say so just just speaking from a personal level I think it is problematic for anyone to say that the protocols are going to be anywhere near done in the next two years right I think there are going to be people in organizations that want to say that. ✪
Manu Sporny: Um looking at the current protocols it doesn't seem like they're definitely multiple rough spots on all the protocols that exist today and you know and the market continues to mature and all that kind of stuff so you know I think I don't know if anyone else feels differently about this but saying that there will be a standardized protocol or one of many. ✪
Manu Sporny: I think is a dangerous thing to say I don't know if that is controversial or not or you're on the. ✪
Orie Steele: I don't think saying that there won't be only one as controversial I think it would be controversial not to acknowledge that there are currently multiple protocols for moving these things around at various levels of standardization everything from Community drafts in the ccg two drafts at ietf to working group work items that I. ✪
Orie Steele: Foundation to community drafts at dif mean I'm aware of a large number of protocols that move feces around and and I think we should expect the future to look like the present and the past in that regard and I would I wouldn't say much beyond that. ✪
<tallted_//_ted_thibodeau_(he/him)_(openlinksw.com)> ftp, http, smtp, uucp.... all move documents, which may include VCs
Manu Sporny: Go ahead okay and I mean that feels like a fairly reasonable position to take right now any other thoughts from anyone else before we move into PRS I I was just curious to hear what you know folks you know thought about this stuff specifically as it relates the VC API. ✪
Manu Sporny: Making a very good point in in chat. ✪
Manu Sporny: Yeah I mean maybe what we're I mean I'm sure what we're looking at is a multi-protocol future. ✪
Manu Sporny: Just like we've got kind of a multi multi multiple ways to express a VC in their extension points you know it's probably going to be multiple protocols to move VCS it's an inevitability go ahead Mike. ✪
Mike Prorock: Yeah I think that I just want to reiterate that I mean that's my personal thinking as well and that that's why really the focus should be as much on like what are these operations and how do you conduct them cleanly and safely securely right you know be that issue presents you know you know verify really is the core things and then just keep what does that smallest set of things that could be clearly defined in a way that translates naturally between different. ✪
Mike Prorock: Calls right and if we do that from a. ✪
<tallted_//_ted_thibodeau_(he/him)_(openlinksw.com)> sorry... sftp, https, smtp-auth, uupc-over-tls, etc.
Mike Prorock: Point and from an API definition standpoint that will translate well to things like gr PC and you know Kafka streams and stuff like that like what can you do what can you do and why should you do that and what kind of role are you taking when you do that and based on that role what are the you know what are the implications of that that you should be cognizant of. ✪
Manu Sporny: Yep okay if no one else has anything we will move to our PRS I you know I expect this is just a conversation that's going to continue over the next year you know as new things new things happen but I wanted what I wanted to make clear is that this group is still committed to working on the VC API and moving it forward that that is what I got out of the call this morning. ✪
<orie> obligatory XKCD link regarding too many standards
Topic: Remove issue VC option to change verification method
Manu Sporny: All right with that let's move into our first PR I am going to screen share because why not. ✪
Manu Sporny: In theory it didn't crash during the main call today so in theory it should crash here right all right so what's the first one it is to 63. ✪
Manu Sporny: So this is the pr that Dave Longley raised I think at the end of the day it just removes verification method proof purpose and type this was modified was it Longley it can you give us some. ✪
Dave Longley: Sure yep so it was originally raised to remove just verification method we had a discussion about that and talked about sort of reworking the API at a higher level and at the end of all that discussion or he said I've made a couple of suggestions to remove some other options let's go ahead and remove those if you accept my suggestions then I will approve the pr and so that's where we're at. ✪
Manu Sporny: Okay so we've got an approval from Ori because it was changed does anyone else have objections on these these changes. ✪
Markus Sabadello: Yeah I also commented on this I'm trying to remember now I don't object to it I just I just wrote up some some thoughts that I had on this that perhaps sometimes it is useful to be able to configure these parameters on the client side or two that the client specify this oh I remember I wonder if perhaps some implementations in. ✪
Markus Sabadello: Will it support is in the vendor specific way right so I'm a bit worried that maybe they will be implementations that defined their own custom parameters or options that allow you to pick a verification method or allow you to pick a proof purpose and and then we have when the lock-in and no interoperability. ✪
Markus Sabadello: Buddy I think they've explained the rationale very well and I understand that and I can't object I think it's it's fine. ✪
Manu Sporny: Great thank you Marcus yeah I need to speak to that I think if there is a vendor that wants to provide that kind of variability in their API it is their right to do so. ✪
Manu Sporny: Right and I totally agree with you Marcus if they start doing that and they get very popular then all of a sudden there's potential vendor lock-in but that is a risk. ✪
<orie> embrace, extend, extinguish
Manu Sporny: Yeah that that risk is always there right but I don't think we limit the options to just the ones there we just Define a set and the implementers can do more if they want to. ✪
Manu Sporny: I'm not hearing objections to marching this so we will merge although why is it saying we haven't met. ✪
Mike Prorock: Sori still have change requests turned on now. ✪
Manu Sporny: Why is this all right I'm going to click the button I don't know why it's saying we haven't met maybe we didn't get it enough code owners to okay rebase emerge. ✪
Manu Sporny: All right that one's done next one up. ✪
Manu Sporny: Mike Farley's exchange Discovery PR is Mike here today. ✪
Manu Sporny: Like is not here today we can discuss this briefly then but I don't want to do much on it if Mike's not here does anyone remember the state that we were in for this I think we were. ✪
Manu Sporny: So Mike's got some questions back to you or E you've got some statements to Mike. ✪
Manu Sporny: Looks like more discussions needed here. ✪
<mprorock> still work in progress it looks like
Orie Steele: Yeah I mean basic handling of potentially unbounded lists with dictate that we should design a pi to account for those things it's not clear to me what the max range on. ✪
Orie Steele: The resource response is but you know generally when you build a rest API you don't want to return you want to return some you know interfaces that you can page over millions of results right let's just build the API thinking about that ahead of time. ✪
Manu Sporny: Yep what did you mean by tutorials here or e. ✪
Orie Steele: It's literally just an example of how to page over results you can see total items total Pages current page tutorials is the items collection in this example it's one of the first search results you get when you search for page a nation in Json. ✪
Orie Steele: Maybe the maybe that was confusing maybe I should have linked to mongodb API documentation or something better for paginated APS. ✪
Manu Sporny: Okay all right that's that's clear. ✪
Manu Sporny: All right okay so there just needs to be a little more discussion there and I don't think we can do much there anyone else on the Queue to talk about 268 know. ✪
Manu Sporny: All right so moving on to the next item which is. ✪
Manu Sporny: 269 Is I took an action to write a PR to clarify the that exchange ID and transaction ID or opaque to the client so this is what the pr basically does ignore that the other stuffs not being rendered that's a bug in the preview but we're basically saying we'd said this is just the option just says the trait. ✪
Manu Sporny: The server but are opaque to the client just because they're human readable doesn't mean that you should assign any kind of semantics to that human readability as a client and that's it that's all the that's all the pr does small piece of text we need more reviews on it. ✪
Manu Sporny: It's on ya it was only race two days ago so I'm not going to try and ask folks to merge it. ✪
Manu Sporny: So take a look at it see if that meets folks needs I will note on this that I have had random conversations I forget with who a couple of view I think Mike Farley was one of them where he was like people are going to want to show the job in there and I think Longley you had also mentioned that like we can't just presume that these are 128-bit identifiers there might be other things. ✪
Manu Sporny: That you know people want to do too. ✪
Manu Sporny: Us you know apis again like some some digitally signed something some short-form digitally signed something like a job in the transaction ID. ✪
Manu Sporny: Thoughts on that the folks feel like. ✪
<mprorock> this is one more reason to go 128bit / UUID
Manu Sporny: If feels like it is going to be very hard for us to push against that we can keep it at like uuid and multi base 128-bit ID for now but you know I have a feeling we're going to lose that battle long-term go ahead well Lee. ✪
Dave Longley: So I understand having limits on URL lengths and things like that and those come from other systems as well that we don't even control but I don't understand why we why we would need to create validation rules around restricting these IDs to very specific formats like uuid and things like that I don't know what that actually buys us as opposed to just. ✪
Dave Longley: Many people know where the transaction IDs and and whatever need to go and allow implementations to put whatever information they need to put their we I do agree that we need to be clear about the semantics that this is a server chosen ID and it should be opaque to the client. ✪
Manu Sporny: So is there a concrete change says suggestion in their day like 100 kilobyte a thousand characters you know something like that. ✪
<mprorock> XSS etc
Dave Longley: Unless the API is going to need to hang anything off of the end of these URLs and maybe they need to the Restriction should just be to the length of a URL whatever you know there are limits and browsers today I don't know what those links are but we should just be inheriting from that and unless this API is going to define or expect to have to put something after that I D. ✪
Dave Longley: Through I don't know what the requirement would be. ✪
Dave Longley: To do to limit it to anything other than the total length of the URL. ✪
Mike Prorock: Yeah I just wanted to note the main reason you want to Define and very clearly kind of limit to like nope 128-bit numbers uuids Etc is primary from security aspect standpoint I mean ranging from cross-site scripting to buffer overflow type attacks to embedding encoded script tags to you know so basically anything you can do at the spec definition layer to say this is the exact format we want its. ✪
Mike Prorock: Completely opaque and has no meaning. ✪
Mike Prorock: Leaking any information and logs or intermediary parties looking at requests those are all good things to do right it may make it more make you add an additional layer of like matching Heidi's to descriptions and stuff like that from a developer standpoint but that's comparatively trivial compared to the amount of other things that you can encounter by letting it go pretty unbounded. ✪
Dave Longley: Yeah so I mean I definitely agree that we do need it does need to be bounded to something but I also want us to be careful that we don't I saw some discussion for example people talking about how we should definitely make these uuids so people don't hide things like Social Security numbers in them you know there was some kind of discussion point about that I don't know why anyone would do that but you can hide a social security number in a uuid if you want to as well we're just talking about a hundred you know uuids. ✪
Dave Longley: Version 4 is mostly random bits you can encode whatever you want in there so that we need to. ✪
Dave Longley: Gage in the certain level of security theater and that we understand what the threats are you did mention some number of threats there that you know are good for us to consider and we definitely do want the ID or at least the oral length something to be well bounded but we should also be careful about what we're actually protecting against. ✪
Manu Sporny: Alrighty so I'm hearing no change for now but that was a good discussion. ✪
Topic: Bundle VC-API and provide UX on API Docs
Manu Sporny: Right I think that's that item next item up is bundled of e c API to provide user usability on API docs or good ux on API Doc's there and. ✪
Mike Prorock: Yeah basically Respec is great for looking for spec standpoint prior we had Swagger up way back and then I think I added I want to say maybe redock or something as the default but basically there's three core libraries that developers tend to use for looking at open API docs that also do things nice things for us like cross check to make sure that you're actually inspect to open API. ✪
Mike Prorock: I had the ability to expand out and look at options on the apis as well as schema stuff and things like that and those are Swagger redock and wrap a dock and I've added just stub so developers know how to get at all three and can access all three from this as well as providing a unified a bundled up auto-generated spec on desire so that if you need to look at. ✪
Mike Prorock: Bundled function for like feeding into other developer tooling just issuer capabilities or all of the issue verifier holder for instance right you can go ahead and do that cleanly and pass things into like Swagger code gen nicely and not have any weird collisions and naming collisions or anything like that. ✪
Manu Sporny: All right plus one all that this is great work I had mentioned that there are a couple of Auto generated files that are being checked in here and notice that you were doing you were using workflows in I believe we can make it I think you were doing that just as an example Mike and when we. ✪
Mike Prorock: Yeah I did and I pulled the auto Jen I wanted to make sure folks could go back in and look at the actual commit log so I'm like what actually gets generated right if they need to see that but yes the the auto gem stuff is pulled and there is a base you know workflow stub in there we could turn that on at a later date with a later PR I don't think we need to you know rely on this PR to go enable it. ✪
Mike Prorock: And another kind of side effect of this by the way is that this will sanity check and make sure that you're they open API animal stuff is all Linton properly additionally so it will catch errors as part of the build process if you introduce them in the spec or destruction of this. ✪
Manu Sporny: Fantastic great yeah this looks nice and clean now Mike so yep plus one to merge after folks have had a little more time to look at it Joe. ✪
Joe Andrieu: Yeah thanks no opposition what's going on here my question for you Mike was is there a way that this form of documentation evolves to identify the components I the apps and the services. ✪
Mike Prorock: Yeah so this is actually a nice the here this is setting us up to go down a path to actually tie in like if you were to look at rapid dock for instance we could go ahead and feed it the config of anyone complying with the test suite and actually have every one of those providers in the drop-down so you can go issue calls against them assuming you are authenticated at cetera right so yeah it not it. ✪
Mike Prorock: Kind of question mark in this is actually addressed and I think that my second PR which is tagging right from an open API standpoint there really wasn't any in there I added some base tags in just to get this PR in generating cleanly and then the I think the next PR we're going to talk about actually cleans up some of that but that will be a room that we can evolve that tagging aspect of it. ✪
Manu Sporny: Okay I think any other thoughts on this looks I mean it looks good sounds like everyone wants to merge it in. ✪
Manu Sporny: Holding for a little bit and we'll move on. ✪
Manu Sporny: All right um thank you like that's going to be a super useful PR let's see next one up is the initial get and delete operations that is this PR here to 71 Mike please give us some background on this one. ✪
Mike Prorock: Yeah this is kind of a follow on and that's I think why we flagged it do not merge is don't want to merge this until the prior PR that actually allows for proper bundling and stuff is in and especially because of tags and whatnot but this basically is moving us more down the direction of let's actually Define a good clean open API and I may have to looks like I may have. ✪
Mike Prorock: Did I nope this actually looks right I thought I may not have backed out the auto generated stuff but it looks like it did but this goes through and covers things like how do I get a credential how do I get a credential by and I get a list of credentials right how do I get a credential by ID Etc if this is not perfect this is intended to be this is a start there are things like pagination for instance that we. ✪
Mike Prorock: Define a pattern by which we follow like do we want to return total pages in a wrapper object and stuff like that those are all common things that get done but we will want to agree as a you know group as to the best pattern to handle that for everything across the board like it in fact pagination came up was that to PR's back that we were looking at right so there are things like that that we will want to Define one sim and reuse as a pattern elsewhere. ✪
Mike Prorock: You know Getters and Killers since we have a lot of post you know type operations this is kind of starting to fill in the rest and I think I put puts in there as well I don't recall but wanted to basically say yep let's define this basic pattern if it makes sense we can get this one in and then we can build off of that and fill in gaps for other things that maybe stateful and persisted on the server side. ✪
Manu Sporny: All right thank you for that Mike any questions or concerns about this PR. ✪
Manu Sporny: I do have one kind of set of questions Mike it's so I've got no objections to marching this I don't know Longleaf we have a position on gets around credentials or presentations so just as long as folks kind of know that like we don't have an opinion on this right now but we may form one in the future. ✪
Manu Sporny: We don't like it but certainly like let's define it see get some implementation variance and then see where we know what folks think about it. ✪
Mike Prorock: Exactly makes total sense in it and part of the reason that I want to get this in as like if we think from like a trade credentialing side right if I if we're going ahead and pushing presentations of credentials over and someone has an issue with one right they may need to call back and say hey give me that credential by this idea again right I I missed something on my end or I blew something up you know or need to retrieve some data so a lot of those kind of core things that come up in practice that we're doing already. ✪
Mike Prorock: We probably should just Define so. ✪
Dave Longley: Yeah I don't have any objections to how it's going so far a lot of this stuff is happening on the on the holder API side of things one thing that has been going on in issues I saw that the the exchanges API is tucked in here with the older API and one of the things we're talking about is how we might want to actually separate that out and have exchangers be their own entity so that's something else to consider in a in a future PR. ✪
<orie> I would be fine seeing the exchange apis pulled out of holder apis
<orie> I welcome a PR to that effecct
Manu Sporny: All right good good things to consider all around would anyone objected this point merging this in the next week I mean we'll give it you know a couple more days to make sure that everyone is able to take a look at it or he's saying he'd be fine seeing exchange apis pulled out a holder apis. ✪
Manu Sporny: Maybe we can do a PR I'm sorry there's a q Marcus go ahead. ✪
Markus Sabadello: I feel like it's a bit strange that we haven't had this before why didn't we think about this in the in the beginning I think we may have discussed this at some point and decided that maybe we didn't want this and maybe we wanted the API to do not have storage or not I do not remember the very fiber credentials but I think it's fine so I'm also. ✪
Markus Sabadello: You to this should be optional right so there could be implementations that can issue but then don't remember what they issued but other than that I think this is good. ✪
Mike Prorock: Yeah I was going to say a big plus 12 pulling exchanges out into their own kind of deal like how do I manage workflows around stuff like I think that would be dependent on the prior PR that kind of cleans up the open API spec then this one and then I think naturally that would lead to us then breaking exchange out into its own now that we can actually bundle stuff properly and then tag it properly as well so I'm a big fan of that the. ✪
Mike Prorock: I think the main reason that I kept this. ✪
Mike Prorock: Holder type operations is that's the area where you are by definition like you're holding something right so you need to be able to Define how do you go get something out of that how do you you know you know delete something that's in there how do you update something that's in their etcetera right those are all the implicit kinds of operations and it has strong ramifications and implicit requirements around things like revocation right you need to be able to do these kinds of operations in order to cleanly check revocations or cross-checked it. ✪
Manu Sporny: Right okay I mean it sounds like there's you know a lot of support for this Marcus yes like you've got an excellent memory Marcus I do remember us talking about how we might not want these apis to be super stateful and so plus 12 making it an optional thing. ✪
Dave Longley: Yeah and I just I want Mike said a lot that I agreed with and my read on this was that this is mostly just around holder apis has mentioned before and I think that that's a little bit new from the original discussions we had a while back where we're focusing on issue we're in verifier and the fact that I see this stuff only going into the holder API is why I am supportive of it it's not imposing anything on issuer verifier apis to add. ✪
Dave Longley: Add storage or special access to credentials. ✪
Dave Longley: You know this is this is tied to a holder API were which implicitly or supposed to represent some kind of storage or the ability to get access to some kind of storage of credentials. ✪
Orie Steele: The current revocation apis with the issuer update credential status operation or stateful and they imply ability to store credentials and resolve them over the network and it is totally broken that we happen to find that endpoint in some way in these sets of apis so yes like get operations are a thing developers are going to reach for. ✪
Orie Steele: That we have a broken revocation feature in the current sets of apis because we don't Define how to get that revocation list credential so it definitely needs to be fixed. ✪
<dave_longley> well, status list / revocation list specs define how to get the revocation VC
Mike Prorock: Yeah and it and I think or he's getting at something that's important well Lori Mike Europe this transcriber makes me happy sometimes sorry the but yeah I two things you know one in relation to Horry and then one in relation to mr. Dave Longley there the when we look at things like updating credential status that really is a put operation of. ✪
Mike Prorock: That you're actually holding something right because otherwise how would you be updating it so I there is this sets up the ability to start more cleanly defining that stuff right that's probably misplaced being in the issuer side of the world and in fact thought very hard about pulling that over into the holders into finding it there properly but it did we can deal with that at a later date and I think you know Dave to. ✪
Orie Steele: +1 To what mike is saying, revocation apis need to be updated or removed. ✪
Mike Prorock: Ality that's one of the reasons we have these separate roles is by definition you could go in and pick out and say nope I'm only doing stateless issuer or verifier type operations cool great awesome you know but if you do want to get into that holder aspect which is going to have other security requirements and operational that's pretty well you know it's implying some kind of state or you can't do it like revocation list for instance or an obvious one retrieval in the event of a storage failure is another one. ✪
Mike Prorock: Right so we're going to have to go in and Define the stuff cleanly. ✪
Mike Prorock: About saying well if you define a holder you can opt into the ability for someone wanting to use older stuff to go get a credential like that makes me a little nervous but I think from a role-based as far as opting into what roles you're filling that makes sense to me. ✪
Dave Longley: Yeah just one quick point to make I agree with most of what's been said here we'll there are some interesting lines for which you know buckets Things fall into whether or not an issue is being which which holder role are you playing or you holding credentials for X Y or Z the the if we're talking about revocation and certainly their stateful information with issuers and. ✪
<orie> an issuer is a holder of revocation list credentials.
Dave Longley: Apple for it to be a good verifier for for to be an issuer that does revocation need to be able to hold on or reference revocation lists credentials and someplace and but currently in the API we you know or he was saying it's broken I don't think that it's actually broken right now we just defer to revocation list specifications to say this is how you go fetch the revocation credential and that does work with the apis we have it's just not bound to these other restful. ✪
Dave Longley: Apis for fetching credentials and we should consider. ✪
Dave Longley: Was revocation list credentials go into the same bucket that you would find these other credentials and or you talking about a different holder instance those sorts of things are questions that are going to come up in the future. ✪
Manu Sporny: All right thanks Dave Keys Emmy we've had a good bit of discussion all good things to keep in mind as we move forward on this but I'm not hearing any one objecting strongly to merging this after a couple of days. ✪
Manu Sporny: Okay now that is that item let's see what's next up we're actually almost all the way through all over P ours. ✪
Topic: Add JSON Schema renderer for ReSpec
Manu Sporny: So next up is adding a Json schema render for Respec. ✪
Manu Sporny: This is my futile attempt to try and render open API specifications and Respec and auto-generate normative spec language from it the initial experiment didn't get I mean it went fairly well like So currently in the VC API spec let me see what we have today right today if you look at one of the definitions it's looks awful. ✪
Manu Sporny: You can't really make out and there's just a lot of it that kind of stuff right so I wrote a Respec renderer to render that Json schema to look like this this is the first iteration but it does you know show you kind of the object that you should expect and the values there and even generate some normative text where it says like each item in the context array must be a string that comes directly from. ✪
Manu Sporny: Whatever changes we make to the Json schema is are automatically rendered and reflected in the Respec file and hopefully helps people kind of understand the type of objects they should be sending in future work includes including the examples in here in you know getting some things better it's really hard to generate human-readable pros from Json schema but you know. ✪
Manu Sporny: We have some gaps and it's so doing this exposed a bunch of gaps in the Json schema we have in fact some of the descriptions we have are pretty awful in some cases we don't have an explanation of what thing is like this is not a bug it's just we totally don't talk about you know the description here in some cases we put examples in with the Json schema text and other cases we actually Define an. ✪
Manu Sporny: Fourth so one good thing that came out of this is it caught a bunch of bugs that we have in our actual Json schema. ✪
<orie> pretty sure you can see all those bugs in the rendered specs
<orie> before
Manu Sporny: Okay so that's that PR it just changes this pure Json schema output to something that's rendered a bit more nicely comments thoughts concerns. ✪
Orie Steele: Is this handle any of one of conditional type checking for Json schema and so it will render its fully supporting all of the features of open API specification 3s profile of Json schema. ✪
Manu Sporny: Fully supporting no but in time it will I only had a couple hours over the weekend to do this so so for example the any of is if you look right here the issuer object must be either a string or an object of the following form that is an any of statement in the OAS file so absolutely we you know I we have to support that stuff if we're going to render it but this is an example of its supporting any of. ✪
Orie Steele: I think it's beautiful actually personally I love it my favorite things of all time is that you can see a rendering of this exact stuff currently with any off-the-shelf open API specification rendering tool. ✪
Manu Sporny: Yeah yeah the the writing the render of those difficult so so at different levels they do different things and there's a whole bunch of like if then switch statements that nobody should care about but I'm just saying like it'll take a while to get there but you know that this was able you know I was able to do this in a couple hours it's probably not going to be hard to get the rest of the stuff supported. ✪
Orie Steele: I mean I know what I'm about to say is probably not going to come across well I'm trying but I would much prefer to see pull requests editing these definitions in the existing renderer than see pull requests to finding a new render open API specification 3. ✪
Manu Sporny: Sure I'll handle that w3c has certain things that they expect in your specification there there are a couple of options we have we can either say in order to be conformant with this specification you must be fully comport informant with the entirety of the Json schema. ✪
<orie> its OAS3.0
Manu Sporny: And there's one normative statement in the specification I don't expect something like that to go over well or os3 or whatever it is right we just basically say the spec is the spec only has one normative statement where it's like. ✪
<orie> The spec is defined in OAS3.0
Manu Sporny: 30 And that's the only misstatement we have versus having actual you know normative statements in the spec and being able to have test Suites you know that that test that stuff. ✪
Manu Sporny: My suggestion is that we it is it is going to be very hard for people to look at this in kind of understand what's going on by just looking at pure Json schema in the render Json schema while web developers cannot work with it it it. ✪
Manu Sporny: Is not have the type of normative statements that are expected in most you know standards thing so this is an attempt to bridge the world so that the folks that want a Json schema can have a Json schema in that can render it in any way that they want to but it's also expressed in a way that makes sense to w3c in because all of that is being Auto generated from the same Source it all says the same thing like normatively right. ✪
Manu Sporny: That's it so that's my you know that is why I feel pretty strongly that we need this renderer because without it the spec doesn't really say much of anything. ✪
Mike Prorock: I think I'm on Q there maybe I didn't add right but you know the other thought is that because there's kind of two things one is kind of is this and Reese back from a formatting and a theming standpoint and then you know rendered out you know in a way that's consumable preferably with as much optionality as Pate you know possible to make sure that it you know all the actual details to objects or captured etcetera. ✪
Orie Steele: +1 To theming an existing tool, and not reinventing wheels ✪
Mike Prorock: Hi is just putting a theme together for you know in a config together for something like a crappy doc or redock and have it render out as you know you know with respect boundaries around it etcetera right and just insert that stuff as header and footer in the templates I mean that that is an option and then we're not worrying about the renderer you know you know like interpreting and rendering this stuff right. ✪
Mike Prorock: Hurting you know normative text where it needs to be inserted. ✪
Manu Sporny: Episode two questions is anyone under the impression that 100% of this is not Auto generated like so or you said something that made it seem like you thought that this is hand-written stuff. ✪
Orie Steele: No I wasn't trying to infer that I was asking whether you supported all of the features of open API specification that we automatically validate because if you don't you'll be maintaining that difference for this tool whereas we wouldn't have that issue if we just used an existing tool that implemented all those features. ✪
Manu Sporny: If someone wants to raise a PR that uses an existing tool to render this stuff in a way that makes sense to like either any any kind of you know standards ITF spec or w3c spec like plus 12 that I did look at doing that in some of the challenges with all of these tools is that they view themselves as kind of the center of the world and they are the. ✪
Manu Sporny: One that is going to be creating the. ✪
<dave_longley> i.e., the renderer output should create W3C normative statements
Manu Sporny: And rendering it in you know the appropriate way in that stuff was not easily importable into Respec. ✪
Manu Sporny: The other issue of course is that those things what what's in this Json schema files contain zero normative language so there's that challenge as well. ✪
Manu Sporny: So I mean plus 12 someone doing the work and you know creating a renderer I tried doing that it was not he liked it it I could not see a path through the jungle primarily because of the way these renders tend to basically create the structure of the document and then just change the CSS classes go ahead or. ✪
Orie Steele: Yep I mean I understand the desire to have w3c you know normative language rendered out with these mosques and certainly you've created a tool here that does that I am not volunteering to assist you in the development maintenance or configuration of this tool I am committed to maintaining these API definitions and open API specification three I think it is a mistake to invest in this kind of. ✪
Orie Steele: All time on it and we have redock and Swagger renderers for open API specification free and I think it would be better to have a single normative statement that said conformant implementations implement the open API specification 3. ✪
Orie Steele: As a single normative requirement feels to me much better because it makes us put our effort into the spec instead of putting our effort into normative statements under every field and property in the spec we have to actually make the API spec clean and consistent and I think it aligns incentives properly so I mean again like I appreciate the tool it looks very nice but you know I'm definitely not volunteering to assist in any kind of work on this. ✪
Manu Sporny: Yep plus 1 I wasn't expecting anyone to help with maintenance of this tool. ✪
Dave Longley: Is there any other w3c spec that we can turn to that as presidents here so we can copy what they're doing or we get again doing something brand new. ✪
<orie> W3C generally doesn't do HTTP APIs, haven't you heard?
<orie> lol
<orie> /s
Manu Sporny: They they all the w3c specs all the specs that I've seen that have come out of standard-setting organizations have handwritten all the normative language when Horry that is not true w3c has defined HTTP apis before. ✪
Manu Sporny: The linked data platform is an example. ✪
Dmitri Zagidulin: I think that was before OAS was popular. ✪
Manu Sporny: Yep yeah just to be clear like the core definition happens in OS nobody's saying that that changes. ✪
Manu Sporny: Okay anyone else want to weigh in on this so I'm hearing opposition to this PR. ✪
Mike Prorock: I am not opposed to be our I'm kind of more along the lines of like is there perhaps more efficiently and I'm just not 100% sure just because we've done some pretty crazy redeeming without a huge amount of effort on both rapid Dock and ridak Lee the I did note that the open API spec and I think it got lost by the transcriber but like the guys that actually have the. ✪
Mike Prorock: Open API specification right away I. ✪
Mike Prorock: They are generating from you know you know just using the normal ITF approach and then generating Respec from that I'm what I've not dug into yet is how much are they like defining normative text or dividing themselves in open API specification but that is something that they for sure are doing and are generating out clean Respec with you know with full documentation itself. ✪
Orie Steele: To be clear I did approve the polar. ✪
Manu Sporny: Okay yeah I mean plus 1 I don't want to be maintaining this tooling either but it's the only way that I can see putting it into a format that w3c members are going to like recognize all right otherwise we're going to be paying you know fighting an uphill battle of trying to convince w3c that they should be using OAS to Define specs and maybe that'll you know happen just fine. ✪
Manu Sporny: Yeah but plus 1 if somebody else wants to do the work to make this easier or put it into some kind of format that's going to be easy to put through you know w3c and or ITF like please help to do that and I realize that you know people may not want to help with this current tool but I'm fine with that. ✪
Manu Sporny: All righty that's it for the call today sorry when a minute over thanks everyone for the great discussion thanks folks for the PRS I think we're clear on actions so please look at the issues and see if there's some PRS that you can raise or want to raise before next week's call we will probably not meet if they're not new people. ✪
Manu Sporny: Raise some PR s if you feel that there's a certain item that needs to be pushed forward with that thanks everyone for the call see you all next week bye. ✪