New proposal: JSON Referencing and Identification (JRI)

[handrews]

Note: This PR will be up for a minimum of 14 days. If we are nearing that and you want an extra couple of days to comment, please just comment with an estimate of how much additional time you need.

What this PR is about

As a "new proposal PR", this PR is for accepting a baseline from which to start discussions. As noted in the README, merging this PR does not indicate an endorsement by the JSON Schema Org, nor does it necessarily mean that it will ever be submitted to the IETF. Those things depend on the outcome of further discussions of this and other proposals.

Therefore for this and other such PRs (we expect at least one more in this repo):

Please do!

• Check that you can get the general idea of the proposal from what's currently written, even if not all details are perfectly clear
• Check for paragraphs/wording that is difficult to understand
• Check for things that seem out of order (I rearranged the order of this proposal in the last few days based on some early feedback to separate the basics, the standalone/interoperable stuff, and the context specification stuff)
• Check for anything that's flat-out wrong
• Make sure I didn't do anything like leave a section titled "Reasons" 🤦 (an early version had this b/c I forgot to come back and make a better title)

Please do not...

• Suggest substantive changes. Please go ahead and file an issue for that! (if possible, tag it with the jri label, but if GitHub won't let you, I'll take care of that) You do not need to wait for the PR to merge before filing discussion issues
• Raise questions about scope and direction in general. Please also file issues for those things without waiting for the PR to merge! As they are larger concerns than any one proposal you should not tag them with this proposal's label

How to view the file

While there are numerous commits here, that is mostly for the folks who saw an early version of this who want to see how I re-organized it since that version. Otherwise you can ignore the commits and just review the file as of the most recent commit.

See the repository README for documentation of the Markdown RFC format. A few key points:

• The first chunk of the text is a YAML header, so when you look at it as rendered Markdown it looks weird (including some giant headers that don't make sense because they're YAML comments).
• From --- abstract onwards, it's Markdown, with some additions
• {{!RFC1234}} is an automatic normative reference, {{?RFC1234}} is an automatic informative reference, and {{RFC1234}} is a reference to something that is explicitly defined in the YAML at the top of the file because the IETF doesn't have automatic entries for whatever it is (e.g. AsyncAPI and OpenAPI)
• {#foo} is the equivalent of "anchor"="foo" in XML, and {{foo}} is the corresponding xref
• Footnotes in Markdown become CREFs in the RFC, but that means that if you look at this as rendered Markdown the footnotes show up at the bottom, instead of inline like CREFs do
• You might find it easier to check out my fork and (assuming you have python3 installed) type make to get the HTML version built; this will check out a submodule containing the build scripts, install a virtualenv inside that build tree, and run the build for you

[handrews]

@gregsdennis I think I have addressed each of your comments with either a change, an explanation, or a question as to how to proceed. Please let me know if I missed anything, and thank you for the speedy review!

[handrews]

@DavidBiesack I think I have addressed all of your comments that we did not move off to separate issues. Please take a look. Since this has been open for 14 days, once you have signed off I will merge this unless something else has come up. We will continue to discuss things in issues and all are welcome to file such issues after the merge.

[handrews]

OK, @gregsdennis I think I have now addressed everything- thanks for the IM about the ones that GitHub had "conveniently" hidden.

[handrews]

@DavidBiesack thanks for the speedy review! I think I have addressed everything you raised- I have no idea how I missed the $extRef comment in particular, this PR has gotten rather confusing to follow in the UI (I missed a comment or two of @gregsdennis's as well despite going over everything multiple times). Please let me know if this is insufficient or if you notice other things I have missed. I did kind of rush this most recent update.

[handrews]

@DavidBiesack @gregsdennis thanks! I have fixed the word 🤦