[CMIS 1.1 Draft Review] CMIS 1.1 Working Draft 01b: browser binding comments

[Scott Malabarba <scott.malabarba@us.ibm.com>]

I'd like to add the browser binding authentication
and authorization sections to the agenda for one of the next meetings.
Florian's solution and writeup are excellent.
But's it's (necessarily) complex -- I'd like to get a sanity check from
the TC on
cost to implement.

Spec comments below.

Regards,
Scott


Suggested edits denoted with [].



2.1.4

Query-able Can be located via the
Discovery Services (for exmape[typo]: query).


5.1 

but is not restricted to those[them].


browser applications;[,] it can also
as a simpler [simpler than what?]
HTTP based binding in other application
models.


5.2.3

  suggest:

This specification provides a formal
definition of the CMIS JSON
elements. The formal definition is short
and precise and allows
implementations to validate CMIS JSON
at runtime.

5.2.4

including Object, String, Number,
Boolean, Null and Arrays[Array].


some explanation of mapping is necessary.
  No explanation follows, just
a table.  Suggest:

Not all types used in the CMIS schema
have direct JSON equivalents.
The following table describes the mapping
between CMIS and JSON types.

Datetime   number    (milliseconds
since 1970/01/01, UTC)[1970/01/01 00:00:00 UTC]


5.2.5

The URL patterns allow objects to
be referenced both by object ID and by path[referenced by either object
ID or path]

5.2.6

Browser applications also[] typically
use HTTP multipart forms

5.2.8

  Suggest stating the problem we
are trying to solve (same-origin policy) first. For example:

Modern browsers restrict a _javascript_
function from making HTTP calls to servers other than
the one on which the function originated.
This set of restrictions is called the 
"same-origin policy" (see
[reference]). A CMIS client web application and the CMIS repositories
it uses may often be deployed to different
servers. This specification allows _javascript_
clients to access repositories on other
servers, within the constraints of the same-origin policy,
by using the JSON with Padding (JSONP)
pattern.


The JSONP (JSON with Padding) pattern
  
  I believe the convention is "JSON
with Padding (JSONP)" for the first reference and "JSONP"
thereafter.

5.2.9

HTTP[S?] over TLS 

5.2.9.1

  It is not clear to me how this
section applies to non-browser clients but not to browser clients.
  The 403 status code would break
any client -- browser or not -- that relies on the basic HTTP auth 
  challenge instead of preemptive
authentication. We should probably discuss this part.

5.2.9.2

  As with 5.2.8, I think we need
to open by stating the problem we are trying to solve:  CSRF protection.
  The section as written is technically
sound but it's not at all clear why the repository implementor 
  should invest in something so
complicated.

  Text aside, I worry that the
complexity will prove to be a barrier to both client and repository implementors.
  We should discuss.

5.3.3

used to build Object URL’s[URLs
(as used in the 5.3.4 heading)]

5.4
  
  default values might be better
in table form

All operations that retrun[return]
the HTTP status code 201 SHOULD also return a HTTP Location

5.4.1.1

  I know you're trying to match
the format of the entries under 5.4.2, but the "" heading looks
odd.
  Suggest removing the 5.4.1.1
heading entirely.
  
5.4.2
  
  I don't understand the formatting
of the "Argument" and "Arguments" fields.

  What is the difference between
"Arguments" ("q") and "Relevant CMIS Controls"
("Query")?


5.4.3.19

  I assume that if the operation
fails the repository may return a JSON object as described in 5.2.10.
  What is the format of the overall
response including the ID list?
  Also assume that an error HTTP
status is returned on failure -- is this correct?

5.4.4

The encoding type (HTML form attribute
"enctype") MUST be either application/x-www-form-urlencoded
or multipart/form-data if no content
stream is attached to the form. The encoding type MUST
be multipart/form-data if a content
stream is attached to the form data.

  These two can seem contradictory
depending on how one parses the first sentence. Suggest:

If a content stream is not attached
to the form, the encoding type MUST be either...
If a content stream is attached, the
encoding type MUST be...

5.4.4.3.7

To unset the property, the propertyValue
control MUST NOT be present.

  Incomplete. Suggest:

To unset the property, the client must
submit form data that contains the propertyId control
and does NOT contain the propertyValue
control.

  Or if we have to use MUST/MUST
NOT:

To unset the property, the client must
submit form data in which the propertyId MUST be present
and the propertyValue control MUST NOT
be present.

5.4.4.3.9

  Opening line is awkward. Suggest:

In order to add an ACE to a CMIS object,
a client passes a control named addACEPrincipal along with
a set of corresponding addACEPermission
controls. An index value addACEIndex links the principal
with its permissions, and a second index
permIndex differentiates the permissions.

5.4.4.3.10

  Same issue as .9.

5.4.4.4

as any other kind of _javascript_[,]
which means that 

number of milliseconds since 1970/01/01,
UTC, [1970/01/01 00:00:00 UTC]

5.4.4.4.2

The use of transaction ids[IDs?]

  Suggest replacing second sentence
with:

It may be preferable to keep the state
entirely on the client using, for example, a cookie.

5.4.4.4.2.1

A simple in-memory store would be
sufficient.

  If and only if the CMIS repository
runs on a single server or has persistent HTTP connections.
  On an enterprise-capable repository
this would not work. Suggest something like:

The repository might store the state
in-memory or in shared session state.


5.4.5.0.2.4


There is no selector provided in
this example, which means it falls back to the default selector for
a folder: [ ]children[.]

5.4.5.0.2.5

Note that the contents of the response
are abbreviated for brevity.

  Why else would you abbreviate
something? ;)