Proposed update to collection semantics

>From a recent conversation in Github:
https://github.com/jasnell/w3c-socialwg-activitystreams/issues/193#issuecomment-127748852

I am proposing the following modification to the as:Collection and
as:OrderedCollection classes in the core vocabulary. The proposal is
based on feedback from implementers working to integrate the AS2
vocabulary with other work (such as the web annotations stuff).

I've copied the text of my proposal in github below. While the
proposal does add a handful of new classes, the change adds more
clarity to the Collection/Paging model.
-----

Currently, we have Collection and OrderedCollection that have these
somewhat strangely placed page properties included. The proposal is:

1. Introduce new PagedCollection, CollectionPage and
OrderedCollectionPage types;OrderedCollectionPage extends from
CollectionPage.
2. Allow first, last and current properties on PagedCollection to
indicate the first, last and current pages of the Paged Collection.
(current identifies the page with the most recently published/updated
items).
3. Allow first, last, next, prev and current properties on CollectionPage.
4. Make itemsPerPage a property on PagedCollection
5. Move startIndex to OrderedCollectionPage
6. Introduce as:pageOf as a property on CollectionPage to allow a page
to point back to it's

Specifically:

as:PagedCollection a owl:Class ;
  rdfs:subClassOf as:Collection .

# A Collection Page is essentially a collection containing a
# subset of members from a full logical collection.
as:CollectionPage a owl:Class ;
  rdfs:subClassOf as:Collection .

as:OrderedCollectionPage a owl:Class ;
  rdfs:subClassOf as:OrderedCollection, as:CollectionPage .

as:pageOf a owl:FunctionalProperty,
           owl:ObjectProperty ;
  rdfs:label "pageOf"@en;
  rdfs:domain as:CollectionPage ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf (as:Collection as:Link )
  ] .

as:first a owl:FunctionalProperty ,
           owl:ObjectProperty ;
  rdfs:label "first"@en ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf (as:PagedCollection as:CollectionPage )
  ] ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf ( as:CollectionPage as:Link )
  ] .

as:last a owl:FunctionalProperty ,
           owl:ObjectProperty ;
  rdfs:label "last"@en ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf (as:PagedCollection as:CollectionPage )
  ] ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf ( as:CollectionPage as:Link )
  ] .

as:current a owl:FunctionalProperty ,
           owl:ObjectProperty ;
  rdfs:label "current"@en ;
  rdfs:domain [
    a owl:Class ;
    owl:unionOf (as:PagedCollection as:CollectionPage )
  ] ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf ( as:CollectionPage as:Link )
  ] .

as:next a owl:FunctionalProperty ,
           owl:ObjectProperty ;
  rdfs:label "prev"@en ;
  rdfs:domain as:CollectionPage ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf ( as:CollectionPage as:Link )
  ] .

as:prev a owl:FunctionalProperty ,
           owl:ObjectProperty ;
  rdfs:label "prev"@en ;
  rdfs:domain as:CollectionPage ;
  rdfs:range [
    a owl:Class ;
    owl:unionOf ( as:CollectionPage as:Link )
  ] .

as:itemsPerPage a owl:DatatypeProperty ,
          owl:FunctionalProperty ;
  rdfs:label "itemsPerPage"@en ;
  rdfs:comment "The maximum number of items per page in a logical
Collection"@en ;
  rdfs:range xsd:nonNegativeInteger ;
  rdfs:domain as:PagedCollection .

as:startIndex a owl:DatatypeProperty ,
        owl:FunctionalProperty ;
  rdfs:label "startIndex"@en ;
  rdfs:comment "In a strictly ordered logical collection, specifies
the index position of the first item in the items list"@en ;
  rdfs:range xsd:nonNegativeInteger ;
  rdfs:domain as:OrderedCollectionPage .

Example: Simple Unpaged Collection (exactly what we have now, except
without paging properties)

{
  "@type": "Collection",
  "@id": "http://example.org/collection",
  "totalItems": 75,
  "items": [ ... ]
}

Example: Simple Paged Collection

{
  "@type": "PagedCollection",
  "@id": "http://example.org/collection",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "itemsPerPage": 25,
  "totalItems": 75
}

{
  "@type": "CollectionPage",
  "@id": "http://example.org/collection?page=0",
  "pageOf": "http://example.org/collection",
  "next": "http://example.org/collection?page=1"
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "items": [ ... ]
}

{
  "@type": "CollectionPage",
  "@id": "http://example.org/collection?page=1",
  "pageOf": "http://example.org/collection",
  "prev": "http://example.org/collection?page=0",
  "next": "http://example.org/collection?page=2",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "items": [ ... ]
}

{
  "@type": "CollectionPage",
  "@id": "http://example.org/collection?page=2",
  "pageOf": "http://example.org/collection",
  "prev": "http://example.org/collection?page=1",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "items": [ ... ]
}

Example: Paged Ordered Collection

{
  "@type": ["PagedCollection", "OrderedCollection"],
  "@id": "http://example.org/collection",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "itemsPerPage": 25,
  "totalItems": 75
}

{
  "@type": "OrderedCollectionPage",
  "@id": "http://example.org/collection?page=0",
  "pageOf": "http://example.org/collection",
  "next": "http://example.org/collection?page=1"
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "startIndex": 0,
  "items": [ ... ]
}

{
  "@type": "OrderedCollectionPage",
  "@id": "http://example.org/collection?page=1",
  "pageOf": "http://example.org/collection",
  "prev": "http://example.org/collection?page=0",
  "next": "http://example.org/collection?page=2",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "startIndex": 25,
  "items": [ ... ]
}

{
  "@type": "OrderedCollectionPage",
  "@id": "http://example.org/collection?page=2",
  "pageOf": "http://example.org/collection",
  "prev": "http://example.org/collection?page=1",
  "first": "http://example.org/collection?page=0",
  "last": "http://example.org/collection?page=2",
  "totalItems": 25,
  "startIndex": 50,
  "items": [ ... ]
}

Received on Wednesday, 5 August 2015 18:36:58 UTC