# ##############################################################
# 
# File:         traceroute.rnc - Specialized schema for the 
#                                 traceroute tool 
# Version:      $Id$
# Purpose:      Describes specific elements to be used in the
#               representation and handling of traceroute
#               measurements.
# Reference:    http://books.xmlschemata.org/relaxng/page2.html
#                         
# ##############################################################


# ##############################################################
# Namespace definitions
# ##############################################################
namespace nmwg = "http://ggf.org/ns/nmwg/base/2.0/"
namespace traceroute = "http://ggf.org/ns/nmwg/tools/traceroute/2.0/"
namespace nmwgr = "http://ggf.org/ns/nmwg/result/2.0/"


# ##############################################################
# Include additional functionality from other files
# ##############################################################
include "nmtopo.rnc"
include "nmtopo_ver3.rnc"
include "result.rnc"
include "nmbase.rnc" {
        Metadata |= TracerouteMetadata
        Data |= TracerouteData        
} 


# ##############################################################
# Metadata is the 'data' that describes physical measurements. 
# Metadata can be something such as a physical address, or 
# a geographical location; any form of static, re-usable 
# designation.  It is important to note that the subject
# namespace and parameters namespace MUST match (or the parameters
# can be a generic NMWG) or bad things will occur.
#
# Example: 
# 
# <nmwg:metadata id="REQUIRED_ID" 
#                metadataIdRef="OPTIONAL_REFERENCE_ID"
#                xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
# 
#   <!-- TBD OPTIONAL SUBJECT -->
# 
#   <!-- TBD OPTIONAL PARAMETERS -->
#
#   <!-- TBD OPTIONAL EVENTTYPE -->
# 
#   <!-- TBD OPTIONAL KEY -->
#  
#   <!-- ANY OPTIONAL (MULTIPLE) ELEMENT IN ANY NAMESPACE --> 
#
# </nmwg:metadata>
# 
# ##############################################################
        
TracerouteMetadata = 
        element nmwg:metadata {
                Identifier &
                MetadataIdentifierRef? &
                TracerouteMetadataContent
        }
          
TracerouteMetadataBlock = 
        TracerouteSubject? &
        (
                TracerouteParameters |
                Parameters
        )?        
        
TracerouteMetadataContent = 
        (
                TracerouteMetadataBlock |
                FilterMetadataBlock                
        ) &        
        EventType? &
        Key?        

# ##############################################################
# Redefined ping subject allows only an endPointPair, and the
# two id attributes.    
#
# Example: 
# 
# <traceroute:subject id="REQUIRED_ID" 
#               metadataIdRef="OPTIONAL_REFERENCE_ID"
#               xmlns:nmwg="http://ggf.org/ns/nmwg/tools/traceroute/2.0/">
# 
#   <nmwgtopo:endPointPair xmlns:nmwgtopo="http://ggf.org/ns/nmwg/topology/2.0/">
# 
#     <nmwgtopo:src type="REQUIRED_TYPE" value="REQUIRED_VALUE" 
#                   port="OPTIONAL_PORT"/>
# 
#     <nmwgtopo:dst type="REQUIRED_TYPE" value="REQUIRED_VALUE" 
#                   port="OPTIONAL_PORT"/>
#  
#   </nmwgtopo:endPointPair>
#  
# </traceroute:subject>
#
# ##############################################################

TracerouteSubject =
        element traceroute:subject {
                Identifier &
                MetadataIdentifierRef? &                        
                (                   
                        EndpointPair |
                        L4EndpointPair
                )
        }


# ##############################################################
# This is simply the regular method of doing parameters with an
# enumeration to limit what 'names' are accepted and an outer
# ping: namespace for the parameters.
#
# Example: 
# 
# <traceroute:parameters id="REQUIRED_ID" 
#                   xmlns:nmwg="http://ggf.org/ns/nmwg/tools/traceroute/2.0/">
# 
#   <nmwg:parameter name="REQUIRED_ENUM_NAME" value="OPTIONAL_VALUE"
#                   xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
# 
#     <!-- ANY TEXT, (IF YOU DID NOT USE THE VALUE ATTRIBUTE) -->
# 
#   </nmwg:parameter>
#  
#   <!-- MORE PARAMETERS -->
#   
# </traceroute:parameters>
# 
# ##############################################################

TracerouteParameters =
        element traceroute:parameters {
                Identifier &        
                TracerouteParameter+
        }
        
TracerouteParameter = 
        element nmwg:parameter { 
                attribute name { "firstTtl" | "maxTtl" | "waitTime" | 
                                 "pause" | "packetSize" | "arguments" |       
                                 "valueUnits" | "numBytes" | 
                                 "numBytesUnits" } &
                (
                        attribute value { text } |
                        text
                )
        }


