Re: [media-types] Fwd: New Version Notification for draft-amundsen-richardson-foster-alps-01.txt

[mike amundsen <[e-mail]>]

Graham:

thanks for the review. all good stuff.

comments inline ....



mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

On Tue, Mar 3, 2015 at 6:38 AM, Graham Klyne <[e-mail]> wrote:

> Hi,
>
> Reviewing:
> http://tools.ietf.org/id/draft-amundsen-richardson-foster-alps-01.html
>
> I'm just taking a quick skim here, and offer some immediate comments (I've
> yet to fully grasp the big picture).
>
> ...
>
> Sect 1.4
>
> "This URL SHOULD be assumed to be dereferencable." reads oddly (making a
> normative statement about an assumption?).
>
> Maybe just "This URL SHOULD be dereferencable."?
>

+1

>
> ...
>
> Sect 2.2.2: missing {...} around "alps" content?
>
> { "alps : "doc" : { "value" : "..." }, ... }
>
> (cf. sect 2.3.3.1)
>

yep -- good catch

>
> ...
>
> 2.2.7.3. Link Relation Values and 'id' or 'name'
>
> I see a problem here.  It's all very well to say "If the resulting link
> relation type is the same as a registered relation type, the descriptor
> MUST not change the meaning of the IANA relation type.".
>
> But an implementer cannot know what new relation types will be implemented
> in future.  An application that is conformant at the time of implementation
> may be rendered non-conformant by subsequent IANA registrations.  I think
> this is not consistent with progressing the notion of "software engineering
> on the scale of decades" which I'm guessing is a motivation for this work.
>
> One possible approach might be to require any non-registered value to be a
> URI or URI reference, and introduce a distinguishable prefix for local
> ids.  (e.g. use fragment syntax such as '#idvalue' or a common URN prefix
> such as 'urn:ietf:alps:id:idvalue'.  I'm not suggesting these as specific
> solutions as I don't yet understand enough of the scope of what you're
> proposing, just as examples of alternative approaches to contemplate.)
>
> ...
>

right - our *intent* is to mimic advice from 6906[1]: "A profile MUST NOT
change the semantics of the resource representation when processed without
profile knowledge..." in this case, the intent is to say that an ALPS
document MUST NOT change the semantics of an existing registered Link
Relation Value." Also, using 5988-style URIs for non-reg'd values is a good
one. We're totally on board for that.

So that challenge here is to properly convey the idea that reg'd values
MUST NOT be redefined. this certainly works "at the scale of decades",
right?

[1] https://tools.ietf.org/html/rfc6906#section-3



> Section 2.2.12
>
> I'm not understanding what you mean by the description of
> type="semantic".  The examples given (html.span and html.input) aren't
> helping in this respect.
>
> My guess is that some kind of introduction to the kind of hypermedia model
> your basing this upon is needed.  I think there's a lot of tacit knowledge
> permeating the spec that needs to be surfaced for those who aren't in tune
> with your approach.
>
>
good observation. we need some expository material maybe. in ALPS
documents, descriptors can describe actions (type="safe", "idempotent", or
"unsafe") or descriptors can describe state values (type="semantic"). the
idea here is make it clear that both actions and data elements are
described in an ALPS document and it it clear which is which.

I'll work up some content that addresses this in the Motivation section.


> ...
>
> Section 4.
>
> I think the media type registrations should reference the fragment id
> interpretation (sect 2.2.7.2).
>

yep - again, good catch.


>
> ...
>
> HTH
>

yes, it does. thanks.


>
> #g
> --
>
>
>
>
> On 02/03/2015 17:42, mike amundsen wrote:
>
>> The updated I-D for ALPS was just posted it to the IETF tracker (see
>> details below). I've also updated the web site[0] .
>>
>> We're looking for any/all comments and feedback. Feel free to discuss on
>> the ALPS list[1] or here, and to open/update issues in github[2] for the
>> next round of changes.
>>
>> -- cheers.
>>
>> [0]  http://alps.io/spec/index.html
>> [1] https://groups.google.com/forum/?fromgroups=#!forum/alps-io
>> [2] https://github.com/alps-io/spec/issues
>>
>>
>> mamund
>> +1.859.757.1449
>> skype: mca.amundsen
>> http://amundsen.com/blog/
>> http://twitter.com/mamund
>> https://github.com/mamund
>> http://linkedin.com/in/mamund
>>
>>
>>
>> ---------- Forwarded message ----------
>> From: <[e-mail]>
>> Date: Mon, Mar 2, 2015 at 12:23 PM
>> Subject: New Version Notification for
>> draft-amundsen-richardson-foster-alps-01.txt
>> To: Mike Amundsen <[e-mail]>, Leonard Richardson <
>> [e-mail]>, "Mark W. Foster" <[e-mail]>
>>
>>
>>
>> A new version of I-D, draft-amundsen-richardson-foster-alps-01.txt
>> has been successfully submitted by Mike Amundsen and posted to the
>> IETF repository.
>>
>> Name:           draft-amundsen-richardson-foster-alps
>> Revision:       01
>> Title:          Application-Level Profile Semantics (ALPS)
>> Document date:  2015-02-28
>> Group:          Individual Submission
>> Pages:          27
>> URL:
>> http://www.ietf.org/internet-drafts/draft-amundsen-
>> richardson-foster-alps-01.txt
>> Status:
>> https://datatracker.ietf.org/doc/draft-amundsen-richardson-foster-alps/
>> Htmlized:
>> http://tools.ietf.org/html/draft-amundsen-richardson-foster-alps-01
>> Diff:
>> http://www.ietf.org/rfcdiff?url2=draft-amundsen-richardson-foster-alps-01
>>
>> Abstract:
>>     This document describes ALPS, a data format for defining simple
>>     descriptions of application-level semantics, similar in complexity to
>>     HTML microformats.  An ALPS document can be used as a profile to
>>     explain the application semantics of a document with an application-
>>     agnostic media type (such as HTML, HAL, Collection+JSON, Siren,
>>     etc.).  This increases the reusability of profile documents across
>>     media types.
>>
>> Editorial Note (To be removed by RFC Editor)
>>
>>     Distribution of this document is unlimited.  Comments should be sent
>>     to the IETF Media-Types mailing list (see [1]).
>>
>>
>>
>>
>> Please note that it may take a couple of minutes from the time of
>> submission
>> until the htmlized version and diff are available at tools.ietf.org.
>>
>> The IETF Secretariat
>>
>>
>>
>> _______________________________________________
>> media-types mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/media-types
>>
>>
> _______________________________________________
> media-types mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/media-types
>