Difference: SampRfcDiscussionV11 (1 vs. 44)

Revision 442012-06-26 - root

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

I approve this document. MatthewGraham

Resource Registry

I approve the document (nice work) RayPlante

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

I approve the final document. HerveWozniak

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


Revision 432009-03-11 - MatthewGraham

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Added:
>
>
I approve this document. MatthewGraham
 

Resource Registry

I approve the document (nice work) RayPlante

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

I approve the final document. HerveWozniak

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 422009-03-06 - RayPlante

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Added:
>
>
I approve the document (nice work) RayPlante
 

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

I approve the final document. HerveWozniak

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 412009-03-03 - PedroOsuna

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

Changed:
<
<
[Approval in the RFC period]
>
>
Added:
>
>
I approve the document. PedroOsuna.
 

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

I approve the document. MasatoshiOhishi

Theory

I approve the final document. HerveWozniak

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 402009-02-24 - MasatoshiOhishi

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Added:
>
>
I approve the document. MasatoshiOhishi
 

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

Added:
>
>
I approve the document. MasatoshiOhishi
 

Theory

I approve the final document. HerveWozniak

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 392009-02-20 - HerveWozniak

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

I aprove the document. FrancoisOchsenbein

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

Theory

Changed:
<
<
[Approval in the RFC period]
>
>
I approve the final document. HerveWozniak
 

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 382009-02-20 - FrancoisOchsenbein

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

I approve this document. KeithNoddle

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

Changed:
<
<
[Approval in the RFC period]
>
>
I aprove the document. FrancoisOchsenbein
 

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 372009-02-20 - KeithNoddle

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Added:
>
>
I approve this document. KeithNoddle
 

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

I approve the SAMP final draft document. Good job, all! -- SebastienDerriere

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 362009-02-19 - SebastienDerriere

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

Added:
>
>
I approve the SAMP final draft document. Good job, all! -- SebastienDerriere
 

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

AOK. BobHanisch.

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 352009-02-19 - BobHanisch

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

Added:
>
>
AOK. BobHanisch.
 

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 342009-02-19 - TomMcGlynn

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

I approve the document. KeithNoddle

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Changed:
<
<
Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.
>
>
Note that the space for RFC comments from the working groups was intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.
 

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 332009-02-19 - KeithNoddle

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Added:
>
>
I approve the document. KeithNoddle
 

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.

I approve the document. ChristopheArviset


<--  
-->

Revision 322009-02-19 - ChristopheArviset

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.] I approve the final draft document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

Changed:
<
<
[Approval in the RFC period]
>
>
I thank the authors for their changes after the RFC period and I acknowledge the creation of the www.ivoa.net/samp page.
Added:
>
>
I approve the document. ChristopheArviset
 
<--  
-->

Revision 312009-02-19 - MireilleLouys

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.]
Added:
>
>
I approve the final draft document. MireilleLouys
 

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

[Approval in the RFC period]


<--  
-->

Revision 302009-02-18 - MarkTaylor

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

Changed:
<
<
From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Integer Group chair or representative should approve the document in the TCG review section at the bottom of the document.
>
>
From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Interest Group chair or representative should approve the document in the TCG review section at the bottom of the document.
 

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.]

Grid & Web Services

Resource Registry

Semantics

VO Event

I still approve (and approve of) the document. -- RobSeaman

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

[Approval in the RFC period]


<--  
-->

Revision 292009-02-18 - RobSeaman

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Integer Group chair or representative should approve the document in the TCG review section at the bottom of the document.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


RFC period comments from Working and Interest Groups

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.]

Grid & Web Services

Resource Registry

Semantics

Changed:
<
<

VO Event

>
>

VO Event

Added:
>
>
I still approve (and approve of) the document. -- RobSeaman
 

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

[Approval in the RFC period]


<--  
-->

Revision 282009-02-18 - TomMcGlynn

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.

Changed:
<
<
We would appreciate it if chairs of the working and interest groups who have not yet reviewed the document could indicate their assent to the proposal or their concerns with it.
>
>
From February 16, 2009 through March 10, 2009 the SAMP document shall be reviewed by the members of the TCG. Each Working and Integer Group chair or representative should approve the document in the TCG review section at the bottom of the document.
 
Deleted:
<
<
The recommendation is to be reviewed by the TCG and the executive committee before final promotion to recommendation.


 

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


Changed:
<
<

Comments from Working and Interest Groups:

>
>

RFC period comments from Working and Interest Groups

 

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset

