########################################################################

An XML schema for requesting measurements
================================================================================


Abstract
================================================================================

General model information
================================================================================

Namespaces:
--------------------------------------------------------------------------------
Unless otherwise indicated with a prefix such as "xsi:", all elements and types
referenced in this document are in the blahblahblah namespace.

Indication of types:
--------------------------------------------------------------------------------
To indicate the type of an element, the {xsi:type} attribute may be used[XSD].

In the case of elements which must have a type derived from a type specified
in this document, the type of that element MUST be specified with an {xsd:type}
attribute.


Model
================================================================================

This document describes the contents of an XML element used to represent a
request for a network measurement, either in the past or in the furture.
The element MUST be called {NetworkMeasurementRequest}[1]

The element MUST contain the following named sub elements:
 * 1 {subject} element
 * 1 {time} element
 * 1 or more {characteristic} elements
 * 0 or 1{ methodology} elements
 * 0 or 1 {statistics} elements[2a]


Element subject
--------------------------------------------------------------------------------
The {subject} element describes the subject of the measurement, that is, the
hosts and routers involved.

The {subject} element MUST have a type that is derived from NetworkEntityType.

The following derived types have been defined:

NetworkPathType
 This describes the hosts that forms the endpoints of a path. It consists of two
 elements, {source} and {destination}, each of which MUST have a type that is
 derived from NetworkEntityType.

NodeType
 This describes a single host that has an address of some sort, and optionally
 a name and a tool[3]. The element MUST contain an {address} element of type
 NetworkAddressType or a derived type, and MAY contain a {name} element of type
 xs:string.

NamedNodeType
 This describes a single host that is identified by a name only.
 It MUST contain a single element called {name} of type xs:string that contains
 the name of the host.

The following types derived from NetworkEntityType have been defined:

IPAddressType
 This describes an IP address. It MUST contain an element called {IP} of type
 xs:string that contains the IP address of the node. It MAY contain a {port}
 element[3] indicating the port the tool should (have) connect(ed) to.
 The element MAY also have an attribute called {version} of type xs:token
 that indiciates the protocol version. If ommitted, the version is assumed to
 be IPv4[4]

DNSAddressType
 This describes a DNS address. It MUST contain an element called {name} of type
 xs:string that contains the DNS address of the node. It MAY contain a {port}
 element[3] indicating the port should (have) connect(ed) to.


Element {time}
--------------------------------------------------------------------------------
The {time} element has type TimeInformationType.
It describes the time of interest for this request. The time may either be a
range of times or a single time and a tolerance. If the request is specifying
a future measurement over a range of times, the it can also specify the interval
between measurements.

In the following section, the time represented by the string value "now" is
assumed to be the current time at all times. A service may convert it to a real
time for whatever reasons, but it should do so as late as possible.

For example: a client sends a request for measurements between A and "now" at
time B, where A<B. The service queries a database at time D, where B<D,
requesting all measurements after time A (the before "now" is implied, as such
measurements will not be in the database). If a measurement were to be made at
time C, where B<C<D, that measurement would also be returned as C was before
the time represented by "now" when the measurement was made.

For example: a client sends a request for a measurement to be made "now",
or within 25 seconds. The service might check if any measurements have been
made in the last 25 seconds (and if so, returns the latest), if any
measurements are to be made in the next 25 seconds (and if so, returns the
earliest once it is completed), and if neither of those are true, causes a new
measurement to be made there and then and returns that.

For example: a client sends a request for a measurement to be made at exactly
"now". The service might cause a new measurement to be made, and would return
that.

This {time} element MUST contain EITHER:

1) An optional element, {time}, which is of type TimeType, and may either
   contain a double value indicating the Unix time [epoch] or the string value
   "now" or an xs:dateTime value. If omitted, the value "now" must be assumed.
   An optional element, {plusTimeTolerance}, which is of type TimeIntervalType,
   and may contain either a positive double value or the string value
   "unbounded".
   An optional element, {minusTimeTolerance}, which is of type TimeIntervalType,
   and may contain either a positive double value or the string value
   "unbounded".
   An optional element, {maxResults} of type xs:positiveInteger.
   Measurements must have been made after {time} minus {minusTimeTolerance} and
   {time} plus {plusTimeTolerance}.
   A value of "unbounded" in {minusTimeTolerance} indicates that any measurement
   made before {time} will be accepted. A value of "unbounded" in
   {plusTimeTolerance} indicates that any measurement made after {time} will be
   accepted.
   If omitted, {minusTimeTolerance} and {plusTimeTolerance} are taken as
   "unbounded".
   If {maxResults} is greater than zero and less than the number of acceptable
   measurements, the service MUST return no more than {maxResults} measurements.
   The measurements are chosen by calculating the absolute time difference
   between {time} and the timestamp of the measurement; the {maxResults}
   measurements with the lowest absolute time difference should be accepted.

   
2) An optional element {startTime} and an optional element {endTime}. Both
   are of type TimeType, and so may contain a double value indicating the Unix
   time [epoch] or the string value "now".
   These elements should be translated into values of the elements in option 1
   above:

                 time = startTime
   minusTimeTolerance = "0"
    plusTimeTolerance = endTime - startTime
           maxResults = "unbounded"


These elements describe a range of times. If they describe a range of times in
the past, that is any time up to and including "now", then the service SHOULD
supply every requested measurement in that range of times. If they describe a
range of times in the future or partially in the future, that is, endTime is at
or after the time represented by "now", the service SHOULD supply the results of
any measurements made in that time, and MAY make otherwise unscheduled
measurements. The optional TimeIntervalType element {testingInterval} can be
used by the service to describe the time interval between measurements made as
a result of the request.

