5.1 Informative

Many HTTP applications and sites have organizing concepts that partition the overall space of resources into smaller containers. Blog posts are grouped into blogs, wiki pages are grouped into wikis, and products are grouped into catalogs. Each resource created in the application or site is created within an instance of one of these container-like entities, and users can list the existing artifacts within one. Containers answer some basic questions, which are:

1. To which URLs can I POST to create new resources?
2. Where can I GET a list of existing resources?
3. How is the order of the container entries expressed?
4. How do I get information about the members along with the container?
5. How do I GET the entries of a large container broken up into pages?
6. How can I ensure the resource data is easy to query?

This document defines the representation and behavior of containers that address these issues. The set of members of a container is defined by a set of triples in its representation (and state) called the membership triples. The membership triples of a container all have the same subject and predicate – the objects of the membership triples define the members of the container. The subject of the membership triples is called the membership subject and the predicate is called the membership predicate. In the simplest cases, the membership subject will be the BPC resource itself, but it does not have to be. The membership predicate is also variable and will often be a predicate from the server application vocabulary or the rdfs:member predicate.

This document includes a set of guidelines for using POST to create new resources and add them to the list of members of a container. This document also explains how to include information about each member in the container’s own representation and how to paginate the container representation if it gets too big.

The following illustrates a very simple container with only three members and some information about the container (the fact that it is a container and a brief title):

# The following is the representation of
#    http://example.org/container1
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
<http://example.org/container1>
   a bp:Container;
   dcterms:title "A very simple container";
   rdfs:member
      <http://example.org/container1/member1>,
      <http://example.org/container1/member2>,
<http://example.org/container1/member3>.

This example is very straightforward - the membership predicate is rdfs:member and the membership subject is the container itself. A POST to this container will create a new resource and add it to the list of members by adding a new membership triple to the container.

Sometimes it is useful to use a subject other than the container itself as the membership subject and to use a predicate other than rdfs:member as the membership predicate, as illustrated below.

# The following is the representation of
#   http://example.org/netWorth/nw1/assetContainer
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
@prefix o: <http://example.org/ontology/>.
<http://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   bp:membershipSubject <http://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<http://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <http://example.org/netWorth/nw1/assetContainer/a1>,
<http://example.org/netWorth/nw1/assetContainer/a2>.

The essential structure of the container is the same, but in this example, the membership subject is not the container itself – it is a separate net worth resource. The membership predicate is o:asset – a predicate from the domain model. A POST to this container will create a new asset and add it to the list of members by adding a new membership triple to the container. You might wonder why we didn’t just make http://example.org/netWorth/nw1 a container and POST the new asset directly there. That would be a fine design if http://example.org/netWorth/nw1 had only assets, but if it has separate predicates for assets and liabilities, that design will not work because it is unspecified to which predicate the POST should add a membership triple. Having separate http://example.org/netWorth/nw1/assetContainer and http://example.org/netWorth/nw1/liabilityContainer container resources allows both assets and liabilities to be created.

In this example, clients cannot simply guess which resource is the membership subject and which predicate is the membership predicate, so the example includes this information in triples whose subject is the BPC resource itself.

In many – perhaps most – applications involving containers, it is desirable for the client to be able to get information about each container member without having to do a GET on each one. BPC allows servers to include this information directly in the representation of the container. The server decides the amount of data about each member that is provided. Some common strategies include providing a fixed number of standard properties, or providing the entire RDF representation of each member resource, or providing nothing. The server application domain and its use-cases will determine how much information is required.

Continuing on from the net worth example, there will be additional triples for the member resources (assets) in the representation:

# The following is the representation of
#	 http://example.org/netWorth/nw1/assetContainer
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#>.
@prefix bp:      <http://open-services.net/ns/basicProfile#>.
@prefix o:       <http://example.org/ontology/>.
<http://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <http://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<http://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <http://example.org/netWorth/nw1/assetContainer/a1>,
      <http://example.org/netWorth/nw1/assetContainer/a3>,
      <http://example.org/netWorth/nw1/assetContainer/a2>.
<http://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 10000.
<http://example.org/netWorth/nw1/assetContainer/a2>
   a o:Bond;
   o:value 20000.
<http://example.org/netWorth/nw1/assetContainer/a3>
   a o:RealEstateHolding;
 
 o:value
300000.

The representation of a container that has many members will be large. There are several important cases where clients need to access only the non-member properties of the container. Since retrieving the whole container representation to get this information may be onerous for clients and cause unnecessary overhead on servers, it is desired to define a way to retrieve only the non-member property values. Defining for each BPC a corresponding resource, called the “non-member resource”, whose state is a subset of the state of the container, does this.

The example listed here only show a simple case where only a few simple non-member properties are retrieved. In real world situations more complex cases are likely, such as those that add other predicates to containers, for example providing validation information and associating SPARQL endpoints. [[RDF-SPARQL-QUERY]]

Here is an example requesting the non-member properties of a container identified by the URL http://example.org/container1 and adding the query string ?non-member-properties :

Request:

GET /container1?non-member-properties HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8

Response:

HTTP/1.1 200 OK
Content-Type: text/turtle; chartset=UTF-8
ETag: "_87e52ce291112"
Content-Length: 325
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
<http://example.org/container1>
   a bp:Container;
   dcterms:title "A Basic Profile Container of Acme Resources";
   bp:membershipPredicate rdfs:member;
