Refactor Ordered Collections. Fixes #112. #495

daliadahleh · 2021-06-24T16:55:14Z

No description provided.

uscholdm

A small fix and a couple of suggestions.

gistCore.ttl

gistDeprecated.ttl

…gist:isProxyFor.

rjyounes

I'm happy to discuss any of the proposed changes if you would like to.

docs/ReleaseNotes.md

gistCore.ttl

rjyounes · 2021-06-25T18:38:02Z

gistCore.ttl

+		a owl:Restriction ;
+		owl:onProperty gist:hasOrderedMember ;
+		owl:someValuesFrom gist:OrderedMember ;
+	] ;


The distinctionary pattern is written like this:

gist:OrderedCollection a owl:Class ; owl:equivalentClass [ owl:intersectionOf ( gist:Collection [ a owl:Restriction ; owl:onProperty gist:hasOrderedMember ; owl:someValuesFrom gist:OrderedMember ; ] ); ] ; skos:definition "A collection where the members are in a fixed sequence."^^xsd:string ; skos:prefLabel "Ordered Collection"^^xsd:string ;

This expresses more clearly the idea that "An X is a type of Y that Z."

You also need an allValuesFrom restriction, so the full definition is:

gist:OrderedCollection a owl:Class ; owl:equivalentClass [ owl:intersectionOf ( gist:Collection [ a owl:Restriction ; owl:onProperty gist:hasOrderedMember ; owl:someValuesFrom gist:OrderedMember ; ] [ a owl:Restriction ; owl:onProperty gist:hasOrderedMember ; owl:allValuesFrom gist:OrderedMember ; ] ); ] ; skos:definition "A collection where the members are in a fixed sequence."^^xsd:string ; skos:prefLabel "Ordered Collection"^^xsd:string ;

@rjyounes @daliadahleh Should we not remove the someValuesFrom? The allValueFrom enforces the object type on the property, and removing someValuesFrom allows for an empty collection.

@uschold and I discussed the possibility of empty sets and opened a new issue to raise the question: #498. In theory I'm in favor of allowing empty collections, but we noted that if we allow empty collections, then the restriction must also be removed from Collection (gist:hasMember some owl:Thing), which leaves it as a class without a formal definition.

rjyounes · 2021-06-25T18:46:15Z

gistCore.ttl

 	] ;
-	skos:definition "A member of an Ordinal Collection.  It necessarily precedes or is preceded by another Ordinal Member in the same collection. (This last condition cannot be formally stated in OWL)."^^xsd:string ;
-	skos:prefLabel "Ordinal Member"^^xsd:string ;
+	skos:definition "A member of an Ordered Collection. It either precedes or is preceded by another Ordered Member in the same collection, or it has a stated integer position in the collection."^^xsd:string ;


Omit "stated." This implies a violation of the Open World Assumption.

In actual fact I would remove the entire sentence. The definition doesn't need to restate the restrictions, especially in this case, where the restrictions are not even the most salient part of the semantics. I would use something like this:

skos:definition "A member of an ordered collection. This resource serves as a proxy linking a real-world item in the collection to that collection, allowing the expression of positional and other information that applies to the item only in the context of the collection."

If you really want to keep your definition, then I would add the second sentence as a scope note.

I'm not entirely thrilled with the "real-world" term. Feel free to find something better.

I would use 'linking a member of a collection to that collection' to bypass the 'real-world item' awkwardness.

@sa-bpelakh that seems confusing because the class name (and the first sentence of the definition) suggests that the proxy is the 'member', while your definition suggests that the real-world item is the 'member'. I think 'real-world item' is clearer.

gistCore.ttl

gistDeprecated.ttl

rjyounes · 2021-06-25T20:00:32Z

@daliadahleh: @uscholdm and I have been discussing the domain/range issue and we disagree. We think this should be brought to the group before the PR is merged. I will put it on the top of the agenda for the next meeting.

In a nutshell:

@uscholdm argues that properties should be left as open as possible to being used in other contexts.
@rjyounes argues that, while this is true generally, in this case we have a sub-model in which the pieces fit together to form a whole. If someone wants to use hasOrderedMember, for example, why wouldn't they adopt the entire sub-model?

sa-bpelakh

Just a few minor things, @uscholdm and @rjyounes got most of it.

sa-bpelakh · 2021-06-28T00:20:11Z

gistCore.ttl

+		a owl:Restriction ;
+		owl:onProperty gist:hasOrderedMember ;
+		owl:someValuesFrom gist:OrderedMember ;
+	] ;


@rjyounes @daliadahleh Should we not remove the someValuesFrom? The allValueFrom enforces the object type on the property, and removing someValuesFrom allows for an empty collection.

sa-bpelakh · 2021-06-28T00:22:35Z

