Please clarify "items" and "orderedItems" properties

[cjslep]

Please Indicate One:

• [ ] Editorial
• [ ] Question
• [ ] Feedback
• [X] Blocking Issue
• [ ] Non-Blocking Issue

Please Describe the Issue:

(I am splitting my email to the public-socialweb mailing list into separate issues, for background please see those emails).

This is ActivityStream vocabulary specific: https://www.w3.org/TR/activitystreams-vocabulary

The "orderedItems" property is omitted from the spec and only present in examples. Therefore, for an OrderedCollection there is no guidance on how to resolve "items" and "orderedItems" if one or both are present. Nor is there guidance whether a "type" property of "Collection" with a "orderedItems" property is in or out of spec.

[sebilasse]

What do you mean by "omitted" ? - is it the same as in https://github.com/w3c/activitystreams/issues/443 for "nameMap", "summaryMap", and "contentMap" ?

[cjslep]

No. The natural language variants nameMap, summaryMap, and contentMap are described in Section 4.7 of the ActivityStreams Core specification, and explicitly lists those as being natural language properties.

However, the ActivityStreams Core spec refers to the orderedItems property exactly twice in the text and once in the example. The two text entries are:

In the JSON serialization, the unordered items of a Collection are represented using the items property while ordered items are represented using the orderedItems property.

Often, it becomes impractical for an implementation to serialize every item contained by a Collection using the items (or orderedItems) property alone.

Which to me implies it is OK to have a "type": "Collection" ActivityStream object with an orderedItems property instead of an items property. It just means that it would be treated as ordered items.

In the ActivityStreams Vocabulary spec, properties section there are no references to the 'orderedItems' property at all. However, the items property says in its Notes:

Identifies the items contained in a collection. The items might be ordered or unordered.

This to me makes it sound like it is OK to have a "type": "OrderedCollection" ActivityStream object with an items property. It also would just mean to treat those items as ordered.

[sebilasse]

I see, so I edited the comment below.

[gobengo]

I also think it would best serve spec-readers to include 'orderedItems' under https://www.w3.org/TR/activitystreams-vocabulary/#properties

[aschrijver]

I interpreted Vocabulary spec on items to mean:

• If the collection is an unordered Collection, then use items
• If the collection is an OrderedCollection, then use orderedItems

So a mutually exclusive choice.

As explained by @cjslep like 'all combinations are possible' would be inconsistent, IMHO, and lead to unnecessary code in an implementation.

[kefo]

Righty. So @aschrijver's interpretation of the text is probably exactly how items and orderedItems are to be used.

The issue @cjslep is raising is the fact that orderedItems, while discussed in the core text (and shown in an example), is not formally included in the Activity Vocabulary.

orderedItems is defined in the namespace document: https://www.w3.org/ns/activitystreams#property-definitions

And it is linked from the namespace document to the Activity Vocabulary document: https://www.w3.org/TR/activitystreams-vocabulary#dfn-ordereditems

BUT, if you follow that link to the Activity Vocabulary document, you will discover that #dfn-ordereditems does not reference anything in the page.

Conversely, compare the link from the namespace document for items: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-items

I imagine if orderedItems were described in the Activity Vocabulary it would have a domain of OrderedCollection, in much the same way items has a domain of Collection. I don't know if any additional description would be needed in the text.

I've not read the listserv thread @cjslep references but I suspect this is what he is getting at. orderedItems is discussed in the core text but not mentioned, save in examples, in the Activity Vocabulary. And because everything else, in particular items, has been included in the Activity Vocabulary and relevant domain/range clearly articulated, it leaves open to some interpretation the use of orderedItems.

Is this omission intentional? If so, why? If not, then orderedItems is missing - i.e. not formally described - from the Activity Vocabulary document.

[nightpool]

orderedItems is an alias of items that has different JSON-LD semantics, but identical RDF semantics, so yes, its omission from the Activity Vocabulary definition is intentional. They both have the same canonical URI

[nightpool]

https://github.com/w3c/activitystreams/issues/507 has a more thorough description of the issue, as well as links to other discussions

[kefo]

I feel the desire to split hairs on this - orderedItems has "different JSON-LD semantics, but identical RDF semantics" - is the source of some of the problem here. Instead of unambiguously defining the property in the Vocabulary, the distinction has been shunted down into the context, and it is a fine distinction at that. Besides, it seems to me that anyone encountering the orderedItems property in the wild and then applying the context and then converting the JSONLD to some other RDF serialization (maybe not the idea for AS but not precluded either) will view the resulting RDF has having different semantics, whether intended or not.

Which brings me back to this Issue topic, titled "Please clarify 'items' and 'orderedItems' properties." Given the number of times this has come up, with the potential semantic issues, do the editors think this is clear? If so, I would say close this issue with a note that says "perfectly clear and no problem."

If not, I, like @cjslep , think this needs some clarification and I will try one last time. orderedItems is listed in the ActivityStreams 2.0 Terms document under the property definitions section, in which we find the first sentence to be "the following are property definitions in the as namespace. This makes it appear to not be a mere alias but a uniquely defined property in the as namespace. So much so there is a link to the Activity Vocabulary for this property. But it is not in the as namespace. It is is an alias in the JSONLD context for as:items, so we discovered in this thread. As such, the link goes nowhere. And of course there is nothing, anywhere, to explain this concept of different JSONLD semantics but same RDF semantics (which, as an aside, and at the risk of repeating myself so soon, I'm not clear is the case since a conversion to some other RDF serialization would produce very different results if items is encountered versus orderedItems in the JSONLD since orderedItems will result in a single as:items property with an rdf:List while items will result in multiple as:items with generic rdf:Resources as objects, I think).