# ##############################################################
# The data block is complex, and has the potential to contain
# many things.  The data block can be used to return a metadata
# block from a request, commonTime or datum elements, keys, 
# or something that we have perhaps not defined as of yet.  
#
# Example: 
# 
# <nmwg:data id="REQUIRED_ID" 
#            metadataIdRef="OPTIONAL_REFERENCE_ID" 
#            xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
# 
#   <!-- OPTIONAL (MULTIPLE) METADATA -->
# 
#           <!-- OR -->
#
#   <!-- TBD OPTIONAL (MULTIPLE) COMMON TIME ELEMENTS AND 
#        OPTIONAL (MULTIPLE) DATUM ELEMENTS-->
# 
#           <!-- OR -->
#  
#   <!-- TBD OPTIONAL (MULTIPLE) DATUM ELEMENTS -->
# 
#           <!-- OR -->
#  
#   <!-- OPTIONAL (MULTIPLE) KEY ELEMENTS -->
# 
#           <!-- OR -->
# 
#   <!-- ANY OPTIONAL (MULTIPLE) ELEMENT IN ANY NAMESPACE -->
#   
# </nmwg:data>
# 
# ##############################################################
   
TracerouteData =
        element nmwg:data {
                Identifier &
                MetadataIdentifierRef? &
                (
                        (
                                Metadata* |
                                TracerouteMetadata*
                        ) |
                        (
                                TracerouteCommonTime+ & 
                                (
                                        TracerouteDatum* |
                                        ResultDatum*
                                )
                        ) |
                        (
                                TracerouteDatum* |
                                ResultDatum*
                        ) |
                        Key*
                )
        }


# ##############################################################
# CommonTime is used a a shortcut able to 'factor out' a frequently
# occurring time range that a bunch of datum (or other) elements
# might share, thus reducing complexity of XML representation.  
# CommonTime is similar to the other NMWG time stamps (from 
# nmtime.rnc) in its potential time representations.
#
# Example: 
# 
# <nmwg:commonTime type="REQUIRED_TYPE" value="OPTIONAL_VALUE"
#                  duration="OPTIONAL_DURATION" 
#                  inclusive="OPTIONAL_INCLUSIVE_FLAG"
#                  xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
# 
#   <!-- TBD OPTIONAL START TIME ELEMENT (USE END TIME OR DURATION) -->
#  
#   <!-- TBD OPTIONAL END TIME ELEMENT (ONLY WITH START TIME) -->
#  
#   <!-- TBD OPTIONAL TIME VALUE ELEMENT (USE IF NO VALUE ATTRIBUTE) -->
#  
#   <!-- TBD OPTIONAL (MULTIPLE) DATUM ELEMENTS -->
# 
#   <!-- ANY OPTIONAL (MULTIPLE) ELEMENT IN ANY NAMESPACE -->
# </nmwg:commonTime>
# 
# ##############################################################

TracerouteCommonTime = 
        element nmwg:commonTime {
                Type &
                (
                        TimeStamp |
                        (
                                StartTime & 
                                (
                                        EndTime | 
                                        Duration 
                                )
                        )
                ) &
                (
                        TracerouteDatum* |
                        ResultDatum*
                )
        } 


# ##############################################################
# These are the basic elements we would expect to see in the 
# specific traceroute datum.
#
# Example: 
# 
# <traceroute:datum value="REQUIRED_VALUE"
#              valueUnits="OPTIONAL_VALUE_UNITS"
#              numBytes="OPTIONAL_NUM_BYTES"
#              numBytesUnits="OPTIONAL_NUM_BYTES_UNITS"
#              ttl="OPTIONAL_TTL"
#              queryNum="OPTIONAL_QUERY_NUM"
#              hop="OPTIONAL_HOP"
#              timeType="OPTIONAL_TIME_TYPE"
#              timeValue="OPTIONAL_TIME_VALUE"
#              xmlns:nmwg="http://ggf.org/ns/nmwg/tools/traceroute/2.0/">
# 
#   <!-- TIME ELEMENT (IF ATTRIBUTES NOT USED) -->
#  
# </traceroute:datum>
# 
# ##############################################################

TracerouteDatum =
        element traceroute:datum {
                attribute value { xsd:float } &
                attribute valueUnits { xsd:string }? &        
                attribute numBytes { xsd:int }? &
                attribute numBytesUnits { xsd:string }? &        
                attribute ttl { xsd:int }? &
                attribute queryNum { xsd:int }? &
                attribute hop { xsd:string }? & 
                (
                        (
                                attribute timeType { xsd:string } & 
                                attribute timeValue { xsd:string }
                        ) |
                        Time
                )?                       
        }