gistCore.ttl

 	] ;
-	skos:definition "A member of an Ordinal Collection.  It necessarily precedes or is preceded by another Ordinal Member in the same collection. (This last condition cannot be formally stated in OWL)."^^xsd:string ;
-	skos:prefLabel "Ordinal Member"^^xsd:string ;
+	skos:definition "A member of an Ordered Collection. It either precedes or is preceded by another Ordered Member in the same collection, or it has a stated integer position in the collection."^^xsd:string ;


I would use 'linking a member of a collection to that collection' to bypass the 'real-world item' awkwardness.

gistCore.ttl

…rdered collection properties.

rjyounes

Fix one typo and consider another change to the someValuesFrom restriction.

gistCore.ttl

sa-bpelakh

Looks good, thanks for steering this barge into the port 👏

uscholdm · 2021-07-02T23:36:17Z

gistCore.ttl

 	] ;
-	skos:definition "A member of an Ordinal Collection.  It necessarily precedes or is preceded by another Ordinal Member in the same collection. (This last condition cannot be formally stated in OWL)."^^xsd:string ;
-	skos:prefLabel "Ordinal Member"^^xsd:string ;
+	skos:definition "A member of an ordered collection. This resource serves as a proxy linking a real-world item in the collection to that collection, allowing the expression of positional and other information that applies to the item only in the context of the collection."^^xsd:string ;


linking a real-world item in the collection to that collection,

Confusing wording, it does not seem to be saying what we want it say. Why does an item that is already in a collection need to be linked to that same collection?

How about 'This resource serves as a proxy that represents an item in the collection to allow the expression of positional and other information that applies to the item only in the context of the collection'?

I still think the phrase "an item in the collection" causes confusion, since it's technically only the proxy that's in the collection.
How about "A member of an ordered collection. This resource links an item to a collection and allows the expression of positional and other information that applies to the item only in the context of the collection."?

This is annoyingly difficult to do well. Here is one more attempt. The example is from the IMF.

skos:definition "A member of an ordered collection. It is a proxy for a real world item that can appear in different orders in different collections. The ordered member appears in exactly one ordered collection." skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property and has ordering information either as a number in a sequence, or by preceding or following another ordered member."^^xsd:string ; skos:example "A document template may have parts such as table of contents, introduction, main body, appendix etc, but not all documents have all parts. The appendix might be the third part of one document template, but the 5th part of another. This would correspond to one instance of DocumentPart for an appendix, and two instances of ordered member."^^xsd:string ;

uscholdm

The fact that defining OrderedMember is so difficult to do well, is all the more reason to get it as good as we can.

uscholdm · 2021-07-07T17:33:55Z

gistCore.ttl

