Rework the descriptions of using data with links #293

handrews · 2017-03-31T19:22:56Z

IGNORE the first commit, it is from PR #292

Review this commit here: af5ef3a

This replaces the rather lengthy discussion of hrefSchema
with a more concise and complete description of all of the
ways to use data with links. This should now serve to set
the context for the various ways to use LDOs.

jdesrosiers · 2017-04-01T01:44:24Z

jsonschema-hyperschema.xml

+                        In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
+                        supplies a non-authoritative description of the target resource's representation.
+                        A client can use "targetSchema" to structure input for replacing or
+                        modifying the representation.  Alternatively, if "targetScheam" is absent


typo: "targetScheam" => "targetSchema"

jdesrosiers · 2017-04-01T01:47:19Z

jsonschema-hyperschema.xml

                <t>
-                    The following properties also apply to Link Description Objects, and provide functionality analogous to <xref target="W3C.CR-html5-20140731">HTML forms</xref>, by providing a means for making a request with client- or user-selected information.
+                    If present, this property indicates the media type format the
+                    client should use to for the request payload described by


handrews · 2017-04-01T21:41:38Z

@jdesrosiers thanks for catching those! Should be fixed now.

handrews · 2017-04-03T18:29:08Z

@awwright this and #292 are awaiting your approval, at which point I think we are good to go with draft-wright-json-schema*-01

handrews · 2017-04-04T18:06:14Z

@awwright this PR now only has the one commit- I've rebased it on top of the merged #292 and #296. Should be more clear to review now.

awwright · 2017-04-04T18:15:58Z

@handrews Thanks, you read my mind

This replaces the rather lengthy discussion of hrefSchema with a more concise and complete description of all of the ways to use data with links. This should now serve to set the context for the various ways to use LDOs.

awwright · 2017-04-07T21:13:33Z

jsonschema-hyperschema.xml

+                    should be inferred primarily from link <xref target="rel">relation types</xref>
+                    and URI schemes.  Note, however, that a resource may always decline an operation at
+                    runtime, for instance due to application state that controls the operation's
+                    availability.


It seems like we're comparing the LDO against something (HTML forms?), but there's no indication of what that is.

I would move this paragraph down one so we lead with what it does, not with what it doesn't do.

Good point, fixed.

awwright · 2017-04-07T21:36:35Z

jsonschema-hyperschema.xml

+                    There are several ways that a client can use data can with a link:
+                    <list>
+                        <t> URI Template variables resolved from server-supplied instance data </t>
+                        <t> URI Template variables resolved from client data </t>


These two lines might be too easy to conflate. I would say something like

Plain links, where all variables in the URI Template (if any) are filled from instance data

Link templates, where the URI Template contains variables that can be filled in by a users or agent

Your phrasing is not clear to me, and I don't have any intuition for "Plain links" vs "Link templates", especially because your plain links obviously involve template variables.

The distinction is not across the template, it's that there are different ways to use template variables, which might appear in any combination in a template.

Oh I see. I suppose that works.

What about "URI Template variables resolved from user input"?

What about "URI Template variables resolved from user input"?

This is a good point: I've avoided "user input" in favor of "client data" because of situations (like autonomous Things in the Internet of Things sense) where there is no direct user input, but there is data coming through the client from somewhere.

So I don't want to make it sound like there has to be an actual user interaction involved, but I do want the purpose to be clear.

client input? user-agent input?

awwright · 2017-04-08T06:18:34Z

Yeah I see exactly what you mean... I figure most people know a "user" can be automated. Technically, it's always an agent making the request and filling in the variables, how about "agent"? Iirc that's how HTML deals with it.

…

On Apr 7, 2017 11:07 PM, "Henry Andrews" ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In jsonschema-hyperschema.xml <#293 (comment)> : > </t> <t> - See the individual keyword descriptions below for details related to each of these cases. + There are several ways that a client can use data can with a link: + <list> + <t> URI Template variables resolved from server-supplied instance data </t> + <t> URI Template variables resolved from client data </t> What about "URI Template variables resolved from user input"? This is a good point: I've avoided "user input" in favor of "client data" because of situations (like autonomous Things in the Internet of Things sense) where there is no direct user input, but there is data coming through the client from somewhere. So I don't want to make it sound like there has to be an actual user interaction involved, but I do want the purpose to be clear. client input? user-agent input? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#293 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAatDRLuRWHhwHxEX5wGMibyTk264mq7ks5rtyQKgaJpZM4MwDxy> .

handrews · 2017-04-08T06:43:00Z

@awwright "agent" works for me, and as you note there is precedent. I'll look through the spec and try to make sure the language is consistent as I know I have "client data" in some places, and "external data" in others. And probably still "user input" somewhere.

