Implementation report for Ordered classes/predicates

[azaroth42]

I'm curious as to how you have 3 implementations of OrderedCollection and its corresponding Page, but no implementation of the orderedItems property, which is needed to implement the ordering.

Is this a bug in the reports (missing entry, incorrectly filled), the implementations (using items instead of orderedItems), or in the report generator (skipping the correctly filled data)?

Your attention is appreciated, as this is important for the Annotation group's use of AS2, and we are days away from publication of full TR.

[rhiaro]

orderedItems is an alias of items in terms of JSON-LD.

It's missing from the Vocab spec altogether though, but used as an example in several places (including in items). We should fix that. It's mentioned in Core.

@jasnell Does this mean it's valid to use items with an OrderedCollection? If so, and everybody is using items instead, we'd need to drop orderedItems I think. Unless @azaroth42 is about to file some implementation reports that use it.

@cwebber Any reason you didn't implement orderedItems in your library?

[azaroth42]

They should definitely NOT be aliases if items is intended to be unordered (e.g. an @set) and orderedItems ordered (e.g. an @list). That would be a significant bug, IMO.

I've sent an implementation report that uses it, will have two more on Monday.

[jasnell]

Both the 'items' and 'orderedItems' terms in the JSON-LD context map to the same #Items vocabulary term. Whether the value is sorted or not is a factor of the JSON-LD mapping and not the vocabulary. If you want ordered items, then 'orderedItems' is required as 'items' is always unordered. Please do not drop either one of them.

On Fri, Feb 10, 2017 at 6:43 PM Rob Sanderson notifications@github.com wrote:

They should definitely NOT be aliases if items is intended to be unordered (e.g. an @set https://github.com/set) and orderedItems ordered (e.g. an @list https://github.com/list). That would be a significant bug, IMO.

I've sent an implementation report that uses it, will have two more on Monday.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/w3c/activitystreams/issues/388#issuecomment-279115254, or mute the thread https://github.com/notifications/unsubscribe-auth/AAa2ef0nTmqXZEBzlGQ-4KsbujFV1hkWks5rbSA3gaJpZM4L9ukQ .

[rhiaro]

The JSON-LD context contains

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

@azaroth42 does that cover what you need, or is the alias still a problem? This is a bit out of scope of my own understanding of JSON-LD.

@jasnell The group had agreed to drop things that don't get implementations in order to exit CR. Fortunately it looks like orderedItems will have implementations from Annotations.

[sandhawke]

@jasnell just to clarify and confirm -- we need to move along, and we can't do that with any terms for which we don't have two implementation reports. So the plan is to move anything like that from the Recommendation to extensions. Since we agreed approved extensions can use the as: namespace, this should have very little impact. I'm not quite sure how we're planning to present them in documentation, yet.

[jasnell]

Again, it's important to note that there is no separate OrderedItems term in the vocabulary. The orderedItems label is an artifact of the JSON-LD mapping and the serialization syntax that is necessary to achieve ordering. You simply cannot ensure that the order of items will be preserved without a JSON-LD mapped term that ensures order. The function of that is independent of the vocabulary itself. Dropping the term would serve no purpose if you kept OrderedCollection because there would be no way of guaranteeing order in that OrderedCollection without such a mapped term.

[sandhawke]

That makes sense.

It doesn't quite answer why people say they are implementing OrderedCollection but not orderedItem. Or maybe it does...

Perhaps the answer is that for a consumer using a json-ld library,they don't need to be aware of orderedItem -- it's just handled by the generic json-ld code. Maybe even for serialization; can json-ld libraries do that -- turn triples into something using orderedItem?

(not sure when I might have time to dig deeper to answer those questions, so I'm just stating them for now.)

[jasnell]

I think the primary reason would be lack of understanding about how the JSON-LD mapping operates.

Consider the following example that uses the items term for the collection of entries: (JSON-LD Playground)

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollection",
  "items": [
    {
      "type": "Note",
      "id": "urn:example.org:2",
      "name": "Foo"
    },
    {
      "type": "Note",
      "id": "urn:example.org:1",
      "name": "Bar"
    }
  ]
}

The expanded JSON-LD form for this is:

[
  {
    "http://www.w3.org/ns/activitystreams#items": [
      {
        "@id": "urn:example.org:2",
        "http://www.w3.org/ns/activitystreams#name": [
          {
            "@value": "Foo"
          }
        ],
        "@type": [
          "http://www.w3.org/ns/activitystreams#Note"
        ]
      },
      {
        "@id": "urn:example.org:1",
        "http://www.w3.org/ns/activitystreams#name": [
          {
            "@value": "Bar"
          }
        ],
        "@type": [
          "http://www.w3.org/ns/activitystreams#Note"
        ]
      }
    ],
    "@type": [
      "http://www.w3.org/ns/activitystreams#OrderedCollection"
    ]
  }
]

And the normalized Quads would be:

<urn:example.org:1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#Note> .
<urn:example.org:1> <http://www.w3.org/ns/activitystreams#name> "Bar" .
<urn:example.org:2> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#Note> .
<urn:example.org:2> <http://www.w3.org/ns/activitystreams#name> "Foo" .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#OrderedCollection> .
_:c14n0 <http://www.w3.org/ns/activitystreams#items> <urn:example.org:1> .
_:c14n0 <http://www.w3.org/ns/activitystreams#items> <urn:example.org:2> .

Now, switch the example to use orderedItems as appropriate:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "OrderedCollection",
  "orderedItems": [
    {
      "type": "Note",
      "id": "urn:example.org:2",
      "name": "Foo"
    },
    {
      "type": "Note",
      "id": "urn:example.org:1",
      "name": "Bar"
    }
  ]
}