Added:
>
>


TCG Review: Working and Interest Groups

Note that the space for RFC comments from the working groups were intended to spur early review of the document. A formal approval is still requested from each of the WG and IG heads. I [TAM] have noted cases where the RFC comments seemed to indicate an approval in the RFC period but the appropriate chairs should review this final draft.

Applications

I approve this document. TomMcGlynn

Data Access Layer

Data Modeling

[Approval in the RFC period.]

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

[Approval in the RFC period]

VOTable

[Approval in the RFC period]

Data Curation & Preservation

OGF Astro-RG

Theory

[Approval in the RFC period]

TCG

[Approval in the RFC period]
 
<--  
-->

Revision 272009-02-13 - TomMcGlynn

 
META TOPICPARENT name="SampInfo"

RFC Discussion

Changed:
<
<
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampInfo page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.
>
>
This page has been used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and reponses are included below. In response to the comments during the RFC an updated version, 1.11, has been delivered to the IVOA document repository.
 
Changed:
<
<
Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.
>
>
We would appreciate it if chairs of the working and interest groups who have not yet reviewed the document could indicate their assent to the proposal or their concerns with it.
Added:
>
>
The recommendation is to be reviewed by the TCG and the executive committee before final promotion to recommendation.
 

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
  • http://www.ivoa.net/samp/ is now in place -- MarkTaylor - 09 Feb 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 262009-02-09 - MarkTaylor

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampInfo page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
Added:
>
>
 

Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

I approve the document. MireilleLouys

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 252009-02-08 - MireilleLouys

 
META TOPICPARENT name="SampInfo"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampInfo page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Added:
>
>
I approve the document. MireilleLouys
 

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 242009-02-03 - MarkTaylor

Changed:
<
<
META TOPICPARENT name="SampProgress"
>
>
META TOPICPARENT name="SampInfo"
 

RFC Discussion

Changed:
<
<
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.
>
>
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampInfo page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.
  Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 232009-01-28 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

Changed:
<
<
  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009
>
>
  • Following discussion with the reviewers, on apps-samp and with the TCG, we plan to address this issue by modifying section 5.3 so that instead of providing an outline procedure for extending the MType list, it directs readers to a fixed URL, hopefully http://www.ivoa.net/samp/ . This URL will contain concrete details of the current MType list(s) as well as concrete details about how developers should go about extending it, perhaps along with other useful information. In the first instance this URL will probably redirect to an IVOA internal wiki page, but the possibility exists that it may one day point at less wiki-like content hosted somewhere or other. We are currently investigating the mechanics of getting this URL working. Assuming this can be done, Jesus, as well as Christophe and Bob who made similar comments, have agreed by email that it addresses their concerns. -- MarkTaylor - 28 Jan 2009
 

Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 222009-01-20 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

Added:
>
>
 
  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
Changed:
<
<
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119.
>
>
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119. Where they are not now capitalised, and where "can" is used, the modality is not in the RFC 2119 sense of adherence to the protocol.
 
  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
Changed:
<
<
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?
>
>
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use throughout the document as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better? If you still find this dicussion confusing, an alternative would be to remove this section, which has no normative content.
 
  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
Changed:
<
<
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).
>
>
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked near here are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).
 
  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.
Added:
>
>
 
  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
Added:
>
>
    • SHOULD was my intention. For instance a hub might decide not to pass on all metadata declarations if a flood is received over a short interval - won't usually be the case, but I believe it should be an implementation decision. But we can reconsider this if any SAMP authors/contributors disagree.
 
Deleted:
<
<
Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009
 

Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 212009-01-20 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
Added:
>
>
    • Some of these addressed as detailed below. Otherwise I've been through the text and capitalised these terms where they are used in the sense of RFC 2119.
 
  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.
Added:
>
>
    • "may not" changed to "MUST NOT" in that case. The other "may"s you have marked are "May only be invoked by a Callable Client" . It doesn't make sense to replace May by MUST in these cases (the client is not under obligation to invoke these operations), so I have reworded: "An error results if the invoking client is not Callable" (though I'm dubious that this improves clarity).
 
  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
Changed:
<
<
    • I don't share your confusion here; operations the hub invokes are discussed because invocation by the hub is the context in which these operations must be supported. I've reworded the first paragraph avoiding the word "may" as follows: "This section lists the operations which the hub uses when it wishes to pass information to a callable client. Note that callability is optional for clients; special (Profile-dependent) steps may be required for a client to inform the hub how it can be contacted, and thus become callable. Clients which are not callable can send messages using the Notify or Synchronous Call/Response patterns, but are unable to receive messages or to use Asynchronous Call/Response, since these operations rely on client callbacks from the hub." If you still find this confusing, could you explain which parts you don't like or suggest alternative wording?
