New Proposal: JSON Reference (JRef) media type

[jdesrosiers]

This PR adds a proposal for a JRef media type. I chose not to include commentary in the spec on why I made the decisions I made because I don't think that kind of thing belongs in a specification, but you can read #7 for more on my vision and why I made certain choices.

I wrote this in formal spec language, but it's not in I-D format and it's not necessarily complete. It should be complete enough for people to get the idea. It can be converted to I-D format later if necessary.

Disclaimer (adapted from @handrews):

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:

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 anything that's flat-out wrong

Please do not...

• Suggest substantive changes. Please go ahead and file an issue for that! (if possible, tag it with the jref 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

[gregsdennis]

@jdesrosiers how do you read $href? From the way this is written, I expect you pronounce the $. I don't pronounce it in my head; I only read "h-ref".

In a lot of places you have "a $href," which is slightly jarring to me. I think I prefer "an $href." Maybe that's just me.

Going back to read #7 for now to get some context. That's the only thing that jumped out at me.

[jdesrosiers]

I pronouce it "dollar-h-ref". In conversation I often drop the "dollar" when everyone knows what I'm talking about, but I think of $ in all the keywords as being pronounced as "dollar".

[handrews]

@jdesrosiers it turns out that the build system looks for draft-whatever.md, and I can't figure out how to exclude a file. So I think it makes sense to either rename this just jdesrosiers-jref.md or apply the following patch which will build cleanly. It's the minimal boilerplate plus adjusting heading levels to what the build wants and putting the title in the initial YAML. Whichever you prefer is fine with me:

diff --git a/draft-jdesrosiers-jref.md b/draft-jdesrosiers-jref.md
index 8453406..bd0049a 100644
--- a/draft-jdesrosiers-jref.md
+++ b/draft-jdesrosiers-jref.md
@@ -1 +1,14 @@
-# JRef Specification
+---
+title: JRef Specification
+docname: draft-jdesrosiers-jref-latest
+submissionType: IETF
+category: info
+ipr: trust200902
+
+author:
+ -
+    ins: J. Desrosiers
+    name: Jason Desrosiers
+    country: U.S.A.
+
+--- abstract
@@ -3 +15,0 @@
-## Introduction
@@ -10 +22,3 @@ resource.
-NOTE: This document is written as a spec and therefore doesn't have commentary
+--- note_Note_to_Readers
+
+This document is written as a spec and therefore doesn't have commentary
@@ -15 +29,3 @@ information see https://github.com/json-schema-org/referencing/issues/7.
-## Media Type
+--- middle
+
+# Media Type
@@ -19 +35 @@ The JRef media type is identified as `application/reference+json` and uses the
-### Fragments
+## Fragments
@@ -31 +47 @@ implementations MUST raise an error.
-### Profiles
+## Profiles
@@ -35 +51 @@ This media type allows the "profile" media type parameter as defined by [RFC
-## The "reference" Type
+# The "reference" Type
@@ -37 +53 @@ This media type allows the "profile" media type parameter as defined by [RFC
-### Syntax
+## Syntax
@@ -54 +70 @@ has a `$href` property and the value of that property is a string.
-### Following References
+## Following References
@@ -86 +102 @@ semantics of the media type of the referred to document.
-## Values
+# Values

[jdesrosiers]

Done. I went with renaming. I considered using a prefix other than "draft", but I couldn't think of a good word, so I went with your suggestion of dropping the prefix altogether.

[handrews]

I think this is straightforward and readable. As the other proposal now has two approvals and both have been up for at least two weeks, I think we can go ahead and merge these.