Minor comments on the primer

[larsgsvensson]

2.2 Basic Terminology

The text reads "all arcs in or out". I propose to change this to "all incoming or outgoing arcs"

3 ShEx Essentials

Text reads "in which an Issue which is submitted". That ought to be "in which an Issue is submitted" otherwise there's something missing in the sentence. In the image of the graph the assignee is missing. Is that on purpose?

3.1 Node constraints

The definition of value set shows an example where the set consists of two IRIs. It would be helpful to add text or an example that shows how this works with literals and/or numbers. E. g. ´´´my:IssueShape { ex:numberOfVerifications [ 1 3 5 ] }´´´ (saying that the issue must be verified 1, 3 or five times; stupid example but you get the gist...).

3.4 Combining Value Constraints

I don't quite understand this example. The result shape map references inst:User1 and inst:User3 but none of those appear in the passing/failing data. Are those instances the same as http://hr.example/id#123 and http://hr.example/id#abc ?

3.7 Value Sets

In the example you use inverse constraints (´´´^ex:hasIssue´´´) but don't introduce those until later in the document which is confusing for the reader. It would be better to say that the example uses an inverse constraint and make a reference to 4.1. The Result Shape Map says that ´´´inst:Issue3´´´ fails against ´´´my:IssueShape``` because ´´´my:Product3´´´ is not in range of ´´´ex:hasIssue´´´. In my view that is not correct. ´´´my:Product3´´´ is not in the domain of ´´´ex:hasIssue´´´ or not not in range of ´´´^ex:hasIssue´´´ (the inverse constraint).

4.1 Inverse Triple Constraints

Is there a reason that the data is not split into passing and failing data? inst:User2 is failing data.

4.6 Repeated Properties

In this section the usual Result Shape Map is missing.

Best,

Lars

[jimkont]

Thank you for your extensive feedback on the primer @larsgsvensson We will try to incorporate your comments in the spec

[tombaker]

Hi Lars,

Your detailed comments are much appreciated! I am swamped this week with two major deadlines for next week (and DC-2017) but look forward to fixing these immediately thereafter.

Many thanks, Tom

On Thu, Oct 12, 2017 at 08:05:37AM +0000, Lars G. Svensson wrote:

2.2 Basic Terminology

The text reads "all arcs in or out". I propose to change this to "all incoming or outgoing arcs"

3 ShEx Essentials

Text reads "in which an Issue which is submitted". That ought to be "in which an Issue is submitted" otherwise there's something missing in the sentence. In the image of the graph the assignee is missing. Is that on purpose?

3.1 Node constraints

The definition of value set shows an example where the set consists of two IRIs. It would be helpful to add text or an example that shows how this works with literals and/or numbers. E. g. ´´´my:IssueShape { ex:numberOfVerifications [ 1 3 5 ] }´´´ (saying that the issue must be verified 1, 3 or five times; stupid example but you get the gist...).

3.4 Combining Value Constraints

I don't quite understand this example. The result shape map references inst:User1 and inst:User3 but none of those appear in the passing/failing data. Are those instances the same as http://hr.example/id#123 and http://hr.example/id#abc ?

3.7 Value Sets

In the example you use inverse constraints (´´´^ex:hasIssue´´´) but don't introduce those until later in the document which is confusing for the reader. It would be better to say that the example uses an inverse constraint and make a reference to 4.1. The Result Shape Map says that ´´´inst:Issue3´´´ fails against ´´´my:IssueShape``` because ´´´my:Product3´´´ is not in range of ´´´ex:hasIssue´´´. In my view that is not correct. ´´´my:Product3´´´ is not in the domain of ´´´ex:hasIssue´´´ or not not in range of ´´´^ex:hasIssue´´´ (the inverse constraint).

4.1 Inverse Triple Constraints

Is there a reason that the data is not split into passing and failing data? inst:User2 is failing data.

4.6 Repeated Properties

In this section the usual Result Shape Map is missing.

Best,

Lars

-- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: https://github.com/shexSpec/primer/issues/10

-- Tom Baker tom@tombaker.org

[tombaker]

Hi Lars,

We have accepted most all of your changes (thank you!) [1,2]

We thought of two more good examples to illustrate different types of Value Set: 1) URI (ex:unassigned), 2) literal ("unassigned") 3) integer (0).

We have two remaining issues [3,4]. For example, you wondered why the passing and failing data were not presented in sequence, as they usually are, and Eric feels that simply adding a "try it" button to the data in 4.1 could usefully present a block of data that both passes and fails.

We both have other deadlines to meet and simply ran out of time for now but will return to complete these.

Tom

[1] https://github.com/shexSpec/primer/compare/41122f4...ecd904b?diff=split&name=ecd904b [2] https://github.com/shexSpec/primer/pull/11/files [3] https://github.com/shexSpec/primer/pull/11#discussion_r154493324 [4] https://github.com/shexSpec/primer/pull/11#discussion_r154493484

-- Tom Baker tom@tombaker.org

[larsgsvensson]

Thanks for considering my suggestions. Absolutely no need to hurry for my sake. If there's anything more I can do, just ping me.