OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-domains message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Comments on OSLC AM Spec 2.1

Here are some comments on the AM Specification
Terminology Section
Add a comma.
<section id='abstract'>
  <p>This specification defines the OSLC Architecture Management domain, a RESTful web services interface for the management of architectural resources and relationships between those and related resources such as product change requests, activities, tasks, requirements or test cases. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, as well as HTTP response codes, content type handling and resource formats.</p>
Need a comma added here.
      <dd>A logical relationship from one resource to another resource. An OSLC AM Link is uni-directional.
        The subject (source) of a link represents the resource that "knows
        about" and is referencing another resource (target). The type of
        relationship is given by a predicate URI (link type). In semantic web
        terminology, a link would correspond to an RDF statement with a subject
        (source), a predicate (type) and object (target). The predicate could be
        defined by property in an RDF schema.</dd>
Simple semantic word change.
      <dt><dfn>Link type Resource (LTR)</dfn></dt>
      <dd>A resource that contains human consumable information about a Link Type, like its human readable
        name and description. The resource is managed by the AM provider. The
        information may be about a Link Type in a different domain (i.e. Dublin
        Core Terms or OWL). The main use of an LTR is for clients who want to
        build a UI for users that clearly labels potential link types.</dd>
The definition of a Service Provider was removed from this section but is still used throughout the document.  If keeping the document content, should add that definition back in here.
Base Requirements
Are these two statements inconsistent?
<li>AM Servers MUST support XML representations with media-type <code>application/xml</code>.
OSLC AM Servers SHOULD support HTTP GET requests on Architecture Management Resources (AMR), with an Accept header of an HTML type
Simple Semantic suggestion (multiple places) (ref https://www.quora.com/A-http-or-an-http-which-is-the-correct-grammatical-usage)
<p>An OSLC AM server MAY support the <code>oslc.properties</code> URL query parameter on an HTTP
  GET request on individual resource
I believe this section is repeated.  This part looks like a copy and paste from RM which should have been removed.  A same-name AM specific section already exists just before this.
<section id="updatingMultiValueProps">
<h4>Updating Multi-Valued Properties</h4
<p>For multi-valued properties that contain a large number of values, it may be difficult and inefficient to add or remove property values. OSLC RM servers MAY provide support for a partial update of the multi-valued properties as defined by draft specification [[LDPPatch]]. RM servers MAY also support partial updates through HTTP PUT where only the updated properties are included in the entity request body.</p>
Update Required (see markup below).  Also, should the last reference here instead be to the Architecture Management Vocab document instead?  Alternatively, since a reference exists to the Vocabulary document in the Conformance section anyway, perhaps do not even need this section here.
<section id="ResourceDefs">
<h2>Vocabulary Terms and Constraints</h2>
  <p><a href="" Architecture Management Resources 2.1</a>
    Defines the vocabulary terms and constraints for OSLC Change Management Architecture Management resources.
    These terms and constraints are specified according to [[!OSLCCore3]].</p>
AM Server Capabilities
Simple semantic markup (remove s to be consistent with other text)
<h3>Resource Shapes</h3>
  <p>OSLC AM services providers SHOULD support Resource Shapes as defined in [[!OSLCShapes]].</p>
Minor markups (add two characters)
<p>OSLC AM Servers MUST provide an <code>oslc:serviceProvider</code> property for their defined resources that will be the URI to a <a href="" href="http://open-services.net/bin/view/Main/OslcCoreSpecification#Service_Provider_Resources">http://open-services.net/bin/view/Main/OslcCoreSpecification#Service_Provider_Resources">Service Provider Resource</a>. This does not prevent AM Servers from providing multiple service provider properties with different values
This sounds wrong (is this so that a client can confirm that what was accepted is what he required?)
so clients will be able to confirm if required what was accepted.</p>
Would this sound better and be more accurate?
If supported then AM Servers MUST support a simple GET without any simple query parameters that returns all link type resources.
Suggested change
<p>OSLC AM Servers SHOULD support the selection of resources by delegated web-based user interface delegated selection dialogs as defined by [[!OSLCCore3]].</p>
<p>OSLC AM Servers MAY support the creation of resources by delegated web-based user interface delegated creation dialogs as defined by [[!OSLCCore3]].</p>
Expected for the size values are defined by <a href="" href="http://www.w3.org/TR/CSS1/#length-units">http://www.w3.org/TR/CSS1/#length-units">CSS length units</a>.</p
Minor additions/markups
<p>The following table summarizes the requirements from OSLC Core Specification
as well as some additional requirements specific to the AM domain. Note that
this specification further restricts some of the requirements for the OSLC Core
Specification. See the previous sections in this specification or the
OSLC Core Specification to get further details on each of these
<td>If AM Servers support update and delete of resources they MUST support the standard HTTP If-Match header in PUT and DELETE for concurrency protection of resources.</td>
<td>AM Servers MAY provide paging of HTTP entity response bodies, but only when specifically requested by a client</td>
<td>AmM (small m needs to be Big M here) Servers MAY support requests for a subset of a resource's properties via the oslc.properties URL parameter retrieval via HTTP GET</td>
Several places in the Conformance table include items that should be offset as <code></code> such as instances of oslc:properties
Should the reference to CORE below be a hyperlink?
<td>AM Servers MAY provide a Service Provider Catalog, MUST provide a Service Provider resource, and MAY provide other forms of discovery described in Core 3.0 Discovery.</td>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]