Hyper-schema: "create" is not an IANA link relation

[awwright]

The JSON Hyper-schema spec currently lists the following

       {
           "title": "Post a comment",
           "rel": "create",
           "href": "/{id}/comments",
           "method": "POST",
           "schema": {
               "type": "object",
               "properties": {
                   "message": {
                       "type": "string"
                   }
               },
               "required": ["message"]
           }
       }

But this isn't a useful link relation because there's no such thing as a "create" link.

The place that would best define how to create resources would probably AtomPub, see https://tools.ietf.org/rfc/rfc5023.txt

The specification does later define "create", but it should normatively reference the IANA registry instead.

[handrews]

Apparently the "rel"s are supposed to be URIs already? https://github.com/json-schema/json-schema/wiki/More-templating-(v5-proposal)

It's not clear to me how that is supposed to work, but it seems like @geraintluff had something in mind for this?

I think it's worth considering a bit of inspiration from JSON-LD's notion of a "context" to allow working with concise names for unregistered relations. I'd call it something like "relBase" and make it a schema-level field (applying to all LDOs for that schema and any contained schemas unless overridden by a closer "relBase") Whether or not that's reasonable for v5 I guess depends on what answer you get in issue #48 about how much use hyper-schema has actually seen.

[awwright]

Take a look at the RFC for Web Linking and HTML, rel can be an IANA-registered keyword or a URI. If it's a keyword, it can still also be mapped to a URI with the default URI base < http://www.iana.org/assignments/relation/>.

On Sep 17, 2016 14:28, "Henry Andrews" notifications@github.com wrote:

Apparently the "rel"s are supposed to be URIs already? https://github.com/json-schema/json-schema/wiki/More- templating-(v5-proposal)

It's not clear to me how that is supposed to work, but it seems like @geraintluff https://github.com/geraintluff had something in mind for this?

I think it's worth considering a bit of inspiration from JSON-LD's notion of a "context" to allow working with concise names for unregistered relations. I'd call it something like "relBase" and make it a schema-level field (applying to all LDOs for that schema and any contained schemas unless overridden by a closer "relBase") Whether or not that's reasonable for v5 I guess depends on what answer you get in issue #48 https://github.com/json-schema-org/json-schema-spec/issues/48 about how much use hyper-schema has actually seen.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/json-schema-org/json-schema-spec/issues/47#issuecomment-247809176, or mute the thread https://github.com/notifications/unsubscribe-auth/AAatDYmrtiN3pZ6S6w2cCauzjG5BgQkQks5qrFtpgaJpZM4J9K4M .

[handrews]

@awwright Are you talking about the "Context IRI"? That defaults to the IRI of the current resource, which I believe would be the schema document. That would mean that the "create" rel in each schema is in fact a different relation from the "create" rels in any other schema. While that definitely avoids relation URI collisions, it also makes the relations overly specific by default.

(also, should JSON Schema be specifying IRI in place of URI anywhere? Even the web linking RFC mixes IRIs and URIs in a way that I find totally confusing).

[awwright]

What Geraint was saying is that "rel" is also a URI reference, very much the same way "href" is. See the definition in Web Linking. And so he figures why can't we use templates there, too?

The difference is you have to specify either a full URI or an IANA-registered keyword. If you specify a keyword, it's resolved against the special URI base <http://www.iana.org/assignments/relation/>.

As for IRI, if we switch to using IRI we gain the ability to use Unicode characters in links. I suppose that could be useful, I'll make an issue.

[handrews]

@awwright Understand that rel is, according to the web linking RFC, a URI. What I don't understand is how that URI is resolved. If {"rel": "next"} is supposed to indicate the IANA standardized "next" relation, how do we resolve {"rel": "somethingThatIsNotStandard"} as a URI? Do we have to check IANA first? Can that even be done programmatically? Do all "rel" values that are not IANA-registered need to be full URIs instead of URI references?

[awwright]

@handrews In that case you'd get <http://www.iana.org/assignments/relation/somethingThatIsNotStandard> which isn't a defined link relation.

Addition of a link relation to that registry can be requested by anyone, but it requires expert review.

[handrews]

OK. So as mentioned in issue #48 just now, JSON Hyper-schema proposes full, instances, create, and root as new IANA registered link relations. instances makes no sense because IANA already has a collection link. The IANA item link are full aren't doing quite the same thing, so I can see adding full (although having to define both full and item in a lot of places is mildly annoying).

