search

json-schema-org / referencing

Proposals for a possible specification encompassing the varying uses of "$ref"
MIT License
6 stars 1 forks source link

New Proposal: JSON Reference (JRef) media type #4

Closed jdesrosiers closed 2 years ago

jdesrosiers commented 2 years ago

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 https://github.com/json-schema-org/referencing/issues/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 commented 2 years ago

@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 https://github.com/json-schema-org/referencing/issues/7 for now to get some context. That's the only thing that jumped out at me.

jdesrosiers commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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.