OSLC Reporting Specification V1 Issues

This section captures the issues raised on the Reporting Specification:

Issues are organized via the specification outline.

Note: dates below use US format (mm/dd/yyyy)

Here's what the states mean:

• OPEN - indicates that we have no response for the issue yet
• RESOLVED - indicates that we have a response that we believe resolves the issue
• CLOSED - issue has been resolved and the resolution has been reviewed by the WG
• TABLED - indicates that issue will be reconsidered at some later for future version of the specificaiton

Overall

Overview

1. RESOLVED The sequence diagram is very helpful. It would be useful to proceed it with some descriptive language that introduces the assumptions for the reporting specification. For example, that the specification assumes that the reporting consumer has no specific knowledge of the service provider or service provider domain resources. It relies wholly on the service provider for discovering the shape of resources and their properties and for the presence of an OSLC query capability. Based on the resource shape and query capabilities, a reporting consumer is able to offer it's users the ability to design and run reports, including scenarios of live reporting against the service provider or against a data warehouse. This is just one example. (ScottBosworth, 05/03/2010)
   • Response More description added as suggested. (TackTong, 05/07/2010)

Glossary of Terms

Interface Sequence Diagram

Service Provider Resource

1. RESOLVED The first sub-bullet should be reworded to remove references to single-subject and multi-subject query capabilities. Those topics are no longer included in the Core. I think this section overall should say that only that a Query capability must be provided, that the Query capability should limit responses to include a single type of resource, and that the query capability have shape resource. (ScottBosworth, 05/03/2010).
   • Response Remove all references to self-subject or multi-subject. (TackTong, 05/07/2010)

Resource Shape Resource

1. RESOLVED Please review the second two paragraphs of this section - they seem to have some grammatical problems and incomplete sentences. (ScottBosworth, 05/03/2010).
   • Response Fix grammer. (TackTong, 05/07/2010)

Query

1. RESOLVED In the current OSLC Reporting spec, you have the statement: "An OSLC Service MUST support paging and include oslc:responseInfo as required in the response of a query." However, note that the core spec says "The server MAY return the logical response as sequence of physical responses, referred to as pages."
   What is the reason for the MUST in the Reporting spec? Do you mean that if a response is paged, it must be done as per the core spec? Or do you mean that the server must really break down a response into pages? If you mean the former, I'm not sure the statement is necessary - all OSLC specs from here on are supposed to be compliant with the core spec, so if paging is performed, that is how it must be done. If you mean the latter, why? What is the maximum size of a reportable response? If a provider decided to page after 100 petabytes, is that compliant? If no maximum size is defined, a client has to handle a response of an arbitrary size, and therefore will be able to handle a response from a provider that does not page.
   Of course, a provider that does not implement paging might not be able to return a very large query result, so support for paging is recommended - but perhaps a given provider knows it's database is not that large.
   It seems to me the statement should probably use SHOULD rather than MUST. (TackTong for NickCrossley, 04/28/2010)
   • Response Specification updated from "MUST support paging ....." to "SHOULD support paging....". (TackTong, 04/30/2010)

Resource Representation

Authentication

Guidance

Example