In the case that no elements are entered (which is an acceptable part of either
option above), the request is assumed to be for a {time} of "now", with a
{plusTimeTolerance} and {minusTimeTolerance} of "unbounded".

Element {characteristic}
--------------------------------------------------------------------------------
The {characteristic} elements contain the name of the characteristic requested.
The characteristic name SHOULD match that described in the NMWG hierarchy
document [NMWGHeir].


Element {methodology}
--------------------------------------------------------------------------------
The {methodology} element is of type MethodologyType and MUST contain any number
(including none) of {parameters} elements.
Each {parameters} element must have a type derived from ParameterSetType.

Each child element of the {parameters} element describes a parameter of the
measurement(s). Each element SHOULD be both optional and unbounded (see ranges
below).

Each child element of the {parameters} element MUST have the following three
attributes:

{use}: type: ParameterUseType. This is an enumeration, and MUST take one of
       "optional" or "required" as values. The default is "optional".
       "optional" indicates that the service SHOULD return measurements where
       the specified parameter has that value if possible, but MAY return
       measurements with an unknown or different parameter value otherwise.
       "required" indicates that the service MUST return measurements where the
       specified parameter has that value if it is possible to do so, and if
       not, it MUST NOT return any value.
{report}: type: xs:boolean. This may take the values "true" or "false".
       "true" indicates that the parameter value SHOULD be reported in the
       reply to the client. "false" indicates that the parameter value
       SHOULD NOT be reported.
{range}: type: ParameterRangeType. This is an enumeration and MUST take one of
       the values "exact", "minimum" or "maximum".
       See ranges, below.


Unknown parameters
------------------
If a service comes across a {parameters} element of an unknown type, it should
check the {use} attribute of each of the constituent parameters.

If the service encounters an unknown parameter with use="required", it
MUST NOT return a measurement.

Otherwise the service SHOULD return a measurement matching any known parameters
as described above. If a parameter is marked report="true", the service MAY
report that the parameter is unknown, if the return mechanism supports doing so.


Defined types
-------------
We have defined a few types derived from ParameterSetType. Each one contains a
number of parameters.

IPParameterSetType

TCPParameterSetType

ICMPParameterSetType

ApplicationParameterSetType

ToolParameterSetType

Ranges
------
The following applies to the child elements of the {parameters} element with a
particular name.

The range attribute indicates that the element describes either the minimum
acceptable value, the maximum acceptable value, or the exact value for a
parameter.

The service should divide the list of elements into those marked use="optional"
and those marked use="required".

For those marked use="required", for each parameter specified in the request,
the service MUST ensure that the matchine parameter of the returned measurement
is either, or both

 * equal to the earliest possible of the request parameters with range="exact"
 or
 * both: * greater-than or equal-to ALL of the request parameters with
           range="minimum"
         and
         * less-than or equal-to ALL of the request parameters with
           range="maximum"

For those marked use="optional", for each parameter specified in the request,
the service SHOULD try to ensure that the matchine parameter of the returned
measurement is either

 * equal to the earliest possible of the request parameters with range="exact"
 or
 * both: * greater-than or equal-to the earliest possible of the request
           parameters with range="minimum" if any exist.
         and
         * less-than or equal-to the ealiest possible of the request parameters
           with range="maximum" if any exist.

If the element is missing, then the service SHOULD use whatever default value it
has for that parameter.

If the element is present, and is marked "optional" but no value is given, then
the service SHOULD use whatever default value it has for that parameter.


Element {statistics}
--------------------------------------------------------------------------------
The {statistics} element is of type StatisticsType. It represents a request for
statistical summaries of the raw data.

It may contain any number of elements in the {statistic} substitutionGroup.

We have defined a number of elements in this group, any of which may be used:

{count}, {min}, {max}, {mean}, {median}, {stddev}: this elements do not contain
  any child elements, and represent a request for, respectively: a count of the
  number of measurements made; the minimum value measured; the maximum value
  measured; the mean of all the values measured; the median value of all the
  values; the standard deviation of all the values.

{percentile}: this element MAY take one attribute, {n}, which is an xs:double
  value between 0 and 100. This represents a request for the nth percentile
  of the measurements made. If not explicitly stated, {n} takes the value 95.

{confidence}: this element MAY take one attribute, {confidence}, which is an
  xs:double value between 0 and 100. This represents a request for the specified
  confidence interval. If omitted, {confidence} takes  the value 95.

Each statistic element may also contain an {interval} attribute of type
TimeIntervalType, which may take any positive real value indicating the time
period over which the statistical summary should be made, or the string
"unbounded". If the value is "unbounded" and a range of times in the {time}
root element is given, the summary should be for all measurements in that range.
Otherwise if the value is "unbounded", a sensible default range should be used.



NOTES
================================================================================

[1] Should it really? Maybe we should be describing a Type. The same goes for
the response schema.

[3] These elements are a hang-overs from the response document.
    They may be unnecessary.

[4] In the IPAddressType taken from the response document, the default is
    "4" in this case, but IPv4 in the Parameters.





Other stuff

[epoch] The Unix time is given by the number of seconds since midnight
  on the first of January 1970, UTC.

[XSD] XML Schema Definition.

[NMWGHeir] A Hierarchy of Network Performance Characteristics for Grid Applications and Services,
	   http://www-didc.lbl.gov/NMWG/docs/draft-ggf-nmwg-hierarchy-01.pdf