>
>
    • I've replaced the first sentence with the following: "This section lists the operations which a client MUST support in order to be classified as callable. The hub uses these operations when it wishes to pass information to a callable client."
 
  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
    • Changed to MUST NOT .

  • Section 4.2, it is not clear if these are musts or shoulds.
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 202009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I don't share your confusion here; operations the hub invokes are discussed because invocation by the hub is the context in which these operations must be supported. I've reworded the first paragraph avoiding the word "may" as follows: "This section lists the operations which the hub uses when it wishes to pass information to a callable client. Note that callability is optional for clients; special (Profile-dependent) steps may be required for a client to inform the hub how it can be contacted, and thus become callable. Clients which are not callable can send messages using the Notify or Synchronous Call/Response patterns, but are unable to receive messages or to use Asynchronous Call/Response, since these operations rely on client callbacks from the hub." If you still find this confusing, could you explain which parts you don't like or suggest alternative wording?

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?
Added:
>
>
    • Changed to MUST NOT .
 
  • Section 4.2, it is not clear if these are musts or shoulds.
Added:
>
>
    • Since it's discussing an API, I don't think there is much ambiguity. However, I have added a MUST at the start of the section.
 
  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 192009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
Added:
>
>
    • The thinking was that this is one way to encode the abstract message object (one might think of others), and the references to this section from sections 3.11 and 3.12 are what require that this particular encoding is used for the purposes of the SAMP API. However, I've now clarified this in 3.8 by writing instead: "A message is encoded for SAMP transmission as a map with the following REQUIRED keys" , and made a similar alteration in sec 3.9.
 
  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
    • I don't share your confusion here; operations the hub invokes are discussed because invocation by the hub is the context in which these operations must be supported. I've reworded the first paragraph avoiding the word "may" as follows: "This section lists the operations which the hub uses when it wishes to pass information to a callable client. Note that callability is optional for clients; special (Profile-dependent) steps may be required for a client to inform the hub how it can be contacted, and thus become callable. Clients which are not callable can send messages using the Notify or Synchronous Call/Response patterns, but are unable to receive messages or to use Asynchronous Call/Response, since these operations rely on client callbacks from the hub." If you still find this confusing, could you explain which parts you don't like or suggest alternative wording?

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 182009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.
Added:
>
>
    • I don't share your confusion here; operations the hub invokes are discussed because invocation by the hub is the context in which these operations must be supported. I've reworded the first paragraph avoiding the word "may" as follows: "This section lists the operations which the hub uses when it wishes to pass information to a callable client. Note that callability is optional for clients; special (Profile-dependent) steps may be required for a client to inform the hub how it can be contacted, and thus become callable. Clients which are not callable can send messages using the Notify or Synchronous Call/Response patterns, but are unable to receive messages or to use Asynchronous Call/Response, since these operations rely on client callbacks from the hub." If you still find this confusing, could you explain which parts you don't like or suggest alternative wording?
 
  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 172009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
    • These comments boil down to American/English English distinctions. Discussed in private emails.

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
Added:
>
>
    • This section is, by way of supplying context, discussing some messaging models which are related to what SAMP does, but SAMP does not exactly match any of the four models discussed here. Although the notion of "subscription" is one which we do use as part of the description of how SAMP works, the notion of "publication" is not (partly because SAMP permits sends directed to a single recipient as well as ones directed to all subscribed recipients, and this does not seem to be well captured by the terminology of publication). So: no, "publish" is not to be considered a synonym of "send" here. I have reworded this paragraph, though not the rest of the text, slightly as follows, avoiding use of the word "send": "A publish/subscribe (pub/sub) messaging system supports an event driven model where information producers and consumers participate in message passing. SAMP applications ``publish'' a message, while consumer applications ``subscribe'' to messages of interest and consume events. The underlying messaging system routes messages from producers to consumers based on the message types in which an application has registered an interest." Is this any better?
 
  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.
    • Since these operations do not return values, I have removed this sentence.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
    • Reference added.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 162009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
Added:
>
>
    • These comments boil down to American/English English distinctions. Discussed in private emails.
 
  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