items and orderedItems are aliased in the context to as:items. This is the only non-language property this happens with. (And it is worth pointing out that the other properties treated this way are *Map properties and they've caused their own confusion at times.) That's why I think splitting hairs here is not worth the trouble. Cleanly defining orderedItems (actually) in the as namespace would bring some clarity to this. Finally, as noted by @aschrijver, the lack of clear Vocabulary semantics for orderedItems allows many permutations presently. I believe the following are perfectly legit (the first one is arguably logically legitimate, but the second I suspect is unintended):

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "summary": "Sally's notes",
  "type": "Collection",
  "totalItems": 2,
  "orderedItems": [
    {
      "type": "Note",
      "name": "Reminder for Going-Away Party"
    },
    {
      "type": "Note",
      "name": "Meeting 2016-11-17"
    }
  ]
}

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "summary": "Sally's notes",
  "type": "OrderedCollection",
  "totalItems": 2,
  "items": [
    {
      "type": "Note",
      "name": "Reminder for Going-Away Party"
    },
    {
      "type": "Note",
      "name": "Meeting 2016-11-17"
    }
  ]
}

[evanp]

There are two main problems here:

1. The orderedItems property is not listed in Activity Streams Vocabulary.
2. The relationship between Collection, OrderedCollection, items, and orderedItems is not clear.

I think there are two remedies for this problem.

1. We should add the orderedItems property definition to the ERRATA document. We should add the orderedItems property as a property of OrderedCollection.
2. We should document on the Primer some best practices for publishing and consuming Collections with order and unordered.

[evanp]

https://www.w3.org/wiki/Activity_Streams/Primer/Collections has guidance for publishers and consumers for dealing with collections, pages, and properties.

[evanp]

My next TODO on this topic is to propose an addition to the ERRATA for Activity Streams 2.0 and submit it for approval by the CG.

[pietercolpaert]

There are two main problems here:

1. The orderedItems property is not listed in Activity Streams Vocabulary.

Is there a semantic difference between orderedItems and items of an ordered collection? I wonder if we shouldn’t just deprecate orderedItems and always use item.

2. The relationship between Collection, OrderedCollection, items, and orderedItems is not clear.

I believe we should have a concept of 1 collection that has multiple views, and each of these views can be ordered or structured in a different way. That’s the way we do it in TREE.

In one project, we would now see the OrderedCollection as a specific tree:ViewDescription of a dataset in which we can understand that the next page to contain certain element that are greater than or less than a certain value.

[nightpool]

Is there a semantic difference between orderedItems and items of an ordered collection? I wonder if we shouldn’t just deprecate orderedItems and always use item.

there is no semantic difference but there is a major syntactic difference, one is a @list and the other is a @set, so one has a range of ordered lists and the other is just a normal triple.

there is no easy way to represent this distinction in JSON-LD without 1) using two properties or 2) imposing arcane and bad syntax on pure json consumers. this is the best compromise

[kefo]

there is no easy way to represent this distinction in JSON-LD without 1) using two properties or 2) imposing arcane and bad syntax on pure json consumers. this is the best compromise

The current situation is the best compromise? Assuming, yes, I'm not sure a compromise that promotes this level of questioning is the "best."

Why, exactly, is defining an additional property in the AS namespace (as is currently advertised, but not actually done) a problem?

[pietercolpaert]

there is no easy way to represent this distinction in JSON-LD without 1) using two properties or 2) imposing arcane and bad syntax on pure json consumers. this is the best compromise

Couldn’t you do something like this to make both worlds happy?

{
  "@context": {
     "items" : {"@id": "as:items", "@container": "@set"},
     "orderedItems" : { "@id": "as:items", "@container": "@list"}
  }
} 

EDIT: actually, this is how it is done if i’m not mistaken, which is actually the whole reason why orderedItems is a JSON-LD label, but not a separate IRI. So in my opinion, nothing needs to be done at the moment and this issue can be closed: it’s only a JSON-specific thing.

I would also like to make a side-note here however that I believe using an @list /rdf:List here is not that useful from an RDF perspective. The only interesting part about an ordered collection is a client knowing whether they are interested in the next page or not. If it is not, it will save HTTP calls. In the page itself using an rdf:List means spending more RDF statements on ordering entities, while the client itself could also just order these entities based on how the client wants them ordered, without a noteworthy loss in performance as this can happen at parsing to object translation. While this is true from an RDF perspective, I understand this may also be different from a JSON-LD point of view.

[tesaguri]

As a side note, in JSON-LD 1.1 (but not in 1.0), you could type-scope the item term like the following, so that the term expands to a @list in an OrderedCollection object and to a @set otherwise:

{
  "@context": {
    "items": {
      "@id": "as:items",
      "@container": "@set"
    },
    "OrderedCollection": {
      "@id": "as:OrderedCollection",
      "@context": {
        "@propagate": false,
        "items": {
          "@id": "as:items",
          "@container": "@list"
        }
      }
    }
  }
}

But Activity Streams is based on JSON-LD 1.0, and besides, this definition of the items term wouldn't be able to represent a Collection with an as:items property of an rdf:List resource, so I'm not sure if this would be desirable even if AS were able to take advantage of JSON-LD 1.1 features.