+			[
+				a owl:Restriction ;
+				owl:onProperty gist:hasOrderedMember ;
+				owl:minCardinality "1"^^xsd:nonNegativeInteger ;


Its best (for performance and flexibility reasons) to use someValuesFrom rather than min 1. If there is no filter class, just use owl:Thing.

uscholdm · 2021-07-07T17:38:43Z

docs/ReleaseNotes.md

@@ -8,6 +8,7 @@ Release 10.0.0

 - Renamed `MimeType` to `MediaType` to be consistent with [IANA guidelines](https://www.iana.org/assignments/media-types/media-types.xhtml)
  and [RFC6838](https://tools.ietf.org/html/rfc6838). Issue [#434](<https://github.com/semanticarts/gist/issues/434>).
+- Refactored ordered collection model. Includes addition of predicate `gist:providesOrderFor` and deletion of classes `gist:OrdinalCollection` and `gist:OrdinalMember`. Issue [#112](<https://github.com/semanticarts/gist/issues/112>).


Have pieces indented like this:

- Refactored ordered collection model. Issue [#112](<https://github.com/semanticarts/gist/issues/112>) - Added predicate `gist:providesOrderFor` - Deleted classes `gist:OrdinalCollection` and `gist:OrdinalMember`. .

uscholdm · 2021-07-07T18:04:31Z

gistCore.ttl

 	] ;
-	skos:definition "A member of an Ordinal Collection.  It necessarily precedes or is preceded by another Ordinal Member in the same collection. (This last condition cannot be formally stated in OWL)."^^xsd:string ;
-	skos:prefLabel "Ordinal Member"^^xsd:string ;
+	skos:definition "A member of an ordered collection. This resource serves as a proxy linking a real-world item in the collection to that collection, allowing the expression of positional and other information that applies to the item only in the context of the collection."^^xsd:string ;


This is annoyingly difficult to do well. Here is one more attempt. The example is from the IMF.

skos:definition "A member of an ordered collection. It is a proxy for a real world item that can appear in different orders in different collections. The ordered member appears in exactly one ordered collection." skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property and has ordering information either as a number in a sequence, or by preceding or following another ordered member."^^xsd:string ; skos:example "A document template may have parts such as table of contents, introduction, main body, appendix etc, but not all documents have all parts. The appendix might be the third part of one document template, but the 5th part of another. This would correspond to one instance of DocumentPart for an appendix, and two instances of ordered member."^^xsd:string ;

rjyounes · 2021-07-07T19:30:16Z

I think Michael has mostly nailed it. I propose a couple of tweaks:

skos:definition "A member of an ordered collection that serves as a proxy for a real world item, which can appear in different orders in different collections. The ordered member appears in exactly one ordered collection."

skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property and represents ordering information either as a number in a sequence, or by preceding or following another ordered member.  The ordered collection is linked to the ordered member via the property hasOrderedMember. The ordered member may also represent data about the real world item that applies to it only in the context of the ordered collection."

skos:example "A person may rank 12th in the Boston Marathon but 29th in the New York City Marathon."

Michael, I've provided a different example which I think is more straightforward and easier to understand. See what you think. We could of course include both.

uscholdm · 2021-07-07T23:51:52Z

Yes, much better example. Below is a slightly revised version. I split a long sentence in the scope note into two. I also got rid of the last sentence. First, I found it confusing. When I realized what it says, it kind of goes without saying, once the idea is grasped, which is hard enough. If we insist on saying it, then we need to have a compelling example that somehow does not add more complexity and confusion. Even if it was a good example, it still may not be worth saying. Less is more. See also the variation at the end.

skos:definition "A member of an ordered collection that serves as a proxy for a real world item, which can appear in different orders in different collections. The ordered member appears in exactly one ordered collection."

skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property.  Ordering information is represented either as a number in a sequence, or by preceding or following another ordered member.  The ordered collection is linked to the ordered member via the property hasOrderedMember."

skos:example "A person may rank 12th in the Boston Marathon but 29th in the New York City Marathon."

VARIATION: I moved last sentence of definition to first sentence of scope note and replaced it with a new sentence, which I think captures the essence. The scope note is rewriten to exactly echo the last sentence in the definition.

skos:definition "A member of an ordered collection that serves as a proxy for a real world item, which can appear in different orders in different collections. An ordered member exactly corresponds to a particular item in a particular order in a particular (ordered) collection."

skos:scopeNote "An ordered member points to the real world item via the providesOrderFor property. It is linked to exactly one ordered collection via the hasOrderedMember property.    Ordering information is represented either as a number in a sequence, or by preceding or following another ordered member."

skos:example "A person may rank 12th in the Boston Marathon but 29th in the New York City Marathon."

Why was this so fricking hard to do well?

uscholdm · 2021-07-08T18:58:44Z

I saw that Dalia made changes to the annotations, but they were not my latest draft. Can @rjyounes and @daliadahleh have a look to see what we want to go with?

daliadahleh · 2021-07-08T19:06:39Z

@uscholdm, the annotations are from your latest draft. I used the first variation in your latest comment .

rjyounes · 2021-07-08T19:10:34Z

I'm happy to go with this. @uscholdm please give the final go-ahead.

uscholdm · 2021-07-08T20:43:31Z

the annotations are from your latest draft. I used the first variation

I prefer the second variation. Can you say what you prefer about the first?

daliadahleh · 2021-07-08T21:10:36Z

I thought 'An ordered member exactly corresponds to a particular item in a particular order in a particular (ordered) collection' is unnecessarily wordy. The point comes across just as clearly in the first variation. I'm not too picky though, happy to go with either.

uscholdm · 2021-07-08T22:52:13Z

I thought 'An ordered member exactly corresponds to a particular item in a particular order in a particular (ordered) collection' is unnecessarily wordy.

I think I agree, at least for the definition. We could just remove that sentence all together, or put it in the scope note.

Its Rebecca's call. I'm not too bothered either way.

rjyounes · 2021-07-13T15:20:37Z

Let me look at it. It's not actually correct to say it corresponds to a particular item "in a particular order." It is linked to the same item regardless of the order. It will just change its properties (sequence or directlyPrecedes) accordingly.

uscholdm · 2021-07-13T16:55:24Z

OK - maybe its just helpful to me as a way to think about it, but confusing otherwise. Probably best to just leave that verbiage out.

daliadahleh added 2 commits June 24, 2021 12:33

Implemented ordered collections

92c12d0

Updated release notes

2825bcd

daliadahleh requested review from rjyounes, uscholdm and sa-bpelakh June 24, 2021 16:55

daliadahleh assigned rjyounes, uscholdm and sa-bpelakh Jun 24, 2021

daliadahleh linked an issue Jun 24, 2021 that may be closed by this pull request

Address semantic issues related to OrdinalCollection and OrdinalMember #112

Closed

uscholdm requested changes Jun 25, 2021

View reviewed changes

gistCore.ttl Outdated Show resolved Hide resolved

gistDeprecated.ttl Outdated Show resolved Hide resolved

Added owl:deprecated true to deprecated classes. Added scope note to …

1168938

…gist:isProxyFor.

rjyounes requested changes Jun 25, 2021

View reviewed changes

sa-bpelakh requested changes Jun 28, 2021

View reviewed changes

daliadahleh added 5 commits July 1, 2021 09:27

updated release notes

e1adc2c

fixed definitions and notes for ordered collection model

ddd459c

Removed OrdinalMember and OrdinalCollection from gistDeprecated

f5935e3

renamed isProxyFor to providesOrderFor. added domains and ranges to o…

ad8d92d

…rdered collection properties.

fixed release notes to reflect renaming gist:providesOrderFor

9292021

rjyounes requested changes Jul 1, 2021

View reviewed changes

gistCore.ttl Outdated Show resolved Hide resolved

gistCore.ttl Outdated Show resolved Hide resolved

daliadahleh added 3 commits July 1, 2021 14:44

fixed typo in OrderedCollection skopenote

b8d4fe4

fixed restriction on gist:OrderedCollection

9f37651

Merge branch 'develop' into issue112/ordered_collections

a88a780

sa-bpelakh approved these changes Jul 2, 2021

View reviewed changes

uscholdm requested changes Jul 2, 2021

View reviewed changes

rjyounes assigned daliadahleh Jul 7, 2021

uscholdm requested changes Jul 7, 2021

View reviewed changes

Merge branch 'develop' into issue112/ordered_collections

33a69ac

daliadahleh added 2 commits July 8, 2021 10:14

indented release notes

d4660c7

updated OrderedMember restriction and annotations

1ab44e1

rjyounes approved these changes Jul 8, 2021

View reviewed changes

rjyounes merged commit 869adb7 into develop Jul 14, 2021

rjyounes deleted the issue112/ordered_collections branch July 14, 2021 16:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor Ordered Collections. Fixes #112. #495

Refactor Ordered Collections. Fixes #112. #495

daliadahleh commented Jun 24, 2021

uscholdm left a comment

rjyounes left a comment

rjyounes Jun 25, 2021

sa-bpelakh Jun 28, 2021

rjyounes Jul 1, 2021

rjyounes Jun 25, 2021 •

edited

Loading

sa-bpelakh Jun 28, 2021

daliadahleh Jul 1, 2021

rjyounes commented Jun 25, 2021 •

edited

Loading

sa-bpelakh left a comment

sa-bpelakh Jun 28, 2021

sa-bpelakh Jun 28, 2021

rjyounes left a comment

sa-bpelakh left a comment

uscholdm Jul 2, 2021

daliadahleh Jul 7, 2021

rjyounes Jul 7, 2021

uscholdm Jul 7, 2021

uscholdm left a comment

uscholdm Jul 7, 2021

uscholdm Jul 7, 2021

uscholdm Jul 7, 2021

rjyounes commented Jul 7, 2021

uscholdm commented Jul 7, 2021

uscholdm commented Jul 8, 2021 •

edited

Loading

daliadahleh commented Jul 8, 2021

rjyounes commented Jul 8, 2021

uscholdm commented Jul 8, 2021

daliadahleh commented Jul 8, 2021

uscholdm commented Jul 8, 2021

rjyounes commented Jul 13, 2021

uscholdm commented Jul 13, 2021

Refactor Ordered Collections. Fixes #112. #495

Refactor Ordered Collections. Fixes #112. #495

Conversation

daliadahleh commented Jun 24, 2021

uscholdm left a comment

Choose a reason for hiding this comment

rjyounes 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

rjyounes Jun 25, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rjyounes commented Jun 25, 2021 • edited Loading

sa-bpelakh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rjyounes left a comment

Choose a reason for hiding this comment

sa-bpelakh 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

uscholdm 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

rjyounes commented Jul 7, 2021

uscholdm commented Jul 7, 2021

uscholdm commented Jul 8, 2021 • edited Loading

daliadahleh commented Jul 8, 2021

rjyounes commented Jul 8, 2021

uscholdm commented Jul 8, 2021

daliadahleh commented Jul 8, 2021

uscholdm commented Jul 8, 2021

rjyounes commented Jul 13, 2021

uscholdm commented Jul 13, 2021

rjyounes Jun 25, 2021 •

edited

Loading

rjyounes commented Jun 25, 2021 •

edited

Loading

uscholdm commented Jul 8, 2021 •

edited

Loading