If we register a create link do we also register other CRUD-ish links? Including a distinction between full replacement vs patching?

root is weird- I get what it's doing, but it is strange to me that a link should redefine how something is interpreted like this. If you want to link to a point inside a resource representation, just put the fragment on the link URI.

[awwright]

fwiw, I'm not actually opposed to the idea of a "create" link relation, having an explicit "append this to a collection" resource might be useful (normally you just POST to the collection), but it really has no business being in JSON Schema.

[handrews]

Should we be using "create-form" and "edit-form"? I'm not entirely clear on this point, but I think that despite the name these links are not specific to HTML forms. They just indicate a submittable resource.

Given that "create-form" requires HTTP POST unless otherwise specified, and "edit-form" similarly requires HTTP PUT, these relations fit very well with the principle of not specifying HTTP methods in JSON Hyper-Schema (I'm increasingly coming around to this position due to JSON Home addressing the things for I would have needed explicit HTTP method specification).

And by "using", I mean "not defining other links in the Hyper-Schema spec that do the same thing as these". I don't mean requiring their use.

[awwright]

edit-form and create-form are intended to link to an actual HTML form that provides editing capabilities. It's for Web browsers.

On Oct 12, 2016 12:28 PM, "Henry Andrews" notifications@github.com wrote:

Should we be using "create-form" and "edit-form" https://tools.ietf.org/html/rfc6861? I'm not entirely clear on this point, but I think that despite the name these links are not specific to HTML forms. They just indicate a submittable resource.

Given that "create-form" requires HTTP POST unless otherwise specified, and "edit-form" similarly requires HTTP PUT, these relations fit very well with the principle of not specifying HTTP methods in JSON Hyper-Schema (I'm increasingly coming around to this position due to JSON Home addressing the things for I would have needed explicit HTTP method specification).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/json-schema-org/json-schema-spec/issues/47#issuecomment-253313586, or mute the thread https://github.com/notifications/unsubscribe-auth/AAatDS7JMqM9sKQc2Xo0lt7I1rQr-ZMEks5qzTTggaJpZM4J9K4M .

[handrews]

Is that required by the use of the words "input form"? The word "browser" does not appear anywhere in the RFC, just "automated agent". I was reading this sentence:

The "create-form" and "edit-form" link relations are intentionally generic, and they can be used with multiple media types in a wide variety of use cases.

to mean that while HTML forms motivated the links, they could be used more broadly. I suppose that just means for media types that also only produce interactive forms?

[awwright]

Well, but more specifically it's going to show you a document that contains details on how to edit the resource, or how to create a new instance.

Right now the only thing that can do this in any capacity is HTML though. Or maybe XForms.

On Oct 12, 2016 12:44 PM, "Henry Andrews" notifications@github.com wrote:

Is that required by the use of the words "input form"? The word "browser" does not appear anywhere in the RFC, just "automated agent". I was reading this sentence:

The "create-form" and "edit-form" link relations are intentionally generic, and they can be used with multiple media types in a wide variety of use cases.

to mean that while HTML forms motivated the links, they could be used more broadly. I suppose that just means for media types that also only produce interactive forms?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/json-schema-org/json-schema-spec/issues/47#issuecomment-253317357, or mute the thread https://github.com/notifications/unsubscribe-auth/AAatDWaJoGh-6qNGK9HOZpsJPdKnpq_jks5qzTiCgaJpZM4J9K4M .

[awwright]

I believe I fixed this to my satisfaction, I'll go ahead and close this out B-)

[handrews]

For anyone else who comes along and reads this, @awwright fixed it by removing all of the relation declarations (I agree they have no place here).

[Relequestual]

Is there an intention to later add this kind of functionality back or not? I could see how it could be useful, but it may be already covered by other parts of the spec (I don't know)

[awwright]

If someone can tell me how the functionality is useful, we can figure out if it's a good fit for JSON Hyper-schema and how to implement it if so.

The stuff that was taken out was either unused or not in-scope for a hypermedia media type. This is the only significant case where actual functionality was changed.

[Relequestual]

From the perspective of where I intend to use json-schema, it kind of has a nice fit. Although, that sort of functionality may be better left to specifications which are designed for specifying an API, like RAML.