Added:
>
>
    • Definition reworded: " string --- a scalar value consisting of a sequence of characters; each character is an ASCII character with hex code 09, 0a, 0d or 20-7f"
 
  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.
Added:
>
>
    • This wasn't intended to be a well-defined restriction, more of a fuzzy indication of what could be expected. However, I've replaced it by the following more specific text: "Of these operations, only callAndWait() involves blocking communication with another client. The others SHOULD be implemented in such a way that clients can expect them to complete, and where appropriate return a value, on a timescale short compared to user response time."
 
  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.
Added:
>
>
    • Since these operations do not return values, I have removed this sentence.
 
  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.
Added:
>
>
    • Reference added.
 
  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 152009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009


Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 142009-01-19 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

Changed:
<
<
  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009
>
>
  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. "Detailed markup" received with thanks - more responses to come. -- MarkTaylor - 19 Jan 2009
 
Added:
>
>

 

Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.
Changed:
<
<
In fact, because of the already existing well-written client and hub
>
>
  • In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.
Deleted:
<
<
packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.
 
Changed:
<
<
In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A
>
>
  • In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

Response:

  • A similar comment has been made above by Bob and below by Christophe. We will discuss the best way to address this (on the apps-samp list, for those interested) and provide a response shortly. -- MarkTaylor - 19 Jan 2009
Deleted:
<
<
possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.
 

Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 132009-01-16 - JesusSalgado

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009
Added:
>
>

Comments from JesusSalgado

  • The document is clear from the technical point of view. However, to be fully useful for external developers, the note/document where current MTypes are listed must be provided.

In fact, because of the already existing well-written client and hub packages provided to the community, the SAMP architecture is quite transparent to the client developer and the tricky part of SAMP is now the implementation of the relevant messages per application, so the MTypes list and description is, at least, as important as the SAMP general design and it complements it.

In the document (section 5.3), it is mentioned that these MTypes could appear in an IVOA Note (instead of a document) to avoid administrative overhead. However, the UCD controller vocabulary (a similar document) is a formal document, so a more formal approach is still feasible. A possible intermediate solution could be a formal document with the already accepted messages and a working list of new MTypes waiting to be formally approved in note or web format.

 

Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

I approve the document. PedroOsuna.

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 122009-01-16 - PedroOsuna

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

Added:
>
>
I approve the document. PedroOsuna.
 

VOTable

PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 112009-01-16 - FrancoisOchsenbein

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

VO Query Language

VOTable

Added:
>
>
PLASTIC proved to be a basic interoperability component in VO; and the SAMP document adds the possibility of understanding the underlied protocol. Well written in comprehensive terms.

I approve the document. FrancoisOchsenbein

 

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 102009-01-16 - RobSeaman

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

Added:
>
>
The IVOA might consider standardizing nomenclature for pubsub. VOEvent has brokers. SAMP has hubs. Defining a hub as a broker for routing seems a bit redundant. I guess a hub would be a broker that never talks to another broker?

A solid draft - complete and self-consistent. That's a "yea" (even a "yay!") from us. RobSeaman

 

VO Query Language

VOTable

Deleted:
<
<
 

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Approved from TIG. HerveWozniak

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 92009-01-16 - HerveWozniak

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

No additional comments from DCP. BobHanisch

OGF Astro-RG

Theory

Added:
>
>
Approved from TIG. HerveWozniak
 

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 82009-01-15 - BobHanisch

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

Added:
>
>
No additional comments from DCP. BobHanisch
 

OGF Astro-RG

Theory

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset


<--  
-->

Revision 72009-01-07 - ChristopheArviset

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

OGF Astro-RG

Theory

Added:
>
>

TCG

The document is well written, with clear reference and examples for implementation. Taking into account the already wide acceptance of PLASTIC, Annex A is particularly useful.

In section 5.3 MTypes Vocabulary, should we directly define the NOTE of web page where the list of (existing and increasing) "samp" MTypes would reside ?

I approve the document. ChristopheArviset

 
<--  
-->

Revision 62009-01-06 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

Changed:
<
<
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.
>
>
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page. Since the document is in a public source code repository, interested viewers will be able to see the changes which are made as a consequence of these comments - see SampDoc for details.
  Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.

Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009


Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

OGF Astro-RG

Theory


<--  
-->

Revision 52009-01-05 - TomMcGlynn

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Comments from BobHanisch

  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

Response:

  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009
Added:
>
>

 
Added:
>
>

Comments from Working and Interest Groups:

Applications

This draft reflects the consensus of the Working Group. There are, as far as I know, no substantive controversies. TomMcGlynn