I'll update the PR tomorrow.

Instead of "user input", "client data", and "external data".

handrews · 2017-04-08T22:12:42Z

@awwright the latest commit changes everything to "user agent data". I looked through the HTML5 spec and RFC 7231 and both consistently user "user agent" (never "agent" on its own). So that seems the safest option.

Previously, I'd used several different phrases all over the place, so I went ahead and cleaned it all up. If you want look at this part on its own the commit diff is:

6bf4061

awwright

Even better! Yeah, "user agent" is the right call here it seems

handrews · 2017-04-09T03:17:34Z

@awwright Yay! This was the last PR (aside from the meta-schema URI which I assume you'll either merge when you do the release or do it on your own, I don't care which).

I think you are clear to publish draft-wright-json-schema-*-01!

This was referenced Mar 31, 2017

Remove "method", add "form" #290

Closed

Add cref describing the situation with HTML forms #281

Closed

form semantics #294

Closed

jdesrosiers reviewed Apr 1, 2017

View reviewed changes

jdesrosiers approved these changes Apr 1, 2017

View reviewed changes

handrews mentioned this pull request Apr 1, 2017

Remove "method" and analogies to HTML forms. #292

Merged

handrews force-pushed the operations branch from af5ef3a to 22389d4 Compare April 1, 2017 21:41

jdesrosiers approved these changes Apr 1, 2017

View reviewed changes

handrews requested a review from awwright April 3, 2017 18:15

handrews added Priority: Critical Status: Review Needed labels Apr 3, 2017

handrews force-pushed the operations branch from 22389d4 to 92a9541 Compare April 4, 2017 18:05

handrews added this to the draft-next (draft-6) milestone Apr 5, 2017

Rework the descriptions of using data with links.

95507e9

This replaces the rather lengthy discussion of hrefSchema with a more concise and complete description of all of the ways to use data with links. This should now serve to set the context for the various ways to use LDOs.

handrews force-pushed the operations branch from 92a9541 to 95507e9 Compare April 6, 2017 18:43

awwright reviewed Apr 7, 2017

View reviewed changes

Switch order based on feedback.

323611b

Standardize on "user agent data"

6bf4061

Instead of "user input", "client data", and "external data".

awwright approved these changes Apr 9, 2017

View reviewed changes

handrews merged commit 1f9fd20 into json-schema-org:master Apr 9, 2017

handrews removed the Priority: Critical label Apr 9, 2017

handrews deleted the operations branch April 9, 2017 07:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework the descriptions of using data with links #293

Rework the descriptions of using data with links #293

handrews commented Mar 31, 2017 •

edited

Loading

jdesrosiers Apr 1, 2017

jdesrosiers Apr 1, 2017

handrews commented Apr 1, 2017

handrews commented Apr 3, 2017

handrews commented Apr 4, 2017

awwright commented Apr 4, 2017

awwright Apr 7, 2017

handrews Apr 7, 2017

awwright Apr 7, 2017 •

edited

Loading

handrews Apr 7, 2017 •

edited

Loading

awwright Apr 8, 2017

handrews Apr 8, 2017

awwright commented Apr 8, 2017 via email

handrews commented Apr 8, 2017

handrews commented Apr 8, 2017

awwright left a comment

handrews commented Apr 9, 2017

Rework the descriptions of using data with links #293

Rework the descriptions of using data with links #293

Conversation

handrews commented Mar 31, 2017 • edited Loading

jdesrosiers Apr 1, 2017

Choose a reason for hiding this comment

jdesrosiers Apr 1, 2017

Choose a reason for hiding this comment

handrews commented Apr 1, 2017

handrews commented Apr 3, 2017

handrews commented Apr 4, 2017

awwright commented Apr 4, 2017

awwright Apr 7, 2017

Choose a reason for hiding this comment

handrews Apr 7, 2017

Choose a reason for hiding this comment

awwright Apr 7, 2017 • edited Loading

Choose a reason for hiding this comment

handrews Apr 7, 2017 • edited Loading

Choose a reason for hiding this comment

awwright Apr 8, 2017

Choose a reason for hiding this comment

handrews Apr 8, 2017

Choose a reason for hiding this comment

awwright commented Apr 8, 2017 via email

handrews commented Apr 8, 2017

handrews commented Apr 8, 2017

awwright left a comment

Choose a reason for hiding this comment

handrews commented Apr 9, 2017

handrews commented Mar 31, 2017 •

edited

Loading

awwright Apr 7, 2017 •

edited

Loading

handrews Apr 7, 2017 •

edited

Loading