RFCs

[davidlehn]

I've long had an idea for starting a JSON-LD Request For Comment "RFC" system. Similar to PEPs, JEPs, XEPs, EIPs, and so on in other projects. The idea being to have a collection of docs that propose and work on new features, ideas, implementation conventions, and other related items. In some cases features may move into specs in the future. It's worked pretty well in other communities and I imagine we could grow some new ideas here too.

I don't know what name would be best... so was just thinking of being old school with RFC.

Location would perhaps be rfcs.json-ld.org, so use a new repo, make some meta rfcs and indexes, and get github pages to host it.

Not sure what file formats to suggest. Probably support both respec and markdown. Markdown because it seems a bit more lightweight when just throwing new ideas out there.

As for topics, I've got some things queued up and it's unclear where best to document them.

• benchmarking: Recommendations for common implementation standards for benchmarking so we can more easily compete compare code.
• custom API flags: Recommendations for how to pass implementation specific flags to API calls.
• safe mode: Spec for a "safe" mode to avoid common pitfalls in use cases like digital signatures. jsonld.js is getting this feature soon and it seems worthwhile to document it and collaborate with other implementations on the idea.
• well-formed mode: Ideas for higher performance when you know your input is good.

I can come up with more. I assume others can too. Some of these things seem too small to handle with their own repos and big spec docs. But a light weight RFC doc seems right.

Thoughts?

[gkellogg]

Note that RFCs are an IETF thing, but there may be a similar concept in the W3C process. As a CG, I believe we can operate any way we want, but for things to go through REC-track, we’d need to use the WG, which does have some specific process guidelines. So far, we’ve worked on separate specs (JSON-LD-star and JSON-LD Streaming, for example) that might be put forward as their own specs. I think what you’re calling for is a process that would serve as a way to better detail changes to existing JSON-LD Recommendations. The 2021 W3C Process document does define a “candidate addition” [1] that might be the way to look at this. I would think that the CG work towards a process that would lead to Candidate additions the WG could then drive through to create updated recommendations. (There are also “canidiate corrections”, which are closer to errata). The process for revising a Recommendation is detailed in [2]. Of course, work the CG does may never advance forward to the Working Group, and does not necessarily need to to be useful to the community. Clearly, at some point we’d need more advice on how to handle this specifically. This is a suitable topic for the upcoming call. Gregg Kellogg ***@***.*** [1] https://www.w3.org/2021/Process-20211102/#candidate-addition <https://www.w3.org/2021/Process-20211102/#candidate-addition> [2] https://www.w3.org/2021/Process-20211102/#revising-rec

…

On May 31, 2022, at 12:50 PM, David I. Lehn ***@***.***> wrote: I've long had an idea for starting a JSON-LD Request For Comment "RFC" system. Similar to PEPs, JEPs, XEPs, EIPs, and so on in other projects. The idea being to have a collection of docs that propose and work on new features, ideas, implementation conventions, and other related items. In some cases features may move into specs in the future. It's worked pretty well in other communities and I imagine we could grow some new ideas here too. I don't know what name would be best... so was just thinking of being old school with RFC. Location would perhaps be rfcs.json-ld.org, so use a new repo, make some meta rfcs and indexes, and get github pages to host it. Not sure what file formats to suggest. Probably support both respec and markdown. Markdown because it seems a bit more lightweight when just throwing new ideas out there. As for topics, I've got some things queued up and it's unclear where best to document them. benchmarking: Recommendations for common implementation standards for benchmarking so we can more easily compete compare code. custom API flags: Recommendations for how to pass implementation specific flags to API calls. safe mode: Spec for a "safe" mode to avoid common pitfalls in use cases like digital signatures. jsonld.js is getting this feature soon and it seems worthwhile to document it and collaborate with other implementations on the idea. well-formed mode: Ideas for higher performance when you know your input is good. I can come up with more. I assume others can too. Some of these things seem too small to handle with their own repos and big spec docs. But a light weight RFC doc seems right. Thoughts? — Reply to this email directly, view it on GitHub <#778>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAALJWHCHDUI5ZEFRTKKSF3VMZUPXANCNFSM5XOVBFMA>. You are receiving this because you are subscribed to this thread.

[davidlehn]

Yes, IETF does use RFCs, but I was aiming more at how Rust has RFCs, Python has PEPs, XMPP has XEPs, Java uses JEPs, Ethereum has EIPs, Bitcoin uses BIPs, etc. Linked this time so people can browse what I'm proposing. It could be called JEP or JIP or something if people prefer layers of acronyms.

I'm specifically looking for space and a less formal process to start the documentation ing and discuss ideas. Maybe crazy ideas that go nowhere. Maybe just guidelines. Maybe they will target spec updates, maybe not. Something between a github PR/issue and a one spec repo. I'm unsure how the W3 process docs above apply here. It seems we could have CG RFC docs that interested people can work on. Some may work out, some may not. If the RFCs turn out to be good ideas that need formalization, they could then be sent to the more formal WG process and hopefully will already be a bit more cooked than raw.

Perhaps there are not enough ideas at this level for this to be worth it? I'm not sure. If not, where would these sorts of small docs go now?

I assume we'll have more to talk about on calls than time to do so. Would be nice to get more feedback on this concept sooner rather than later. I hope to write some of these sorts of docs soon and don't know where they should go.

[gkellogg]

I was thinking that we should probably fork the WG spec repos in json-lid.org and work on updates via PR, at least for things that are updates to those specs. When we think the WG is read to move these towards an updated CR state, we can merge back into the WG repos. Issues and PRs could be tagged as RFC.

For other things, we may want to create new repos.

this would be a good topic of conversation for the upcoming CG call.

[BigBlueHat]

@davidlehn the WICG does this all the time with their specs. They're still called specs, but start their life as pretty drafty repos with a README, explainer, and a rough start to a spec file. I think we could do something similar here without much effort. Maybe just call them "Early Drafts" (though "ED" already means "Editor's Draft"--which is more or less what these would be in W3C terms afaict).

@pchampin would love your thoughts on what terminology to use here that feels more W3C native parlance. 😄

[davidlehn]

@BigBlueHat It's been a minute, and seems like my thoughts are still the same here. A basic dir of RFC dirs with respec or markdown docs and related resources seems fine. Since we may switch to a site generator sooner rather than later, putting this under /rfcs/ is probably less hassle than a subdomain. It does seem there are other viewpoints on how to do this sort of thing. I was trying to avoid complexity of repos and highly structured docs and heavy process overhead. That all seems a bit much if, say, someone wants to propose a design and simple spec doc for a single optional API flag. The ideas I had above may be larger than that, but simple docs would often work fine. I think it's worth a try to see what happens. Nothing is set in stone of course.