Data Access Layer

Data Modeling

Grid & Web Services

Resource Registry

Semantics

VO Event

VO Query Language

VOTable

Data Curation & Preservation

OGF Astro-RG

Theory

 
<--  
-->

Revision 42009-01-05 - MarkTaylor

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Changed:
<
<
>
>

Comments from BobHanisch

 
  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .

  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.

  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?

  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.

  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?

  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.
Changed:
<
<
>
>
Response:
Added:
>
>
  • Bob, thank you for your careful reading. Some of your comments I agree with, and some I'm still thinking about. I will make a proper response shortly. In the meantime, I would be grateful to receive your "detailed mark-up". -- MarkTaylor - 05 Jan 2009
 


<--  
-->

Revision 32008-12-05 - BobHanisch

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:

Added:
>
>
 
Added:
>
>
  • Most of my comments on this document are editorial in nature – proper use of which and that, punctuation, and so on. I will be happy to share a detailed mark-up with the editors. To first order, almost all uses of “which” are incorrect and need to be replaced with “that”. I strongly prefer the Oxford comma (apples, bananas, and oranges), which is the standard for the astronomical literature in the US, but I know that in some countries and in newspapers this is not used. Wikipedia has a nice discourse on this: http://en.wikipedia.org/wiki/Serial_comma .
 
Added:
>
>
  • A general concern, though, is that it is not clear when the document is using the special words “must”, “should”, “may”, etc., in accord with RFC 2119 and when it is not. Sometimes the words appear in all-caps, but usually they do not. Sometimes the word “can” is used and it is ambiguous whether this means may, should, or must. And sometimes “should” it used when it seems like it really is a must. I note a few particular problems below, and others are in my more detailed mark-up.
 
Added:
>
>
  • Section 1.3 introduces the term “publish”, but then it is almost immediately abandoned and replaced by “send”. Are these synonyms, or am I misunderstanding the intent?
 
Added:
>
>
  • In Section 3.3, the string data type is described as a sequence of characters, with the examples being ASCII hex codes, it would appear. But this is not explicit and needs to be.
 
Added:
>
>
  • In 3.8 there is an example of the use of “can”: “The message can be encoded as a map with the following REQUIRED keys... “ I am not sure what the developer is supposed to make of this. If the keys are REQUIRED, isn’t this a “must”?
 
Added:
>
>
  • In 3.11, p. 22, 2nd bullet, there is another example: “mtype may not include wildcards.” It seems that “must” is the correct verb. There are several more “may”s in subsequent bullets that need to be clarified.

  • On p.23, just above 3.12, it says “...should complete...quickly.” What is “quickly”? There needs to be some point of reference, like in less time than something else, or so as not to block some other operation, or something similar.

  • In 3.12, p. 22, the section is called “Operations a Callable Client Must Support”, but immediately we see “may” language and a description of operations that the hub invokes. I find this to be confusing.

  • On p. 24, there is another “...should complete quickly” with no context.

  • 3.13, p. 24, ends with “... it is not to be used by the hub to signal a failed call.” Must not? Should not?

  • Section 4.2, it is not clear if these are musts or shoulds.

  • Section 5, p. 31, the term UCD needs to be defined and referenced.

  • Section 5.3, p. 33, the first paragraph is informal and not specific. Make a decision about how and where to document MTypes and describe it here clearly.

  • Section 5.4.1, all messages are described as “should”, but they seem like “must”.

 


<--  
-->

Revision 22008-12-01 - TomMcGlynn

 
META TOPICPARENT name="SampProgress"
Deleted:
<
<
 

RFC Discussion

Changed:
<
<
This page will be used to encapsulate the discussion of the SAMP RFC from December 9, 2008 through Januar 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.
>
>
This page will be used to encapsulate the discussion of the SAMP RFC from December 8, 2008 through January 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.
  Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.

Comments:


<--  
-->

Revision 12008-12-01 - TomMcGlynn

 
META TOPICPARENT name="SampProgress"

RFC Discussion

This page will be used to encapsulate the discussion of the SAMP RFC from December 9, 2008 through Januar 16, 2009. Comments and responses will be included below. The SAMP protocol and its implementations are described in the documents linked to the SampProgress page.

Please add your comments here directly, or send mail to either the general Applications or specific SAMP mailing lists.


Comments:


<--  
-->
 
This site is powered by the TWiki collaboration platform Powered by Perl This site is powered by the TWiki collaboration platformCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback