Author: zurawski Date: 2010-05-27 09:31:27 -0500 (Thu, 27 May 2010) New Revision: 22 Modified: introduction.tex messages.tex motivation.tex nmc-base.pdf nmc-base.tex Log: Taking a crack at the long-standing project to fix the RFC 2119 words. Only got through section 4 so far. Changed some language as I examined each use (strenghening or weakening the tone). -jason Modified: introduction.tex =================================================================== --- introduction.tex 2010-04-07 13:31:48 UTC (rev 21) +++ introduction.tex 2010-05-27 14:31:27 UTC (rev 22) @@ -5,7 +5,7 @@ % Comment Freek Dijkstra: % Accuracy of last sentence above must be checked (does this specification really define these sets of independent functions?). If false, remove the sentence. -In this model, all services \textbf{SHOULD} communicate using well-defined protocols. While this recommendation does not formally specify these details, it is envisioned that implementations of the proposed architecture \textbf{SHOULD} make this functionality available via \textit{Web Services} (WS). Existing implementation either use SOAP over HTTP or RESTful webservices, but no requirement is given in this document for a particular transport protocol. +In this model, all services must communicate using well-defined protocols. While this document does not formally specify these details, it is envisioned that implementations of the proposed architecture shall make this functionality available via \textit{Web Services} (WS). Existing implementation either use SOAP over HTTP or RESTful webservices, but no requirement is given in this document for a particular transport protocol. The work presented here builds upon the output of other working groups focused on the accurate description of network measurements \cite{nmwg} and topological representation of network elements \cite{nmlwg}. When applicable, we will directly cite terminology and ideas from these working groups. We do not describe a particular system currently in use, although several prototypes exist that implement messaging similar to this work. Modified: messages.tex =================================================================== --- messages.tex 2010-04-07 13:31:48 UTC (rev 21) +++ messages.tex 2010-05-27 14:31:27 UTC (rev 22) @@ -45,10 +45,10 @@ There are some important things to note about this query: \begin{itemize} -\item \textbf{Message Type} - Every \textit{message} \textbf{MUST} contain a \textit{type}, these facilitate the semantic intentions of the internal data -\item \textbf{Message Structure} - There \textbf{MAY} be \textit{metadata} and/or \textit{data} elements in each message, and there \textbf{MAY NOT} need to be a matching data for every metadata (e.g. \textit{Chaining}, see Section~\ref{s:information_chaining}) -\item \textbf{Metadata} - \textbf{SHOULD} contain measurement data, identifying information about a service, or even information meant to serve as a modifier (see see Section~\ref{s:information_chaining}). Note that we still loosely observe the static rule of thumb -\item \textbf{Data} - Serves a dual role: in request messages this \textbf{MAY} be empty (e.g. this is a \textit{data trigger}, it lets the service know we need action on the accompanying metadata), or it \textbf{MAY} contain dynamic measurement data or even other metadata elements +\item \textbf{Message Type} - Every \textit{message} must contain a \textit{type}, these facilitate the semantic intentions of the internal data +\item \textbf{Message Structure} - There must be \textit{metadata} and/or \textit{data} elements in each message; there does not need to be a matching data for every metadata (e.g. \textit{Chaining}, see Section~\ref{s:information_chaining}) +\item \textbf{Metadata} - Must contain measurement data, identifying information about a service, or even information meant to serve as a modifier (see see Section~\ref{s:information_chaining}). Note that we still loosely observe the static rule of thumb +\item \textbf{Data} - Serves a dual role: in request messages this may be empty (e.g. this is a \textit{data trigger}. An empty data element lets the service know we need action on the accompanying metadata), or it may contain dynamic measurement data or even other metadata elements \end{itemize} % XXX jz - 1/27/2010 @@ -63,11 +63,11 @@ % % The above text should be altered to address this. -Simply stated, we are sending a request (either partial or complete) to a capable service to perform some interactive behavior. We are interested in having the service verify that it \textbf{MAY} or \textbf{MAY NOT} be able to service our request. We are interested in either setting or retrieving information on this target data set - subsequent operations may be required. When the service receives this request it will check for several things: +Simply stated, we are sending a request (either partial or complete) to a capable service to perform some interactive behavior. We are interested in having the service verify that it is able to service our request, either by acting in a positive or negative manner. We are interested in either setting or retrieving information on this target data set - subsequent operations may be necessary. When the service receives this request it will check for several things: \begin{itemize} \item \textbf{Syntax} - Does the request parse correctly? Incorrect syntax will trigger \textit{error routines}. -\item \textbf{Message Type} - Can this service accept and act on this kind of message? An unexpected message \textbf{MUST} be rejected outright by discarding it and responding with a corresponding error message. +\item \textbf{Message Type} - Can this service accept and act on this kind of message? An unexpected message must be rejected outright by discarding it and responding with a corresponding error message. \item \textbf{Structure} - Is there at least a single metadata and data pair that is capable of being acted on? A service that cannot determine if there is actionable content in the request will \textit{discard} the message with an \textit{error routine}. \item \textbf{Semantics} - Does the request make sense according to the schematic rules; can the metadata be acted upon; are the chains resolved properly? Handling of semantic rules are the discretion of the service: \textit{error routines} are possible or perhaps some form of \textit{panic parsing} may result in partial completion of a request. \end{itemize} @@ -93,18 +93,18 @@ Note this message is similar to the request in many ways. The major differences: \begin{itemize} -\item \textbf{Message Type} - This becomes the foil of the previous request; it is common to simply replace the word ``Request'' with ``Response''. -\item \textbf{Message Structure} - All valid metadata and data pairings \textbf{MUST} be acted on, chained items \textbf{MAY} be truncated -\item \textbf{Metadata} - \textbf{MAY} be completed if it was not this way in the request -\item \textbf{Data} - \textbf{MUST} contain information, especially if it was empty in the initial request +\item \textbf{Message Type} - This becomes the foil of the previous request; it is common to simply replace the word ``Request'' with ``Response'' +\item \textbf{Message Structure} - All valid metadata and data pairings must be acted on, chained items may be truncated +\item \textbf{Metadata} - May be ``completed'' (e.g. augmented information added to the original) if it was incomplete in the initial request +\item \textbf{Data} - Must contain information, especially if it was empty in the initial request \end{itemize} The second situation is not very different, but is indicative of something occurring that was not expected. We don't explicitly use the term ``error'' to describe this situation because many paths that lead to this are not \textit{wrong}. Some examples of status may be: \begin{itemize} -\item \textbf{Message Syntax/Structure/Semantics} - The service \textbf{MUST} be able to understand the request, if it cannot be parsed on either the syntactic or semantic levels the status \textbf{SHOULD} reflect this. -\item \textbf{Metadata/Data Search} - The backend storage \textbf{MAY} simply be devoid of references to what a request is interested in, this \textbf{MAY} be expressed by returning nothing in the response or having an explicit message to do so. -\item \textbf{Catastrophic Events} - Internal events \textbf{MAY} trigger some sort of panic in the service; note that not all events \textbf{MAY} be recovered from and are not the fault of the service itself (host machine failures, etc.). +\item \textbf{Message Syntax/Structure/Semantics} - The service must be able to understand the request, if it cannot be parsed on either the syntactic or semantic levels the status must reflect this. +\item \textbf{Metadata/Data Search} - The backend storage may simply be devoid of references to what a request is interested in, this should be expressed by returning nothing in the response or having an explicit message to do so. +\item \textbf{Catastrophic Events} - Internal events may trigger some sort of panic in the service; note that not all events may be recovered from and are not the fault of the service itself (host machine failures, etc.). \end{itemize} The general format of a status message is as follows, parallels between the previous response as well as the request can easily be drawn. @@ -139,7 +139,7 @@ \subsection{Message Actions} \label{s:message_actions} -The examples from Section~\ref{s:preliminary_example} characterizes many of the common actions services perform on receipt of a request message. A more formal description of this interaction is described in Figure~\ref{fig:flow}. Note that this is a generalized attempt, and \textbf{SHOULD NOT} directly reflect the actions of any particular service. Protocol extensions \textbf{MUST} provide a description where this example is lacking. +The examples from Section~\ref{s:preliminary_example} characterizes many of the common actions services perform on receipt of a request message. A more formal description of this interaction is described in Figure~\ref{fig:flow}. Note that this is a generalized attempt, and should not directly reflect the actions of any particular service. Protocol extensions should provide a description where this example is lacking. \begin{figure}[ht] \centering @@ -148,12 +148,16 @@ \label{fig:flow} \end{figure} -The example illustrates that any stage of processing a request \textbf{MAY} trigger entry into the status routine. Specifics regarding available status messages \textbf{SHOULD} be categorized by service type and \textbf{SHALL} appear in the protocol extensions; specifics based on a particular action a service \textbf{MAY} take, based on internal conditions, \textbf{SHALL} appear in the service documentation. +% JZ 5/27/2010 +% +% This will need to change re: the new result codes. Leaving it in a safe state for now, but needs ot be bolstered a bit. +The example illustrates that any stage of processing a request may trigger entry into the status routine. Specifics regarding available status messages are available in Section~\ref{s:result_codes}. + \subsection{Request Message} \label{s:request_message} -The \textit{Request Message} is a container for submitting communication to capable services. Enclosed in this simple envelope \textbf{MUST} be a series of \textit{metadata} and \textit{data} pairs containing various instructions to act out. We first present a very simple schema in Section~\ref{s:request_message_schema} along with an analysis of the elements in Section~\ref{s:request_message_analysis}. We conclude with examples in Section~\ref{s:request_message_example}. +The \textit{Request Message} is a container for submitting communication to capable services. Enclosed in this simple envelope must be a series of \textit{metadata} and \textit{data} pairs containing various instructions to act out. We first present a very simple schema in Section~\ref{s:request_message_schema} along with an analysis of the elements in Section~\ref{s:request_message_analysis}. We conclude with examples in Section~\ref{s:request_message_example}. \subsubsection{Request Message Schema} \label{s:request_message_schema} @@ -171,7 +175,7 @@ \subsubsection{Request Message Analysis} \label{s:request_message_analysis} -The following is a breakdown of the elements featured in the schema. Note that services in general \textbf{MUST NOT} implement or attempt to understand this, it is provided as a tool to aid in the development of extensions. +The following is a breakdown of the elements featured in the schema. Note that services in general must not implement or attempt to understand this, it is provided as a tool to aid in the development of extensions. \paragraph{Message} \label{s:request_message_analysis_message} @@ -213,12 +217,12 @@ The message construct is meant to serve as a container for transporting \textit{requests} to capable services. The message element itself is unremarkable, it features \textit{attributes} to aid in the identification of messages (e.g. \textit{id}s) and contains elements with measurement or instructional content. We first examine the available attributes: \begin{itemize} -\item \textbf{id} - Identifier that \textbf{MAY} be used to track state between messages and services -\item \textbf{messageIdRef} - \textbf{OPTIONAL} identifier that \textit{MAY} be used to track state to previous message exchanges. -\item \textbf{type} - \textbf{MUST} designate the message to a particular type; fully enumerated in each protocol extension +\item \textbf{id} - Identifier that may be used to track state between messages and services +\item \textbf{messageIdRef} - Optional identifier that may be used to track state to previous message exchanges. +\item \textbf{type} - Must designate the message to a particular type; fully enumerated in each protocol extension \end{itemize} -There are three major elements that \textbf{MAY} be contained in the message element: +There are three major elements that should be contained in the message element: \begin{itemize} \item \textbf{Parameters} - Described in Section~\ref{s:request_message_analysis_parameters} @@ -257,10 +261,10 @@ \end{table} \label{t:request_parameters} -The parameters element encloses a series of parameter elements that \textbf{MAY} be used to adjust variable aspects of this schema. This element serves as a container for the \textit{Parameter} (see Section~\ref{s:request_message_analysis_parameter}) elements that \textbf{SHOULD} populate it. The single available attribute is described first: +The parameters element encloses a series of parameter elements that may be used to adjust variable aspects of this schema. This element serves as a container for the \textit{Parameter} (see Section~\ref{s:request_message_analysis_parameter}) elements that must populate it. The single available attribute is described first: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. +\item \textbf{id} - Identifying attribute that may be used to track state. \end{itemize} The element (only one possible in this case) is described next: @@ -278,7 +282,7 @@ % % -Note that the use of this element (in this particular location) is \textbf{OPTIONAL}. Services are not required to understand this element and \textbf{SHOULD} ignore this element if not expected by the service. Please consult service documentation before proceeding. +Note that the use of this element (in this particular location) is optional. Services are not required to understand this element and should ignore this element if not expected by the service. Please consult service documentation before proceeding. \paragraph{Parameter} \label{s:request_message_analysis_parameter} @@ -313,14 +317,14 @@ \end{table} \label{t:request_parameter} -The parameter element features a generic structure that allows easy adaptation to the needs of a particular schema. Possible names and values \textbf{SHALL NOT} be enumerated here, but \textbf{SHALL} be done both at the protocol extension and service level. +The parameter element features a generic structure that allows easy adaptation to the needs of a particular schema. For brevity, possible names and values are not listed here and are beyond the scope of this document. This exercise must be done at the protocol extension and service documentation level. \begin{itemize} -\item \textbf{name} - \textbf{MUST} specify the name of some variable value -\item \textbf{value} - \textbf{MAY} be used instead a text element (or enclosed element) to set the value of the \textit{name} +\item \textbf{name} - Must specify the name of some variable value +\item \textbf{value} - May be used instead a text element (or enclosed element) to set the value of the \textit{name} \end{itemize} -In lieu of the \textit{value} attribute, a \textit{text} (or unspecified \textit{complex}) element may be used for the same purpose. It is \textbf{RECOMMENDED} that protocol extensions adopt a single method for all uses of this element. The other possibility for element containment is left unspecified. We do not rule out that ``alternate'' elements would be useful in this case, but the exact use is left up to other extensions. +In lieu of the \textit{value} attribute, a \textit{text} (or unspecified \textit{complex}) element may be used for the same purpose. It is recommended that protocol extensions adopt a single method for all uses of this element. The other possibility for element containment is left unspecified. We do not rule out that ``alternate'' elements would be useful in this case, but the exact use is left up to other extensions. \paragraph{Metadata} \label{s:request_message_analysis_metadata} @@ -362,13 +366,13 @@ \end{table} \label{t:request_metadata} -The metadata element normally contains the static parts of measurements, and \textbf{SHALL} differ from service to service. Besides measurement data it is possible to send other items such as \textit{service descriptions}. The schema description itself of what is possible inside of this element uses vague language that allows for \textit{any} reasonable XML to be contained within. The most common elements that are included are \textit{Subject} (see Section~\ref{s:request_message_analysis_subject}), \textit{Key} (see Section~\ref{s:request_message_analysis_key}), \textit{EventType} (see Section~\ref{s:request_message_analysis_eventtype}), and \textit{Parameters} (see Section~\ref{s:request_message_analysis_parameters}). We will present only a brief discussion of these within this document; a more exact definition \textbf{MAY} be found in specific measurement documentation. +The metadata element normally contains the static parts of measurements, and shall differ from service to service. Besides measurement data it is possible to send other items such as \textit{service descriptions}. The schema description itself of what is possible inside of this element uses vague language that allows for \textit{any} reasonable XML to be contained within. The most common elements that are included are \textit{Subject} (see Section~\ref{s:request_message_analysis_subject}), \textit{Key} (see Section~\ref{s:request_message_analysis_key}), \textit{EventType} (see Section~\ref{s:request_message_analysis_eventtype}), and \textit{Parameters} (see Section~\ref{s:request_message_analysis_parameters}). We will present only a brief discussion of these within this document; a more exact definition should be found in specific measurement documentation. -There are two attributes possible. These \textbf{MAY} be used to both track state and perform the various forms of chaining (e.g. \textit{operator} or \textit{merge}) that a request message \textbf{MAY} require. A detailed description of this element follows: +There are two attributes possible. These should be used to both track state and perform the various forms of chaining (e.g. \textit{operator} or \textit{merge}) that a request message may require. A detailed description of this element follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. -\item \textbf{metadataIdRef} - Identifying attribute that \textbf{MAY} be used to track state or for \textit{chaining} procedures. +\item \textbf{id} - Identifying attribute that may be used to track state. +\item \textbf{metadataIdRef} - Identifying attribute that may be used to track state or for \textit{chaining} procedures. \end{itemize} \paragraph{Subject} @@ -399,11 +403,11 @@ \end{table} \label{t:request_subject} -The subject element normally contains \textit{topological} specifications that relate directly to a measurement or \textbf{MAY} refer to a specific service. We leave a full description of this element up to individual implementations but mention it here due to common use. There are two \textbf{RECOMMENDED} attributes, these are used to both track state and perform a specific type of \textit{chaining} (e.g. \textit{subject} chaining) that \textbf{MAY} be required in a request message. A detailed description follows: +The subject element normally contains \textit{topological} specifications that relate directly to a measurement or a specific service. We leave a full description of this element up to individual implementations but mention it here due to common use. There are two recommended attributes, these are used to both track state and perform a specific type of \textit{chaining} (e.g. \textit{subject} chaining) that may be required in a request message. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. -\item \textbf{metadataIdRef} - Identifying attribute that \textbf{MAY} be used to track state or used in \textit{chaining}. +\item \textbf{id} - Identifying attribute that may be used to track state. +\item \textbf{metadataIdRef} - Identifying attribute that may be used to track state or used in \textit{chaining}. \end{itemize} \paragraph{Key} @@ -453,10 +457,10 @@ The key element is rooted in the concept of a \textit{hash function} --- a function or process designed to convert a variable amount of information into a single value or \textit{index}. Once converted this single value can then be used a shorthanded notation to reference the original entity, imparting a performance increase for computational tasks. -The key structure \textbf{SHALL} used to convey sensitive or private information to and from the service. For this reason the contents of the key \textbf{SHOULD} be viewed as ``opaque'', and \textbf{MUST NOT} be dissected. The key \textbf{SHOULD} contain a \textit{Parameters} (see Section~\ref{s:request_message_analysis_parameters}) element. There is only one attribute possible: \textit{id}. This \textbf{MAY} used to track state. A detailed description follows: +The key structure shall used to convey sensitive or private information to and from the service. For this reason the contents of the key must be viewed as ``opaque'', and must not be dissected. The key should contain a \textit{Parameters} (see Section~\ref{s:request_message_analysis_parameters}) element. There is only one attribute possible: \textit{id}. This may used to track state. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. +\item \textbf{id} - Identifying attribute that may be used to track state. \end{itemize} \paragraph{EventType} @@ -486,7 +490,7 @@ \end{table} \label{t:request_eventtype} -The eventType element \textbf{SHOULD} used to describe a measurement's specific data type (e.g. closely matching the definitions described in \cite{chardoc} and \cite{chargrid03}) or \textbf{MAY} be used to trigger an internal event within the service. This element contains no attributes, and \textbf{MUST} only contain text, normally in the form of a \textit{URI}. There \textbf{MAY} be \textit{many} eventType elements in a single metadata. +The eventType element must used to describe a measurement's specific data type (e.g. closely matching the definitions described in \cite{chardoc} and \cite{chargrid03}) or should be used to trigger an internal event within the service. This element contains no attributes, and must only contain text, normally in the form of a \textit{URI}. There may be \textit{many} eventType elements in a single metadata. \paragraph{Data} \label{s:request_message_analysis_data} @@ -516,13 +520,13 @@ \end{table} \label{t:request_data} -The data element \textbf{SHOULD} contain the dynamic parts of measurements, and \textbf{SHALL} differ from service to service. Besides collected measurements the data field \textbf{MAY} also be populated with query data, or even other other metadata information in certain applications. We leave the description of what is possible inside of \textit{data} blank, and use vague schema language that allows for \textit{any} reasonable content to be contained within. +The data element must contain the dynamic parts of measurements, and shall differ from service to service. Besides collected measurements the data field may also be populated with query data, or even other other metadata information in certain applications. We leave the description of what is possible inside of \textit{data} blank, and use vague schema language that allows for \textit{any} reasonable content to be contained within. -There are two attributes possible. These \textbf{MAY} used to track state inside of a request message. A detailed description follows: +There are two attributes possible. These may used to track state inside of a request message. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. -\item \textbf{metadataIdRef} - \textbf{MUST} be used to link data to metadata. +\item \textbf{id} - Identifying attribute that may be used to track state. +\item \textbf{metadataIdRef} - must be used to link data to metadata. \end{itemize} \subsubsection{Request Message Example} @@ -540,7 +544,7 @@ \end{verbatim} \normalsize -The second example is similar, but incorporates a parameters block that \textbf{MAY} be populated with \textbf{OPTIONAL} behaviors of a service. +The second example is similar, but incorporates a parameters block that may be populated with optional behaviors of a service. \tiny \begin{verbatim} @@ -583,7 +587,7 @@ \subsection{Response Message} \label{s:response_message} -The response message is a container filled with the results of a \textit{Response Message} from a capable service. Enclosed in this simple envelope \textbf{SHALL} be a series of metadata and data pairs containing the results of actions performed by a service. We first present a very simple schema in Section~\ref{s:response_message_schema} along with an analysis of the elements in Section~\ref{s:response_message_analysis}. We conclude with examples in Section~\ref{s:response_message_example}. +The response message is a container filled with the results of a \textit{Response Message} from a capable service. Enclosed in this simple envelope must be a series of metadata and data pairs containing the results of actions performed by a service. We first present a very simple schema in Section~\ref{s:response_message_schema} along with an analysis of the elements in Section~\ref{s:response_message_analysis}. We conclude with examples in Section~\ref{s:response_message_example}. \subsubsection{Response Message Schema} \label{s:response_message_schema} @@ -601,7 +605,7 @@ \subsubsection{Response Message Analysis} \label{s:response_message_analysis} -The following is a breakdown of the elements featured in the schema. Note that services in general \textbf{MUST NOT} implement or attempt to understand this, it is provided as a tool to aid in the development of extensions. +The following is a breakdown of the elements featured in the schema. Note that services in general must not implement or attempt to understand this, it is provided as a tool to aid in the development of extensions. \paragraph{Message} \label{s:response_message_analysis_message} @@ -644,9 +648,9 @@ The message element, like it's counterpart seen in Section~\ref{s:request_message_analysis_message} serves as a container for transporting responses from capable services. The message itself is unremarkable, it features attributes to aid in the identification of messages and contains elements with measurement or instructional content. We first examine the available attributes: \begin{itemize} -\item \textbf{id} - Identifier that \textbf{MAY} be used to track state between messages and services -\item \textbf{type} - \textbf{MUST} designate the message to a particular type; fully enumerated in each protocol extension -\item \textbf{messageIdRef} - Identifier that \textbf{MAY} be used to track state between messages and services +\item \textbf{id} - Identifier that may be used to track state between messages and services +\item \textbf{type} - Must designate the message to a particular type; fully enumerated in each protocol extension +\item \textbf{messageIdRef} - Identifier that may be used to track state between messages and services \end{itemize} There are three major elements that may be contained in the message element: @@ -688,13 +692,13 @@ \end{table} \label{t:response_parameters} -The parameters element \textbf{SHOULD} only be present in the message element if there was a corresponding element in the \textit{Request Message} (see Section~\ref{s:request_message_analysis_message}). It \textbf{MAY} also be used by services to relay back other forms of information. As in Section~\ref{s:request_message_analysis_parameters}, it encloses a series of \textit{parameter} elements. This element serves merely as a container for the Parameter elements (see Section~\ref{s:response_message_analysis_parameter}) that will populate it. The single available attribute is described first: +The parameters element should only be present in the message element if there was a corresponding element in the \textit{Request Message} (see Section~\ref{s:request_message_analysis_message}). It may also be used by services to relay back other forms of information. As in Section~\ref{s:request_message_analysis_parameters}, it encloses a series of \textit{parameter} elements. This element serves merely as a container for the Parameter elements (see Section~\ref{s:response_message_analysis_parameter}) that will populate it. The single available attribute is described first: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. +\item \textbf{id} - Identifying attribute that may be used to track state. \end{itemize} -There is only one available element, although it \textbf{MAY} be used multiple times +There is only one available element, although it may be used multiple times \begin{itemize} \item \textbf{Parameter} - Described in Section~\ref{s:response_message_analysis_parameter} @@ -732,14 +736,14 @@ \end{table} \label{t:response_parameter} -The parameter element features a generic structure that allows it to easily adapt to the needs of a particular schema. Possible names and values \textbf{SHALL NOT} be enumerated here, but \textbf{SHALL} be done both at the protocol extension and service level. +The parameter element features a generic structure that allows it to easily adapt to the needs of a particular schema. For brevity, possible names and values are not listed here and are beyond the scope of this document. This exercise must be done at the protocol extension and service documentation level. \begin{itemize} -\item \textbf{name} - \textbf{MUST} generically specify the name of some variable value -\item \textbf{value} - \textbf{MAY} be used instead a text element to set the value of the \textit{name} +\item \textbf{name} - Must generically specify the name of some variable value +\item \textbf{value} - May be used instead a text element to set the value of the \textit{name} \end{itemize} -In lieu of the \textit{value} attribute, a text element \textbf{MAY} be used for the same purpose. It is \textbf{RECOMMENDED} that protocol extensions adopt a single method for all uses of this element. The other possibility for element containment is left unspecified. We do not rule out that many elements would be useful in this case, but the exact use is left up to other extensions. +In lieu of the \textit{value} attribute, a text element may be used for the same purpose. It is recommended that protocol extensions adopt a single method for all uses of this element. The other possibility for element containment is left unspecified. We do not rule out that many elements would be useful in this case, but the exact use is left up to other extensions. \paragraph{Metadata} \label{s:response_message_analysis_metadata} @@ -782,11 +786,11 @@ The metadata element in the response is normally an exact copy of the sent \textit{Metadata} (see Section~\ref{s:request_message_analysis_metadata}). We leave the description of what is possible inside of a metadata blank, and use vague schema language that allows for any reasonable XML to be contained within. -There are two attributes possible. These \textbf{MAY} be used to track state, possibly back to the sent \textit{Metadata}. A detailed description follows: +There are two attributes possible. These may be used to track state, possibly back to the sent \textit{Metadata}. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. -\item \textbf{metadataIdRef} - Identifying attribute that \textbf{MAY} be used to track state. +\item \textbf{id} - Identifying attribute that may be used to track state. +\item \textbf{metadataIdRef} - Identifying attribute that may be used to track state. \end{itemize} \paragraph{Data} @@ -826,11 +830,11 @@ The data element will contain results and is usually not not empty like the trigger that is used in \textit{Data} (see Section~\ref{s:request_message_analysis_data}). We leave the description of what is possible inside of a data blank, and use vague schema language that allows for any reasonable XML to be contained within. -There are two attributes possible. These \textbf{MAY} be used to both track state inside of a response message. A detailed description follows: +There are two attributes possible. These may be used to both track state inside of a response message. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. -\item \textbf{metadataIdRef} - \textbf{MUST} be used to link data to metadata. +\item \textbf{id} - Identifying attribute that may be used to track state. +\item \textbf{metadataIdRef} - Must be used to link data to metadata. \end{itemize} \paragraph{Key} @@ -864,10 +868,10 @@ \end{table} \label{t:response_key} -The key structure \textbf{SHOULD} be used to convey sensitive or private information to and from the service. For this reason the contents of the key \textbf{SHOULD} be viewed as opaque, and generally not be dissected. The key \textbf{SHOULD} contain the \textit{Parameters} (see Section~\ref{s:response_message_analysis_parameters}) element. There is only one attributes possible: id. This \textbf{MAY} be used to track state. A detailed description follows: +The key structure should be used to convey sensitive or private information to and from the service. For this reason the contents of the key must be viewed as opaque, and generally not be dissected. The key should contain the \textit{Parameters} (see Section~\ref{s:response_message_analysis_parameters}) element. There is only one attributes possible: id. This may be used to track state. A detailed description follows: \begin{itemize} -\item \textbf{id} - Identifying attribute that \textbf{MAY} be used to track state. +\item \textbf{id} - Identifying attribute that may be used to track state. \end{itemize} \paragraph{Datum} @@ -896,7 +900,7 @@ \end{table} \label{t:response_datum} -The datum element \textbf{SHOULD} be used to relay information. Common uses are to return measurement observations (e.g. time and value pairs) or even status (e.g. error messages). We leave the attributes and nested elements purposely undefined as they \textbf{MAY} differ in various profiles of this document. +The datum element should be used to relay various types of information. Common uses are to return measurement observations (e.g. time and value pairs) or even status (e.g. error messages). We leave the attributes and nested elements purposely undefined as they may differ in various profiles of this document. \subsubsection{Response Message Example} \label{s:response_message_example} @@ -923,7 +927,7 @@ \end{verbatim} \normalsize -The final example demonstrates an error condition. Note that this \textbf{MAY} contain multiple pairs if sent, and it \textbf{MAY} be possible to have success for some, and errors for others. +The final example demonstrates an error condition. Note that this may contain multiple pairs if sent, and it may be possible to have success for some, and errors for others. \tiny \begin{verbatim} Modified: motivation.tex =================================================================== --- motivation.tex 2010-04-07 13:31:48 UTC (rev 21) +++ motivation.tex 2010-05-27 14:31:27 UTC (rev 22) @@ -42,10 +42,10 @@ The acts of sending \textit{requests}, receiving \textit{responses}, and being able to discern success or failure are common across many specific interactions. One aim of this document is to prevent the following redundancies: \begin{itemize} -\item \textbf{Duplicate Schemata} - \textit{Messages} differ from service to service, but the overarching concepts should not; we present some of the common features that \textbf{MUST} be present in every exchange and describe how extension is possible. +\item \textbf{Duplicate Schemata} - \textit{Messages} differ from service to service, but the overarching concepts will not; we present some of the common features that must be present in every exchange and describe how extension is possible. \item \textbf{Duplicate Semantic Principals} - Concepts used in services designed in the past are carried over into future iterations. Common practices and common features are only described once. \item \textbf{Duplicate Error Conditions} - Some errors will occur across services and are only defined once (e.g. \textit{Unknown Message Type}). -\item \textbf{Duplication of Common Exchanges} - Common protocols should be the same among services in a framework. For example being able to retrieve the ``status'' of a neighbor or wrapping your communication in a secure channel are communication patterns that will no doubt be required everywhere. A common \textit{Echo} protocol is presented in this document as an example. +\item \textbf{Duplication of Common Exchanges} - Common protocols must be the same among services in a framework. For example being able to retrieve the ``status'' of a neighbor or wrapping your communication in a secure channel are communication patterns that will be required everywhere. A common \textit{Echo} protocol is presented in this document as an example. \end{itemize} With a set design and format to this base functionality, it is possible to define protocol extensions on a ``type by type'' basis instead of a ``service by service'' approach. This also allows for a sufficient reduction in documentation due to service types implementing the same underlying \textit{format} of messages (e.g. services that store measurements may implement the same message types with notable exceptions and data differences). It is expected that the following extensions to this base document will be prepared to describe specific service interactions: Modified: nmc-base.pdf =================================================================== (Binary files differ) Modified: nmc-base.tex =================================================================== --- nmc-base.tex 2010-04-07 13:31:48 UTC (rev 21) +++ nmc-base.tex 2010-05-27 14:31:27 UTC (rev 22) @@ -120,7 +120,7 @@ \section{Notational Conventions} -The key words ``MUST'' ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' are to be interpreted as described in RFC 2119 \cite{rfc2119} +The key words ``MUST'' ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' are to be interpreted as described in RFC 2119 \cite{rfc2119}, except that the words do not appear in uppercase. \section{Security Considerations} % XXX jz - 1/28/2010