URI Template resolution as pseudocode #425

handrews · 2017-09-25T07:58:20Z

NOTE: This is a chunk of work that I have done as part of the rewrite. This probably isn't quite the right way to specify it, but seems like the best way to get some feedback on the approach and changes before putting a lot of work into new prose. Please assume that perfect examples are present wherever you want them to be :-) I have not yet consolidated the examples into a more focused set so they're not included in this PR.

This is one of the two most complex things an implementation must do in order to implement hyper-schema (the other thing being finding all applicable schemas per #424).

This consolidates all of the URI Template resolution sections into
one section. The new section is at the top level, as it applies
to both LDO keywords ("href", "anchor", and all of the algorithm
modifiers) and to a schema keyword ("base").

As much of the algorithm as possible is now given in pseudocode,
although whether this is the most readable form is debatable.
It is certainly more concise, and forced detailed consideration
of some steps which had been under-specified, particularly with
respect to "hrefSchema".

The main changes are that setting any applicable subschema for
a template variable to "false" in "hrefSchema" excludes that
variable from accepting input, and that the input data for
"hrefSchema" is prepopulated only with instance data that
validates against all applicable subschemas within "hrefSchema".
Expressing this properly requires the "applicability" concept
from PR #424.

Previously, the only mention of how to exclude a field from being
used to pre-populate input was the advice to set the "properties"
subschema to "false". However, this does not hold up once you
start using more complex schemas.

This consolidates all of the URI Template resolution sections into one section. The new section is at the top level, as it applies to both LDO keywords ("href", "anchor", and all of the algorithm modifiers) and to a schema keyword ("base"). As much of the algorithm as possible is now given in pseudocode, although whether this is the most readable form is debatable. It is certainly more concise, and forced detailed consideration of some steps which had been under-specified, particularly with respect to "hrefSchema". The main changes are that setting any applicable subschema for a template variable to "false" in "hrefSchema" excludes that variable from accepting input, and that the input data for "hrefSchema" is prepopulated only with instance data that validates against all applicable subschemas within "hrefSchema". Expressing this properly requires the "applicability" concept from PR json-schema-org#424. Previously, the only mention of how to exclude a field from being used to pre-populate input was the advice to set the "properties" subschema to "false". However, this does not hold up once you start using more complex schemas.

handrews · 2017-09-25T20:20:46Z

An alternative approach here would be to say that an implementation MUST provide the from-instance template data set to callers alongside of hrefSchema, and let the caller decide whether and how to pre-populate the input form.

If we went that route, I would still like to include this pre-population approach as an option that an implementation SHOULD support directly as a convenience, as I think it will be the most common and interoperable approach. But I could see requiring a more flexible option alongside of it.

dlax · 2017-09-28T07:24:03Z

While I've been reading the algorithms a couple of times, I'm still having hard time following... So it's hard for me to figure out the scope of the changes of this PR and make an opinion.

One issue with the "pseudocode" form is that it's part of a normative section of the spec (as opposed to in an appendix for example), so it can hardly be skipped. I have the impression that such extensive use of pseudo-code in a normative section is not an usual practice. I can't really tell how this would look like in another form: certainly be more verbose, but maybe easier to follow?

For instance, would something like the Implementation Hints in RFC6570 work here?

handrews · 2017-09-28T07:37:00Z

@dlax it's mostly that I needed to write the pseudocode in order to work out the steps that needed to be done for it to actually work.

I'm not at all attached to it as the form of explanation. I just posted this for feedback on the direction.

handrews · 2017-09-28T22:23:50Z

@dlax I added some English descriptions of the various steps, see if that makes it easier to comprehend. I added the same commit to the main rewrite PR as well.

dlax · 2017-09-29T12:59:38Z

As reading the rewrite PR, I haven't seen any obvious problem with this approach of presenting the URI template resolution consolidated into a dedicated section.

dlax

I've been rereading this as part of #427 so here is some more questions. (Commenting here instead of in the other PR as it seems more appropriate to me.)

Since nobody has a better idea than the pseudocode approach, maybe we should stick to it and move forward.

dlax · 2017-10-08T09:07:21Z

jsonschema-hyperschema.xml

+<![CDATA[
+templateData = populateDataFromInstance(T, ldo, instance)
+
+if resolving "href" or "base" for "href" and ldo.hrefSchema exists:


I don't understand this line. Perhaps resolving needs to be explain or expressed as a function? Then it's not clear how things come together, perhaps adding some parentheses would help.

dlax · 2017-10-08T09:34:24Z

jsonschema-hyperschema.xml

+                            template resolution data set
+                        </t>
+                    </list>
+                </t>


This paragraph (the whole <t>) does not look correct to me, or I'm not understanding it. It seems to me that it does not match with the pseudocode below. Specifically, I don't get the "Look in the immediate instance for remaining values".
Also I wouldn't say that "various data sources in the instance" are used (or, again, I may be missing what you mean by "various data sources"); to me the instance is just one source.

handrews · 2017-10-09T03:00:29Z

@dlax I've reworked some wording based on your feedback, please take a look and see if that's more clear.

dlax · 2017-10-09T07:05:34Z

@handrews It's more clear, thanks.

dlax

LGTM overall.
Just spotted a couple of typos and suggesting minor improvements.

dlax · 2017-10-09T07:12:21Z

jsonschema-hyperschema.xml

+                <preamble>
+                    This is the high-level algorithm as pseudocode.  "T" comes from either
+                    "href" or "anchor" within the LDO, or from "base" in a containing schema.
+                    Pseudocode for each step follows.  "anchorOrHref" indicates which of the


I'd suggest something like templateKind instead of anchorOrHref.

dlax · 2017-10-09T07:13:10Z

jsonschema-hyperschema.xml

+                All three keywords share the same algorithm for resolving variables from
+                instance data, which makes use of the "templatePointers" and "templateRequired"
+                keywords.  When resolving "href", both it and any "base" templates
+                needed for resolution to an absolute URI, the algorithm is modfied to


typo: modfied

dlax · 2017-10-09T07:17:40Z

jsonschema-hyperschema.xml

+                            appears in that keyword's value
+                        </t>
+                        <t>
+                            Otherwise, look for a property names matching the variable in


typo: names -> name

dlax · 2017-10-09T07:20:38Z

jsonschema-hyperschema.xml

+                    <preamble>
+                        "InputForm" represents whatevers sort of input mechanism is appropriate.
+                        This may be a literal web form, or may be a more programmatic construct
+                        such as a callback funciton accepting specific fields and data types,


typo: funciton

dlax · 2017-10-09T07:22:40Z

jsonschema-hyperschema.xml

+                </figure>
+            </section>
+
+            <section title="Accepting input for template data">


Might be worth mentioning that this step corresponds to the acceptInput call in this code block above.

Really? I have to say that "Accepting input" == "acceptInput"? Even when it's in the right order and it's the same words already? Let me think on if there is a better way to present this if it's that confusing as is.

It's certainly not confusing now that you mention it. Perhaps I just read it without enough concentration... Let's leave this comment out for the moment.

Define the condition for using hrefSchema more clearly (I hope). Use consistent language around "locations" in a schema rather than introduce a new term "data sources" which is not defined. Attempt a better explanation of how to find values in the instance. I'm not entirely sure it's successful but at least it's different.

URI Template resolution as pseudocode

handrews added hypermedia Priority: High labels Sep 25, 2017

handrews added this to the draft-07 (wright-*-02) milestone Sep 25, 2017

handrews requested review from philsturgeon, awwright and dlax September 25, 2017 07:58

handrews mentioned this pull request Sep 25, 2017

Rename some href* keywords to template* #420

Merged

Make hrefSchema condition more clear.

6980d49

Add more English descriptions

29afd33

dlax reviewed Oct 8, 2017

View reviewed changes

dlax approved these changes Oct 9, 2017

View reviewed changes

handrews added 2 commits October 9, 2017 11:51

Fix more typos, better variable name.

455cbf8

handrews force-pushed the algo2 branch from a5e10ee to 455cbf8 Compare October 9, 2017 18:57

handrews merged commit 0034a48 into json-schema-org:template-not-href Oct 16, 2017

handrews deleted the algo2 branch October 16, 2017 18:28

handrews restored the algo2 branch October 16, 2017 18:36

handrews added a commit to handrews/json-schema-spec that referenced this pull request Oct 16, 2017

Merge pull request json-schema-org#425 from handrews/algo2

52f3380

URI Template resolution as pseudocode

gregsdennis added clarification Items that need to be clarified in the specification and removed Type: Maintenance labels Jul 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

URI Template resolution as pseudocode #425

URI Template resolution as pseudocode #425

handrews commented Sep 25, 2017

handrews commented Sep 25, 2017

dlax commented Sep 28, 2017

handrews commented Sep 28, 2017

handrews commented Sep 28, 2017

dlax commented Sep 29, 2017

dlax left a comment

dlax Oct 8, 2017

dlax Oct 8, 2017

handrews commented Oct 9, 2017

dlax commented Oct 9, 2017

dlax left a comment

dlax Oct 9, 2017

dlax Oct 9, 2017

dlax Oct 9, 2017

dlax Oct 9, 2017

dlax Oct 9, 2017

handrews Oct 9, 2017

dlax Oct 9, 2017

URI Template resolution as pseudocode #425

URI Template resolution as pseudocode #425

Conversation

handrews commented Sep 25, 2017

handrews commented Sep 25, 2017

dlax commented Sep 28, 2017

handrews commented Sep 28, 2017

handrews commented Sep 28, 2017

dlax commented Sep 29, 2017

dlax left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

handrews commented Oct 9, 2017

dlax commented Oct 9, 2017

dlax left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment