Remove "method", add "form"

[handrews]

NOTE: IGNORE THE FIRST COMMIT

This is the 2nd half of the proposed resolution to #280.

The first commit has been posted separately as PR #289, please review it there.
The second commit is here:

REVIEW THIS: 82e783b

Assuming #289 gets approved (it is much simpler), I will rebase this PR to only be the 2nd commit.

---

This removes the "method" keyword and reworks all references to
HTML forms. The difference in approach between JSON Hyper-Schema
and HTML+JavaScript is explained, and the different sorts of links
(in terms of data usage) are described.

The "form" keyword is being added to indicate HTML POST form
semantics. GET forms can be simulated with "hrefSchema", and the
guidance on that has been made more clear.

We also now clearly acknowldege that you cannot directly specify
HTML methods, as that was the largest source of confusion in the
feedback to the previous draft.

[jdesrosiers]

Is "HTML POST form" the right way to reference this?

The use of capital "POST" seems to refer (by convention) to the HTTP method POST. However, the functionality we are referencing is a form's method="post" functionality which is not the same thing as HTTP POST.

[handrews]

The HTML spec capitalizes it, so that's what I did. But that is why it is always "HTML POST" and never just "POST". If we talk about using HTTP POST then it will be "HTTP POST" (apparently I don't mention it in the current version).

There's not much I can do about the fact that HTML vs HTTP POST is confusing AF except for always prefixing "POST" with the correct spec.

[awwright]

I've always thought it's typically lowercased in method=, or at least in XHTML. I've never actually bothered looking it up. I do think lowercase is a good way to differentiate the usages, though. HTTP is case-sensitive, HTML isn't.

[handrews]

Well, either way I went back to the HTML5 specification and I clearly misread it because the terms are lower-case. I will update this PR accordingly (I also agree with both of your concerns, I had just misread the other spec and thought I was following it)

[jdesrosiers]

Again, I take issue with describing this as "imposing additional constraints". A form with method="post" is a construct specifically for sending data to an executable resource. It's not a constraint that submissionSchema should be used in this case, it's just that doing so is the only way to accomplish the goal of sending data to an executable resource. It's the same with the choice of HTTP method. There is no explicit constraint that POST should be used, it just happens to be the only way to satisfy the goal of the construct.

[handrews]

I'm afraid I just don't understand your distinction.

It is already the case that submissionSchema is the only way to accomplish the goal of sending data to an executable resource. That is its purpose, and the presence or value of form is completely irrelevant to the semantics of the submission keywords.

The only thing that "form": true changes is forbidding any other operations. If that's not a constraint I don't know what is.

[awwright]

@jdesrosiers Can you elaborate some on how clients, as you would like to see, might act differently for different values of "method" or "form"?

[handrews]

Can you elaborate some on how clients, as you would like to see, might act differently for different values of "method" or "form"?

Yeah, this would help me a lot. I'm not trying to be difficult with this, but if I knew what you want a conforming implementation to do that would help with the wording.

As I understand it now, it's mostly documentation:

• For an HTTP link, I would expect a server that receives a POST with a payload that does not validate against the submission schema, it will return a 400 Bad Request. I would expect this regardless of "form".

• While I would expect the resource to return 405 Not Allowed for any non-POST method if a "form": true link is the only link to the target resource, there is no way in a true hypermedia system to know whether the target resource has non-POST behavior that is indicated by some other link elsewhere (such as its own self link, or a third resource with a very different semantic relation to the target). So I can't make any assumptions about behavior because of "form": true either.

[jdesrosiers]

Can you elaborate some on how clients, as you would like to see, might act differently for different values of "method" or "form"?

Honestly, I'm a little perplexed by this question. First of all, method doesn't exist in this context. "method": "post" was replaced with "form": true and "method": "get" was removed in favor of hrefSchema. So there are only two possible values. Understanding the difference is no harder than understanding HTML. How does a client act differently when it encounters an <a> opposed to encountering a <form>.

1. "form": false (default)
   The LDO is analogous to an <a>. Really, it's closer to the Link header, but that's not really the point. A client can do anything with that link that it has enough information to do. A web browser doesn't have enough information to do anything but retrieve it. An LDO with "form": false has more information than an <a> allowing a client to do more things with it based on target hints, but it is basically the same thing.

