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

From: mike amundsen <[email-masked]>
Date: Mon, 2 Mar 2015 12:42:17 -0500

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: <[email-masked]>
Date: Mon, Mar 2, 2015 at 12:23 PM
Subject: New Version Notification for
draft-amundsen-richardson-foster-alps-01.txt
To: Mike Amundsen <[email-masked]>, Leonard Richardson <
[email-masked]>, "Mark W. Foster" <[email-masked]>

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

---

From: Graham Klyne <[email-masked]>
Date: Tue, 03 Mar 2015 11:38:30 +0000

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."?

...

Sect 2.2.2: missing {...} around "alps" content?

{ "alps : "doc" : { "value" : "..." }, ... }

(cf. sect 2.3.3.1)

...

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.)

...

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.

...

Section 4.

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

...

HTH

#g
--

On 02/03/2015 17:42, mike amundsen wrote:
> _______________________________________________
> media-types mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/media-types
>

---

From: mike amundsen <[email-masked]>
Date: Tue, 3 Mar 2015 20:01:12 -0500

Graham:

thanks for the review. all good stuff.

comments inline ....

mamund
+1.859.757.1449
skype: mca.amundsen

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

> 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
>

+1

> { "alps : "doc" : { "value" : "..." }, ... }

yep -- good catch

> 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.

> interpretation (sect 2.2.7.2).

yep - again, good catch.

> HTH

yes, it does. thanks.