dcterms:publisher
<http://acme.com/>.

It sometimes happens that a container is too large to reasonably transmit its representation in a single HTTP response. This will be especially true if the container representation includes many triples from the representations of its members. A client may anticipate that a container will be too large - for example, a client tool that accesses defects may assume that an individual defect will usually be of sufficiently constrained size that it makes sense to request all of it at once, but that the container of all the defects ever created will typically be too big. Alternatively, a server may recognize that a container that has been requested is too big to return in a single message.

To address this problem, BPCs may support a technique called Paging.  Paging can be achieved with a simple RDF pattern. For each container resource, <containerURL> , we define a new resource <containerURL>?firstPage . The triples in the representation of <containerURL>?firstPage are a subset of the triples in <containerURL> - same subject, predicate and object.

BPC servers may respond to requests for a container by redirecting the client to the first page resource – using a 303 “See Other” redirect to the actual URL for the page resource.

Continuing on from the member information from the JohnZSmith net worth example, we’ll split the response across two pages.  The client requests the first page as http://example.org/netWorth/nw1/assetContainer?firstPage :

# The following is the representation of
#    http://example.org/netWorth/nw1/assetContainer?firstPage
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
@prefix o: <http://example.org/ontology/>.
<http://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <http://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<http://example.org/netWorth/nw1/assetContainer?firstPage>
   a bp:Page;
   bp:pageOf <http://example.org/netWorth/nw1/assetContainer>;
   bp:nextPage <http://example.org/netWorth/nw1/assetContainer?p=2>.
 
<http://example.org/netWorth/nw1>
    a o:NetWorth;
	o:asset
	<http://example.org/netWorth/nw1/assetContainer/a1>,
	<http://example.org/netWorth/nw1/assetContainer/a4>,
	<http://example.org/netWorth/nw1/assetContainer/a3>,
	<http://example.org/netWorth/nw1/assetContainer/a2>.
<http://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 100.00.
<http://example.org/netWorth/nw1/assetContainer/a2>
   a o:Cash;
   o:value 50.00.
#
server
initially
supplied
no
data
for
a3
and
a4
in
this
response

The following example is the result of retrieving the representation for the next page:

# The following is the representation of
#  http://example.org/netWorth/nw1/assetContainer?p=2
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
@prefix o: <http://example.org/ontology/>.
<http://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <http://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<http://example.org/netWorth/nw1/assetContainer?p=2>
   a bp:Page;
   bp:pageOf <http://example.org/netWorth/nw1/assetContainer>;
   bp:nextPage rdf:nil.
<http://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset 
      <http://example.org/netWorth/nw1/assetContainer/a5>.
<http://example.org/netWorth/nw1/assetContainer/a5>
   a o:Stock;
   dcterms:title "Big Co.";
o:value
200.02.

In this example, there is only one member in the container in the final page.  To indicate this is the last page, a value of rdf:nil is used for the bp:nextPage predicate of the page resource.

BPC guarantees that any and all the triples about the members will be on the same page as the membership triple for the member.

There are many cases where an ordering of the members of the container is important. BPC does not provide any particular support for server ordering of members in containers, because any client can order the members in any way it chooses based on the value of any available property of the members. In the example below, the value of the o:value predicate is present for each member, so the client can easily order the members according to the value of that property. In this way, BPC avoids the use of RDF constructs like Seq and List for expressing order.

Order only becomes important for BPC servers when containers are paginated. If the server does not respect ordering when constructing pages, the client is forced to retrieve all pages before sorting the members, which would defeat the purpose of pagination. In cases where ordering is important, a BPC server exposes all the members on a page with a higher sort order than all members on the previous page and lower sort order than all the members on the next page. The BPC specification provides a predicate - bp:containerSortPredicates - that the server may use to communicate to the client which predicates were used for page ordering. Multiple predicate values may have been used for sorting, so the value of this predicate is an ordered list.

Here is an example container described previously, with representation for ordering of the assets:

# The following is the ordered representation of
#   http://example.org/netWorth/nw1/assetContainer
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix bp: <http://open-services.net/ns/basicProfile#>.
@prefix o: <http://example.org/ontology/>.
<http://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <http://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<http://example.org/netWorth/nw1/assetContainer?firstPage>
   a bp:Page;
   bp:pageOf <http://example.org/netWorth/nw1/assetContainer>;
   bp:containerSortPredicates (o:value).
<http://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <http://example.org/netWorth/nw1/assetContainer/a1>,
      <http://example.org/netWorth/nw1/assetContainer/a3>,
      <http://example.org/netWorth/nw1/assetContainer/a2>.
<http://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 100.00.
<http://example.org/netWorth/nw1/assetContainer/a2>
   a o:Cash;
   o:value 50.00.
<http://example.org/netWorth/nw1/assetContainer/a3>
   a o:RealEstateHolding;
 
 o:value
300000.

As you can see by the addition of the bp:containerSortPredicates predicate, the o:value predicate is used to define the ordering of the results.  It is up to the domain model and server to determine the appropriate predicate to indicate the resource’s order within a page, and up to the client receiving this representation to use that order in whatever way is appropriate, for example to sort the data prior to presentation on a user interface.

5.2 General