2. "form": true
   The LDO is analogous to a <form>. A <form> is a construct for sending data to a resource. A client can proceed taking that assumption into account. For example a client knows it is going to need user input and should prompt the user for that data. This is different from a Link where you would have to first select which method you want to use, then the client determines if it needs to prompt the user for input.

It's pretty obvious how a web browser behaves differently when it encounters an <a> versus when it encounters a <form>. It should be no less obvious for a hyper-schema client encountering "form": false versus "form": true.

[handrews]

@jdesrosiers I just don't understand why you need a special keyword for this. If there's a "submissionSchema", it can be used as a form. If there's not, it can't.

The other aspects of HTML's constructs have to do with human presentation, which is not a concern of JSON of JSON Hyper-Schema. There will often not be any human involved in the interactions at all.

[handrews]

@jdesrosiers are you trying to distinguish between submission schemas that require actual human user input vs those that do not?

[dlax]

I feel somewhat puzzled by all these new references to JavaScript. In some respect, these could be interpreted as "you need javascript to operate this sort of link" (or taking a step back, "you need a programming language") whereas it seems to me that any kind of intelligent client (including non-programmatic ones, like CLI) should be considered as first-class citizen.

[dlax]

Also, I wonder if intensive references to HTML (and HTML <form> in particular) is really a good idea. It seems to me that this just reflects the context of recent discussions (on method="post", etc.) and would appear as rather "historical" when reading the spec at some point later in time. I reckon that it is important to mention, but maybe in a less repetitive manner?

[handrews]

@dlax good feedback, thanks.

I've been struggling with the HTML analogies throughout Hyper-Schema as I feel like HTML is a totally unsuitable approach for machine-oriented hypermedia. The comparisons to HTML forms are, in my opinion, the root of most of the worst confusions around Hyper-Schema.

If we must compare Hyper-Schema to the human web, it is the hypermedia functionality offered by the combination of HTML and JavaScript that is the thing to which we should compare Hyper-Schema.

But if it's not helpful I will remove it.

I'm honestly not sure what to do with this anymore. I'm still strongly in favor of removing "method" but I don't understand where anyone else wants to go with it. But I don't think the Hyper-Schema draft as it currently stands on master is worth publishing given that we can't even figure out how to use it ourselves.

[handrews]

@dlax I hadn't seen your second comment when I wrote my last response.

JSON Hyper-Schema's "method", "encType", and "schema" keywords were originally explicitly intended to mimic HTML forms. And I have not been successful in convincing people that HTML is an awful reference point that does more harm than good. So... here we are. I'm trying to work with the desire that several project contributors seem to have to draw analogues to HTML, but it's hard to do well when I don't think it's useful in the first place.

We'll figure something out, but I admit to being kinda stumped at the moment. I might not be the right person to write this particular PR.

[dlax]

Henry Andrews a écrit :

I've been struggling with the HTML analogies throughout Hyper-Schema as I feel like HTML is a totally unsuitable approach for machine-oriented hypermedia. The comparisons to HTML forms are, in my opinion, the root of most of the worst confusions around Hyper-Schema.

I totally agree with that.

If we must compare Hyper-Schema to the human web, it is the hypermedia functionality offered by the combination of HTML and JavaScript that is the thing to which we should compare Hyper-Schema. But if it's not helpful I will remove it.

It's not unhelpful, but it may be misleading, in particular as it appears in several places. I think more allusive mentions would be more suitable.

I'm honestly not sure what to do with this anymore. I'm still strongly in favor of removing |"method"| but I don't understand where anyone else wants to go with it. But I don't think the Hyper-Schema draft as it currently stands on master is worth publishing given that we can't even figure out how to use it ourselves.

I also agree with removing "method". My confusion comes from the fact that this PR does not just do this, but also introduces a lot of references. Somehow it's a matter of this project's workflow but I, for one, would be more comfortable if this were done as distinct commits.

[dlax]

@handrews

JSON Hyper-Schema's "method", "encType", and "schema" keywords were
originally explicitly intended to mimic HTML forms. And I have not been
successful in convincing people that HTML is an awful reference point
that does more harm than good.

At least, I am convinced :)

[handrews]

The JavaScript stuff can definitely be taken out and either re-introduced later or just dumped.

