oslc-domains message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [oslc-domains] Comments on OSLC AM Spec 2.1
- From: "Jim Amsden" <jamsden@us.ibm.com>
- To: "Schulte (US), Mark D" <mark.d.schulte@boeing.com>
- Date: Thu, 26 Jul 2018 09:00:12 -0400
Thanks Mark,
I've applied your updates. Some comments
embedded below.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
From:
"Schulte (US),
Mark D" <mark.d.schulte@boeing.com>
To:
"workgroup_mailer@lists.oasis-open.org"
<workgroup_mailer@lists.oasis-open.org>, "oslc-domains@lists.oasis-open.org"
<oslc-domains@lists.oasis-open.org>
Date:
07/20/2018 03:55 PM
Subject:
[oslc-domains]
Comments on OSLC AM Spec 2.1
Sent by:
<oslc-domains@lists.oasis-open.org>
Here are some comments on
the AM Specification
http://htmlpreview.github.com/?https://github.com/oasis-tcs/oslc-domains/blob/master/am/architecture-management-spec.html
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>
</section>
Need a comma added here.
<dt><dfn>Link</dfn></dt>
<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 SHOULDsupport HTTP GET requests on Architecture Management Resources (AMR), with
an Accept header of an HTML type
<jra>These are consistent. The first
says servers must support XML representations of resources. The second
says they should support GET on those resources, and that GET must support
the application/xml media type.</jra>
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 anHTTP
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>
</section>
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>
</section>
AM Server Capabilities
Simple semantic markup (remove s
to be consistent with other text)
<h3>Resource Shapes</h3>
<p>OSLC AM servicesproviders 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="">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 simplequery parameters that returns all link type resources.
Suggested change
<p>OSLC AM Servers SHOULD support
the selection of resources by delegated web-baseduser interface delegated
selection dialogs as defined
by [[!OSLCCore3]].</p>
<p>OSLC AM Servers MAY support
the creation of resources by delegated web-baseduser interface delegated
creation dialogsas defined by [[!OSLCCore3]].</p>
Expected for
the size values are defined
by <a href="">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 theOSLC Core
Specification. See the previous sections
in this specification or the
OSLC Core Specification to get further
details on each of these
requirements.</p>
<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 requestsfor 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]