The expanded JSON-LD form becomes:

[
  {
    "http://www.w3.org/ns/activitystreams#items": [
      {
        "@list": [
          {
            "@id": "urn:example.org:2",
            "http://www.w3.org/ns/activitystreams#name": [
              {
                "@value": "Foo"
              }
            ],
            "@type": [
              "http://www.w3.org/ns/activitystreams#Note"
            ]
          },
          {
            "@id": "urn:example.org:1",
            "http://www.w3.org/ns/activitystreams#name": [
              {
                "@value": "Bar"
              }
            ],
            "@type": [
              "http://www.w3.org/ns/activitystreams#Note"
            ]
          }
        ]
      }
    ],
    "@type": [
      "http://www.w3.org/ns/activitystreams#OrderedCollection"
    ]
  }
]

Which translates into the following normalized quads:

<urn:example.org:1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#Note> .
<urn:example.org:1> <http://www.w3.org/ns/activitystreams#name> "Bar" .
<urn:example.org:2> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#Note> .
<urn:example.org:2> <http://www.w3.org/ns/activitystreams#name> "Foo" .
_:c14n0 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/activitystreams#OrderedCollection> .
_:c14n0 <http://www.w3.org/ns/activitystreams#items> _:c14n2 .
_:c14n1 <http://www.w3.org/1999/02/22-rdf-syntax-ns#first> <urn:example.org:1> .
_:c14n1 <http://www.w3.org/1999/02/22-rdf-syntax-ns#rest> <http://www.w3.org/1999/02/22-rdf-syntax-ns#nil> .
_:c14n2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#first> <urn:example.org:2> .
_:c14n2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#rest> _:c14n1 .

Here, the quads contain explicit ordering details. In both examples, the mapped term is still http://www.w3.org/ns/activitystreams#items. In the former example, there are multiple independent values for http://www.w3.org/ns/activitystreams#items, in the latter example, there is a single value for http://www.w3.org/ns/activitystreams#items that is an ordered list.

In either case, using orderedItems or items counts as an implementation of the vocabulary term http://www.w3.org/ns/activitystreams#items. Using OrderedCollection without also using orderedItems should be considered an implementation bug because the implementation is declaring that the collection is ordered without doing anything to preserve the order of the items.

[evanp]

Do we have an action to do here?

[cwebber]

FWIW Pubstrate and Soci-el are both using the orderedItems property, and that'll be reflected once I get in the updated implementation reports for them this week.

[cwebber]

Oh I see, there's no slot to say whether or not you implemented orderedItems on the current implementation reports template... no wonder!

But, soci-el and Pubstrate have both implemented it, with Pubstrate as both producer and consumer.

[cwebber]

Ah I wasn't paying close enough to what @jasnell said. It doesn't matter though, the orderedItems is "observed" in the "dumb" reading of json (not looking at it from the json-ld expanded form) that's done in Pubstrate after expansion/compaction (and in soci-el generally, which is straight up dumb, no expansion/compaction, just reading it as simple json).

[cwebber]

Can we close this then? It looks like that property is used, even though it's "just an artifact" anyhow.

[azaroth42]

:+1: to closing

[evanp]

Closing