But you can't remove "method" without reworking things all over the place, and you can't add "form" without explaining how it fits into the data use. I didn't touch anything that didn't have to be touched, so while we can change the approach, or how verbose vs minimal some part is, I won't be splitting this up. It either holds together as a coherent whole or it's not worth keeping. I'm not willing to have a commit where the spec contradicts itself and references keywords that don't exist.

[handrews]

Given that this doesn't even do what @jdesrosiers wanted from the proposal, it's probably better to dump this anyway.

[handrews]

I'd be happy to split removing "method" and adding "form" into separate commits, as just removing "method" doesn't require as much explanation.

[dlax]

I'd be happy to split removing "method" and adding "form" into separate commits, as just removing "method" doesn't require as much explanation.

To be honest, I don't quite understand what "form" is for. I guess this has been discussed somewhere else, any pointer?
By now, this previous comment :

I just don't understand why you need a special keyword for this. If there's a "submissionSchema", it can be used as a form. If there's not, it can't.

captures my understanding quite well.

[Relequestual]

To my mind (not having read all of the issues and PRs in the last 3-5 days), the lack of clear use cases is causing a lot of confused discussion. Everyone seems to be making different assumptions about what they WANT JHS to do, and how.

Maybe we need use cases which inform a requirements list of what should be possible (and what should not). That seems to be the cause of most confusion.

I know @handrews has been writing a document on how hypermedia in general should work.

[handrews]

@dlax "form" just comes from the discussion in #280.

Having slept on this, I think I'm going to try to do the following:

• Submit a minimal PR for removing "method"
• Submit any additional reworking of the "Links and data" section that seems necessary
• Wait for the discussion of "form" to clarify before writing that up

@jdesrosiers I don't know if you want to move the "form" discussion to its own issue or keep talking in the PRs, I am fine with whichever. Even if the other PRs I'm about to split out are approved we can hold off on acting on them until we have some agreement on "form".

[handrews]

Closing this in favor of #292, #293, and a future PR about "form" once we have a better handle on what it needs to do.

[jdesrosiers]

I know this PR is closed, but I have a few cleanup remarks and questions to answer.

I just don't understand why you need a special keyword for this. If there's a "submissionSchema", it can be used as a form. If there's not, it can't.

@handrews @dlax You're right, but that's not the point. Try to view this from a different perspective. You have an LDO with a submissionSchema. The question isn't how do you know you can use it to send data to a resource (POST), the question is how do you know that you can't retrieve it (GET). @awwright wrote up a list of 4 or 5 ways an LDO can be used. That makes it sound versatile, but it is also ambiguous. Say I have an LDO that only supports sending data to an executable resource. I don't want to signal to a user-agent that there are 4 or 5 things you can do with this LDO when there is really only one. Using form allows me to signal that this LDO has one use only: sending data to an executable resource. Best of all, I get this in a way that is completely decoupled from HTTP methods. Even if we add a method hint in the future, it would be superfluous for a "form": true LDO. Ultimately I want to get to a place with the spec where method hints are unnecessary. I'll be bringing this up in more detail of the next draft (hopefully).

are you trying to distinguish between submission schemas that require actual human user input vs those that do not?

@handrews No, as we have discussed before, I make no distinction between different sources of input. It's all the same to hyper-schema. If I remember correctly, we agreed on that point.

I feel somewhat puzzled by all these new references to JavaScript

@handrews @dlax I thought the discussion was clear and made sense, but I didn't think it was necessary. it seemed more appropriate in a blog post explaining your take on hyper-schema. My vote would be to leave it out, but I don't think it hurts others disagree.

I'm trying to work with the desire that several project contributors seem to have to draw analogues to HTML

Yeah, one of them is me. The web is the reference implementation for REST. I'm not saying it's perfect or that we should be trying to clone the web in JSON, but it would be silly to ignore it's lessons or assume they don't apply to our situation.

Having slept on this, I think I'm going to try to do the following:

• Submit a minimal PR for removing "method"
• Submit any additional reworking of the "Links and data" section that seems necessary
• Wait for the discussion of "form" to clarify before writing that up

I endorse this plan. I've also decided that I won't hold up draft-06 for form. I'm not done with arguing for this concept and others like it, but I'm willing to wait for draft-07.

[handrews]

I endorse this plan. I've also decided that I won't hold up draft-06 for form. I'm not done with arguing for this concept and others like it, but I'm willing to wait for draft-07.

Thank you. I really do wish we could sort it out for 06 but it seems unlikely.