"method" does not constrain HTTP methods #280
Conversation
|
The stuff about
This is the part that is in question. The following is the way I have interpretated draft-05 / draft-06. I want to be clear that I am not advocating any changes or complaining about any decisions that have already been made. The following is what I believe the spec currently expresses. @handrews and I have agreed that this isn't the time to debate what we want it to say. We just want @awwright to clarify how intended The part I have issue with is the statement that you can choose to ignore schema if you want to use that link with a method that isn't defined for an arbitrary request entity. In HTTP's uniform interface, the only method that is compatible with this type of link is POST. This might not be true of a different uniform interface, which is why this paragraph is not contradictory to the concept that That was my interpretation and the following is why I think the spec supports this interpretation. Since draft-05, the spec explicitly compares the behavior of LDO to HTML Forms. As I understand it, HTML Forms work the way I just described. |
|
@jdesrosiers I think the only difference in our interpretations is that given this:
you follow with "therefore no other HTTP method can be used", while I follow with "therefore The reason that I look at it this way is that I everything I can see and do based on your two-link approach (one This was not true in Draft 04 (or 05), but is true in Draft 06 because of the addition of So my question to you is: what problem is it causing to allow all HTTP methods with I agree that it is different from HTML, but even though we cite HTML Forms, we're already different from HTML and will more than likely continue to diverge. So I don't think that's a real problem. It's a point of confusion that requires documenting clearly, but that's not the same thing. I could further update the PR to remove or de-emphasize the HTML comparison, but I'm not sure @awwright would approve of that. Let me see if I can make a separate PR for consideration on that point. The only other thing that I can come up involves making it more clear which HTTP methods are possible. But it's theoretically possible that Conversely, restricting So I'm looking for a problem that my interpretation causes that is similar in magnitude to the maintenance problem I see with your interpretation. Or an explanation for how to avoid the maintenance problem that I see- I may just be missing something. |
Hyper-Schema is supposed to be decoupled from HTTP. So, we have to consider the information an LDO is conveying without it being colored or constrained by HTTP. If we say that the user-agent can ignore If this interpretation is accepted, If
You've brought this up several times in the past, but I still don't understand the problem you are facing. My guess is that this is not a complexity or scale issue, but rather an approach issue. I suspect that you are using Hyper-Schema in a different way than I do and that causes you to encounter this duplication problem. So, I can't explain how to avoid the maintenance problem because I'm still not sure what the problem is. An example might help, but this thread probably isn't the appropriate place for that discussion. |
|
@jdesrosiers thanks for making the effort to come at this from another angle. I feel like we are working through critically important things here which is exciting! I think I am starting to see where you are coming from. I am still skeptical, but it is making more sense.
Let's propose a set of generic rules and see how they would work with a variety of URI schemes. I want to call attention to With that in mind:
Case 4 is somewhat awkward and not entirely consistent, but I have not been able to find anything anywhere that needs it. If we only need to support the first three cases, then there is no need for I said that I am starting to see, if not agree with, your point of view. If we must support case 4, and we collapse case 3 into it, then we get exactly what you propose. An explicit operation taking non-representation-based input ( So I can recognize an asymmetry between cases 3 and 4, and acknowledge that it's not ideal. In that case, I would still want to dump So now let's go through several examples: http:// or https://The HTTP protocol is squarely in case 3, even when including PATCH. The rules above don't mention anything at all about HTTP, but RFCs 7231 (HTTP Semantics) and RFC 5789 (PATCH) describe every request that can meaningfully take a payload in terms of the target representation, except for the request payload for POST. The rules work, there's no coupling. mailto:
and
so The RFC also defines how to map mail headers directly into the URI, which is what HTML does for GET forms. So
In the case of a
This implies that the other thing you can do with Once again, we don't need to couple the URI scheme to the use of data:The Instead, it involves substituting template sequences such as Basically, HTML offers two different ways to encode form data into There's no need for us to replicate HTML's approach to ftp://FTP is weird in that it is stateful (so not usually encountered in hypermedia these days) and encodes operations into its URLs so as to batch up a series of operations into a single stateless-ish interaction. The URI scheme RFC (which despite the "Obsolete" notation is correct for
But it does indicate that this is accomplished through URLs, so All of the data transfer operations are in terms of representations, or have standard response formats that need not be documented in Hyper-Schema, except for the SITE command:
So the SITE command might have some use for So I think this fits within case 3. And in any event, I'll be dumbfounded if anyone is trying to integrate ftp into a hypermedia system. gopher://Gopher just sends stuff in the URL, so
Gopher+ offers the ASK command which retrieves a form definition for submission. I don't even know what to do with that, it sounds like it wouldn't use In all seriousness, I'm including Gopher to show that some URI schemes just aren't going to fit the modern hypermedia paradigm at all. Arguably FTP is in the same category. others?I'm stopping here mostly because I'm getting bored reading RFCs :-) But I think it would be worthwhile if you can think of other URI schemes to see whether they can map without using any information beyond the rules I listed and the existing content of their protocol or URI RFCs. If you can find anything that requires case 4, there may be an argument for taking your approach. But if not, I believe my approach works without coupling and reduces duplication of LDOs (I'll address that in a separate comment). Also, we can add support for case 4 later without breaking the first three rules by saying that if there is only one operation that can possibly use |
|
OK, now for the duplication thing. I should be clear that while I consider this to be really annoying, it is not completely unmanageable, so preventing it is not something I'll be making a do-or-die last stand about. I can live with it if I have to, I just don't see why I should have to. Let's say I have a heavily parametrized URL to run big data analytics queries. And let's say that if I want to generate a persistent report with extra-fancy graphs that doesn't re-run the query every time, without everyone re-running the expensive query, I POST to the same URL to create the report. The POST includes a list of people to email the link to the report to and information on what sort of charts to render. [EDIT: After writing all this up I realized that the So with your approach, I need to do the following: {
"$id": "entry.json",
"links": [
{
"rel": "tag:example.com,2017:analytics",
"href": "analytics{?start,end,fooFilter,barFilter,regex}",
"hrefSchema": {"$ref": "analytics.json#/definitions/reportQuery"},
"targetSchema": {"$ref": "analytics.json"}
},
{
"rel": "tag:example.com,2017:analytics",
"href": "analytics{?start,end,fooFilter,barFilter,regex}",
"hrefSchema": {"$ref": "analytics.json#/definitions/reportQuery"},
"targetSchema": {"$ref": "analytics.json"},
"schema": {"$ref": "analytics.json#/definitions/saveReportData"},
"method": "post"
}
]
}and {
"$id": "analytics.json",
"definitions": {
"reportQuery": {
"type": "object",
"properties": {
"start": {"type": "string", "format": "date"},
"end": {"type": "string", "format": "date"},
"fooFilter": {"type": "number"},
"barFilter": {"type": "boolean"},
"regex": {"type": "string"}
}
},
"saveReportData": {
"type": "object",
"properties": {
"recipients": {
"type": "array",
"items": {"type": "string", "format": "email"}
},
"charts": {"enum": [...]}
}
}
},
"type": "object",
"allOf": [
{
"properties": {
"data": {
"type": "array",
"items": {...}
}
}
},
{"$ref": "#/definitions/query"}
],
"links": [
{
"rel": "self",
"href": "analytics{?start,end,fooFilter,barFilter,regex}",
"hrefSchema": {"$ref": "#/definitions/reportQuery"},
"targetSchema": {"$ref": "#"}
},
{
"rel": "self",
"href": "analytics{?start,end,fooFilter,barFilter,regex}",
"hrefSchema": {"$ref": "#/definitions/reportQuery"},
"targetSchema": {"$ref": "#"},
"schema": {"$ref": "#/definitions/saveReportData"},
"method": "post"
}
]
}So this is kind of annoying. We can I could arguably drop the So now I need this in at least three places, possibly four if I want to allow jumping to the resource from a saved representation and then hitting POST from there (although I don't view that as critically important). There's more that's difficult here than the duplication caused by requiring |
|
Thanks @handrews this example is a good read. I THINK you mentioned you were writing a wiki page to explain how hypermedia should work. You could include this example you've used to show a comparison of how it would (I presume in your eyes incorrectly) work with your example, and then further how you would LIKE to see it work using JSON Schema. Obviously I'll be happy to give feedback on that page when you're happy with it. Otherwise, consider me a bystander on this =] |
|
@jdesrosiers I have added some wording to clarify how I have left the " I am going to post a separate PR showing an example of using |
|
@jdesrosiers @awwright added an example with a |
|
@handrews Wow, that was a fascinating tour of protocols. I laughed when I got to gopher :-). However, even if there doesn't exist a protocol that can't be mapped unambiguously, it doesn't mean there isn't a coupling. The fact that it is necessary to do a complete survey of potential protocols to determine if there is a conflict is evidence of coupling. An LDO should mean the same thing no matter what protocol/method you are using. If the LDO can potentially change it's meaning based on the method that is applied to it, then it is coupled to that protocol even if that coupling doesn't lead to ambiguity. If you can come up with a definition for For example, a bad definition of I haven't been able to come up with something similar for Can you come up with a definition for |
|
@handrews I think your duplication problem (at least in this example) comes from the way it is designed. If I understand your example correctly, you have some overlap in functionality. The GET request crunches some numbers and generates a report. The POST request crunches some numbers, saves that report and sends an email with that report plus some charts. Both operations crunch the same numbers and generate the same report. The duplication in your links is a reflection of the duplication in your API. I would design this as two steps. First you generate a report. This creates a resource that has an HTML representation as well as a JSON representation. You might do this several times tweaking the parameters and reviewing the results. When you are happy with what you have, then you can make an additional analytics-notify request to persist/email the report. The email can be the HTML representation. Any reports that don't have analytics-notify called on them get removed by the server after some period of time. {
"$id": "entry.json",
"links": [
{
"rel": "tag:example.com,2017:analytics",
"href": "analytics",
"method": "post",
"schema": {
"type": "object",
"properties": {
"start": { "type": "string", "format": "date" },
"end": { "type": "string", "format": "date" },
"fooFilter": { "type": "number" },
"barFilter": { "type": "boolean" },
"regex": { "type": "string" }
}
}
}
]
}{
"$id": "analytics.json",
"properties": {
"id": { "type": "string" },
"data": {
"type": "array",
"items": { ... }
}
},
"links": [
{
"rel": "self",
"href": "analytics/{id}"
},
{
"rel": "tag:example.com,2017:analytics-notify",
"href": "analytics/{id}",
"method": "post",
"schema": {
"type": "object",
"properties": {
"recipients": {
"type": "array",
"items": { "type": "string", "format": "email" }
},
"charts": { "enum": [...] }
}
}
}
]
}Personally, I think this is a better design and it doesn't have the duplication problem. Here are some notes on what I changed. No parameterized query analytics schema now has an id Removed Inlined link I've found that Hyper-Schema is not very forgiving of some design decisions (especially SRP violations). However, when I refactor to get around to problem, I am almost always happier with the new solution. I think Hyper-Schema tends to accentuate design flaws making them more obvious than they might otherwise be. |
|
@jdesrosiers I think we are using different definitions of coupling, and I want to come back to that, but I'm going to focus on some other parts of your response first: (NOTE: I'm going to talk about "actions" because method is overloaded- HTTP methods are actions in this sense, but the Hyper-Schema
It does. The LDO's semantics are determined by the link relation type, not the URI scheme or protocol. Protocol actions have their own semantics, whether defined by the protocol or deferred by the protocol to some other authority (as with HTTP POST deferring to the target resource). The combination of the relation-driven link semantics and the protocol-driven action semantics determine the semantics of each operation. I can go into more detail with examples if this is not clear.
Not quite, although my phrasing was rather muddied last time.
The meaning of
No matter what URI scheme or protocol is used, an action either involves representation data, non-representation data, or no data. If it involves any data at all, it uses the appropriate keyword and ignores the inappropriate one. If it does not involve data, it ignores both. There is nothing remotely specific to any URI scheme or protocol in any of this. By definition, all possible actions fall into exactly one of those three mutually exclusive buckets. Some actions involving representation data also involve modifying that data based on something else, but those actions are still in the representation data bucket. An action that accepts non-representation data that may happen to sometimes be a representation is still in the non-representation bucket (I can give an example if needed). So let's take a look at how this plays out. I'm ignoring data encoded into the URI via
I'll leave off gopher ;-) . There are, of course, more FTP commands, but the ones listed are the ones closely related to sending data. The others are mostly state changes or listings that have response data but not request data (e.g. PWD). I'm quite certain that no special rules tying JSON Hyper-Schema to specific URI schemes are needed to determine value in the 2nd column ("uses"). The values in the 3rd and 4th columns are entirely the result of the 2nd column, so the only question is, can we always figure out the right answer for the 2nd column without having to put a table like this into the JSON Hyper-Schema spec? I think the answer is yes, and I challenge you to come up with even a theoretical situation where it does not work. I will put one caveat on that challenge, though: a protocol that defines multiple actions which take different forms of non-representation data is one that isn't handled well in either of our interpretations. I can go into detail if you disagree. The only way I can currently undertstand you objecting to this is if you insist that |
|
[EDIT: I'm being unfairly cranky again, sorry] @jdesrosiers picking apart an example I made up on short notice does not further this discussion. I regret posting that example, and am not going to respond to API design bikeshedding for something I put about 5 minutes of thought into. |
|
@jdesrosiers which is not to say that I necessarily disagree with your refactor, but it's really not the point here. |
|
@handrews Sorry, your right about the example. What I meant to say, but forgot, was that it doesn't seem fair for me tear apart this toy example. But, the point I wanted to make was that problems with Hyper-Schema can often be addressed by making different design choices. Toy examples might not be sufficient for us to understand our differences. So, yes, I agree, this was unhelpful. |
|
@jdesrosiers thanks for acknowledging that, I really appreciate it. I am, and always have been, notoriously bad at coming up with examples, unless I happen to have worked on something recently that fits well. So my reaction is in part self-recrimination over not being able to come up with something better. In truth, I often respond to colleagues' design questions with a suggestion to rework the resource design rather than add a batch process, an awkward and inconsistent PATCH, or whatever other immediate proposal is on the table. So I'm sympathetic to the impulse! |
"method" already documented that "method": "get" does not constrain the LDO to GET. Clarify that "post" also does not constrain the LDO to HTTP POST, and that the LDO can be used with multiple methods. Further clarify atht "schema" SHOULD be ignored if it is not relevant. The "schema" and "targetSchema" keywords are used with relevant HTTP methods regardless of the presence, absence, or value of JSON Hyper-Schema LDO "method". This is consistent with the existing wording of both "schema" and "targetSchema" around the construction of PUT requests. To clarify non-HTTP usage in generic terms, add some wording about request formats being defined in terms of the target representation or not. This should provide more guidance for when "method": "post" and "schema" are relevant, independent of URI scheme.
|
@jdesrosiers I have updated this PR with a few tweaks and posted PR #284 as an alternative that I think captures your intent. The changes made here to #280 were mostly minor wording improvements, except that I also removed the note about Here is the diff between #284 and the current state of this PR: index bbaa0aa..bf844e2 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -885,17 +885,16 @@ GET /foo/
</t>
<t>
Despite being named after HTTP's GET and POST, the presence,
- absence, or value of this keyword does not directly impose any constraints
+ absence, or value of this keyword does not impose any constraints
on either the protocol or method used to interact with the remote resource.
In particular, the same Link Description Object may be used
for multiple protocol methods.
</t>
<t>
- If "method" is "post" then <xref target="schema">"schema"</xref>
- and <xref target="encType">"encType"</xref>, if present,
- MUST be used to construct any request payload. This indirectly
- constrains the available protocol methods to those semantically
- compatible with this restriction.
+ For protocol methods whose request format is derived from
+ the target representation, if "method" is "post" then
+ <xref target="schema">"schema"</xref> and
+ <xref target="encType">"encTYpe"</xref> SHOULD be ignored.
</t>
<t>
Values for this property SHOULD be lowercase, and SHOULD be compared case-insensitive. Use of other values not defined here SHOULD be ignored.@awwright as noted in #284 I think we are pretty close to a point where you will need to make a call. |
|
This thread has a lot of discussion that I've read as it's been coming in but I may forget which points were made in which thread. And my position may have changed since draft-wright-json-schema-hyperschema-00 was published (and it almost certainly has). So bear with me a little here :) To try to summarize, I'd start by observing that link relations mean the same thing regardless of which media type contains the link. The HTTP "targetSchema" and "schema" both describe properties of the target resource:
Note that I guess, technically, there is still a link relationship. Even an HTML So to this end I was a little confused reading the PR (in the sense that "post" does strongly imply using |
|
@awwright thanks for the explanation! There's a lot to consider here. First, just to get it out of the way, I'm pretty sure nothing in this discussion is at all specific to media type. Even the discussion of
When you say this, are you implying that a link with a Or are you just musing over whether a link with I'd go back to your observation:
I'd further argue that the relation type, meaning the value of The canonical example is "collection". While RFC 6573 is (appropriately) neither media type nor protocol specific, both example media types that it references specify using an HTTP POST to the collection to create an item. While that is media type-specific usage, it does not violate the semantics defined by RFC 6573 in any way. So a collection resource, as identified by a link with Basically, I don't think I should have to specify my "collection" link twice, once with |
|
@handrews sorry for the delayed response.
Thanks, this helped me better understand your point of view. The problem I have with this is that it is so generic as to be effectively meaningless. However, I do like @awwright's definition.
I think this conveys the same concept you were trying to get across, but it's more concrete. With this definition I can see how @awwright thanks for all that great insight. I especially like the observation that all of these link attributes should all be informative and describe the target resource. That and your definition of I still think that the inclusion of the |
|
@jdesrosiers no worries, I don't expect us all to be glued to our computers (I kinda was this weekend, but barely paid attention last weekend). It sounds like we are converging on something workable here. I also like @awwright's "describe the domain" definition. Thinking of this sort of link as a function is helpful. You are correct that On the other hand, I'm not sure how much compatibility we really need to be retaining here, so it may be worth reconsidering now that we've all sharpened our mental models through this discussion. It's already a big change from Draft 04's explicit listing of HTTP methods, and it would probably be less confusing to get rid of it entirely than to lower-case the values and restrict them to their HTML form meaning. As far as I can tell, the primary function of Removing If I am understanding you correctly, the only affect of using What is your use case for requiring the use of I am assuming you are not trying to enforce using Would it be possible to solve your use case by defining the link relation type that you would use as only allowing this sort of function call? Per RFC 5988 link relation types can constrain the possible set of operations. Would it be possible to solve your use case through HTTP's |
|
@jdesrosiers I guess my confusion is that as far as I can tell, your main reason for requiring the use of That's fair enough, but it's a highly debatable point. I would argue that the "collection" link relation is, if not compelling evidence to the contrary, at least indicates that a resource that uses both sorts of links is not uncommon. Even if it's not a great idea. I don't think that JSON Hyper-Schema is responsible for enforcing a design philosophy at that level. It's fine for Hyper-Schema to assume conformance to other specifications such as RFC 7231 HTTP Semantics. That does impose constraints on API design, but JSON Hyper-Schema is not really imposting the constraints. It's just not giving you tools to circumvent constraints defined by other standards. So while I feel like we've sorted out a great many things, I'm still confused on this point, and looking for a rationale beyond stylistic preferences for API design. |
That used to be true. Any mention of a default value or default behavior for
I really thought we were so much closer to understanding each other. I'm not proposing anything new or regressive. I know you're not a fan of the idea, but spec is clear that an LDO includes the functionality of a form. In fact
What this question really boils down to is, "why do I want an LDO that behaves more like a form than a link?". The reason is because it has more specific semantics. A form using `"method": "post" is a non-protocol-or-method-specific construct for sending data to an executable resource. Especially if the resource only supports POST, a specific construct than a generic one. Even if the resource supports other methods, I like the organization of defining information resources and executable resources separately. But, that's just my opinion. Honestly, the compromise proposal is a win-win. Everyone gets what they want and the only change that has to be made is to move the definition of I agree that everything about the naming of |
|
@jdesrosiers I just don't understand why you draw such a hard line between a "form" and a "link". A form is just a description of input that can be used with a link. The link is still a link. Having an input description doesn't change the nature of the link. The nature of the link is determined by the link relation, regardless of input description. You read so much into the use of the word "form", but unless you can point me to a MUST somewhere, I do not accept that the draft requires all these things. The right way to make the semantics more specific is to use a more specific link relation.
Which is why I object to writing it into the draft. |
|
@jdesrosiers @awwright @Relequestual At this point I am strongly against releasing a new draft with the While I can see using another keyword to indicate "you MUST use Instead, I think we will get more iterations of this exact confusion and disagreement. Let's publish something clear, and get clear feedback on it instead of spending the next six months explaining |
|
@handrews I really don't know what else to say. I don't understand your resistance to a compromise in which you get everything you want and lose nothing. Is it really so important that I don't get what I want when it costs you nothing? When this started, it was supposed to be a clarification. Both interpretations can be argued based on the current spec so why not go for an clarification that encompasses both interpretations without getting in each other's way? It can be argued whether or not to drop one or the other in the next draft. |
|
We're sort of evolving away from an idea where HTML forms are defining what hypermedia means to us. Which just means we're doing a good job of thinking about how this works, I believe. The definition of link that we're drifting toward is "The method by which third parties learn how to interact with remote resources". In my interpretation, the only reason we have "method" is to be able to know what to do with "schema". The quintessential Web link just has a document (or "anchor" or "source"), an optional relationship ("rel"), and a target ("href"). For this case, we don't need "schema" or "method". While "href" might have some templates, these are provided by the instance. In some cases, we want to tell a user how they can craft their own URI to a particular resource. Maybe they have a search term, or a product ID, and they would like to go to a page of search results, or a page about a product. So we give them a URI template with some unbound variables. In other cases, we want to tell a user how they can submit a document to a remote resource for processing. We tell them the server is expecting some fields, and the URL to submit it to. Is there any reason we shouldn't be able to do both at the same time? Forgive me if this idea has already been shot down, I think I proposed this before. But I think "schema" is too generic a keyword name to use, and we should allow the two variants to be used at the same time, and we give them more descriptive names: "submissionSchema" ("indicates the domain of what the resource can process") and "hrefSchema"/"hrefVariables" ("specifies what kind of user-provided data will be used in the construction of a URI"). So, given that "method" doesn't really mean anything besides "what do we do with |
|
@jdesrosiers I think I actually just missed that there was a compromise proposal in there. I'm certainly not trying to deny you a benefit here! Is the compromise dropping Before addressing that let me respond to @awwright:
Yes! Despite HTML's success, it shows its age in some weird quirks (and I think forms are one of them, despite still working fine for what they do). More importantly, human-oriented hypermedia and machine-oriented hypermedia really aren't the same, and the human factors that make HTML so usable as it is are absent here.
Nope. Splitting the two is exactly what I've been getting at for months with #108, but I just wasn't able to convey it clearly. I think I was still too muddled on a number of concepts. I would very much be on board with
But why would we keep @jdesrosiers this is not trying to prevent you from anything, I just still don't get it. But if you and @awwright come to an agreement that's along the lines of either of the above proposals, I will support it. I just really do not want a repeat of the last draft where all the feedback we got was |
Yes, that's it. Although, removing If As for renaming |
|
@jdesrosiers Originally I just wanted to clarify this, but I do not think it is possible to publish a clear specification if Allowing leaving it out and not restricting the behavior in such a case will work well for me, but it's arguably even more confusing for people without the backstory. On the other hand, I disagree so strongly about forms being different from links, or really anything other than an input description that is attached to a link without changing any aspect of the underlying link, that I doubt we could settle on any alternate approach. I just feel that the overall direction of hypermedia is that links are links, and mechanisms for input, outside of weird old HTML, are just that: descriptions of possible input, where the decision of how to use the input is deferred to the link relation, target resource, and protocol, and NOT the context media type. So I guess we're doomed to spend six months explaining |
|
So, to summarize:
|
|
@jdesrosiers @awwright I am writing up a PR that captures the above compromise approach, keeping And of course if we figure out a way to remove |
|
One final appeal: Our biggest problem with getting useful feedback on JSON Hyper-Schema is people thinking that it is an API description framework like OpenAPI/Swagger, RAML, Hydra, etc.
If we remove method, then it is absolutely clear that we are not and do not intend to be a static description framework. This is, to me, by far the most valuable thing we could possibly do with draft-wright-json-schema-hyperschema-01: Force people to provide feedback on what Hyper-Schema actually is, and not what they misunderstand it to be. Arguing with people over why they can't say |
|
Henry Andrews wrote:
One final appeal:
Our biggest problem with getting useful feedback on JSON Hyper-Schema is
people thinking that it is an API description framework like
OpenAPI/Swagger, RAML, Hydra, etc.
|"method"| is the single keyword that makes people think that, because
it *looks* like the operation descriptions keyed by HTTP method that are
common to all such systems.
If we remove method, then it is absolutely clear that *we are not and do
not intend to be* a static description framework. This is, to me, by far
the most valuable thing we could possibly do with
draft-wright-json-schema-hyperschema-01: Force people to provide
feedback on *what Hyper-Schema actually is*, and not what they
misunderstand it to be.
Arguing with people over why they can't say |"method": "put"| does not
advance our cause at all. We won't make real progress on Hyper-Schema
until we can get past that.
Previously I was one of those "people" but, thanks to various recent
discussions on this topic, I think I now understand that. So, from my
perspective, there have been some progress.
Thus I agree with you on the removal of "method".
|
|
@dlax Previously I was one of those people, too! If you dig around you can find where @awwright had to keep pushing back on ideas I kept putting forward along those lines until I caught up :-P I think it's an extremely natural reaction. API description formats are the dominant paradigm,so they're the default assumption. The only way to break out of that is to make it impossible to even write a hyper-schema that looks like that. |
|
@dlax @jdesrosiers @Relequestual @awwright @Anthropic I still need to write the "how to figure out your link's semantics, and the semantics of its operations" part. But I think the first half is probably of interest as is. https://github.com/json-schema-org/json-schema-spec/wiki/Hypermedia-and-APIs |
|
@handrews @awwright I'm in favor of giving Once again, I have no love for the
It doesn't. Hacks you can do with JavaScript are irrelevant in this context because Hyper Schema doesn't support any way to execute JavaScript. |
|
OK, sounds great! I'll write up something with Unless you prefer an alternate approach, I am going to describe Separately... I am yielding the point on all the stuff below for the about to be published draft, but I wasn't expecting your response to go in that direction and feel the need to address it. I know you're at least a little puzzled by my vehemence on this point, and hopefully this will put a little more context on it. Understanding your view on this point made some things click a bit more for me.
If we take anything from human-oriented hypermedia, it should be from how it actually works now, not how one piece that is no longer viewed as sufficient on its own by any non-trivial project was defined to work decades ago. |
|
Henry Andrews wrote:
here is the first half of my "API and Hyper-Media" article, which covers
the distinctions between hypermedia and API description formats.
I still need to write the "how to figure out your link's semantics, and
the semantics of its operations" part. But I think the first half is
probably of interest as is.
https://github.com/json-schema-org/json-schema-spec/wiki/Hypermedia-and-APIs
Thanks for that!
The last link on the page "RFC 7231: HTTP Semantics" has wrong target
(should be https://tools.ietf.org/html/rfc7231 not
https://tools.ietf.org/html/rfc6570).
|
This actually probably hits on a lot of the different opinions here. HTML was going to, for a while, allow This usage of So let me re-review the kind of links we support:
|
|
@awwright thanks for that overview! It helped me write the reworked "Links, operations, and data" section in PR #290. Hopefully I captured things accurately. @jdesrosiers I believe that #289 + #290 implements your proposed compromise. Hopefully it is presented in a philosophically coherent way. Please let me know if all of the stuff about "form" is coming across as you want. |
|
Closing this in favor of #292, 293, and a future PR for |
PLEASE do not use this PR to debate changes that have already been made and published.
I am aware that changes made to
"method"in draft-wright-json-schema-hyperschema-00 are still controversial. This is not the forum to debate those changes. Try #96 for that. This PR is just attempting clarify the existing intent so that we can get more valuable feedback for draft-wright-json-schema-hyperschema-01 a.k.a. Draft 06.@awwright if this wording does not clarify your intent I'd be more than happy to approve a PR from you with wording that does. Or edit this one. I am not trying to advocate for a particular interpretation in this PR.
"method" already documented that "method": "get" does not constrain
the LDO to GET. Clarify that "post" also does not constrain the
LDO to HTTP POST, and that the LDO can be used with multiple methods.
The "schema" and "targetSchema" keywords are used with relevant
HTTP methods regardless of the presence, absence, or value of
JSON Hyper-Schema LDO "method". This is consistent with the
existing wording of both "schema" and "targetSchema" around the
construction of PUT requests.
See also #277.