perfsonar development work

Author: aaron
Date: 2007-09-14 17:02:12 -0400 (Fri, 14 Sep 2007)
New Revision: 268

Modified:
   trunk/nmwg/doc/nm-topo/nm-topo.xml
Log:
Include a more thorough specification of the various fields.



Modified: trunk/nmwg/doc/nm-topo/nm-topo.xml
===================================================================
--- trunk/nmwg/doc/nm-topo/nm-topo.xml  2007-09-14 17:56:01 UTC (rev 267)
+++ trunk/nmwg/doc/nm-topo/nm-topo.xml  2007-09-14 21:02:12 UTC (rev 268)
@@ -71,8 +71,9 @@
 
 The identifiers are encoded using the standard URN syntax as described in RFC
 2141. The namespace for the urn is ``ogf''. The ``network'' namespace inside
-the ``ogf'' namespace is used to differentiate the various URNs in the OGF
-namespace. Thus, all identifiers must begin with "urn:ogf:network:".
+the ``ogf'' namespace is used to differentiate these identifiers from other
+identifying URNs in the OGF namespace. Thus, all identifiers MUST begin with
+"urn:ogf:network:".
 
 The format for the rest of the namespace consists of a set of name/value 
pairs.
 Each pair is separated by a ``:'' and each name and value is separated by a
@@ -85,29 +86,100 @@
 The ordering of the name/value pairs goes from the most general network 
element
 to most specific network element.
 
-Unidirectional Links
+Domain
 
-An identifier for a unidirectional link consists of all the network elements
-required to 
+The domain field must be used to describe an administrative domain. The
+identifier for the domain MUST ONLY include the domain field. The actual 
value
+of the field MUST correspond to the AS number for the given network, and MUST
+NOT include any trailing spaces.
 
-Bidirectional Links
+Node
 
-Unlike unidirectional links, bidirectional links can be specified either at 
the
-top-level or inside of a domain. Bidirectional links can include links that
-exists completely in one domain, as well as, links that cross domain
-boundaries. In these scenarios, the link identifiers would be different. For
-the link that exists completely inside a single domain, the identifier must
-include the domain field. If a link crosses domain boundaries, it must be
-identified with a top-level link identifier. 
+The node field MUST be used to refer to a physical device such as a router, a
+logical device like a [XXX example] or a virtual device like a [XXX example].
+Nodes belong to a specific administrative domain and thus, the identifier 
for a
+node MUST include the domain field which MUST be identicial to that field in
+the identifier for that domain. The value of the field can be anything, but
+MUST be unique inside the domain and MUST NOT include any trailing spaces. It
+SHOULD be human readable a human readable description of the node. 
 
+Interfaces
 
+The port field MUST be used to identify a physical, logical or virtual
+interface. Interfaces belong to a specific node and thus, the identifier for 
an
+interface MUST include the node and domain fields which MUST be identicial to
+those fields in the identifier for that node. The value of the field can be
+anything, but MUST be unique inside the node and MUST NOT include any 
trailing
+spaces. It SHOULD be a human readable description of the port.
+
+Unidirectional Intra-domain/Inter-domain Links
+
+A unidirectional link MUST be identified by the link field. The undirectional
+link belongs to the port which can write to the link. Thus, the identifier 
for
+the undirectional link MUST include the domain, node and port fields which 
MUST
+be identical to those fields in the identifier for the port to which the link
+belongs. The value of the field can be anything, but MUST be unique inside 
the
+port and MUST NOT include any trailing spaces. It SHOULD be a human readable
+description of the link. If the unidirectional link is one side of a
+bidirectional link, the value of the link field SHOULD be the same as the 
other
+direction of the bidirectional link.
+
+Bidirectional Domain Links
+
+A bidirectional link that begins and ends solely in one domain MUST be
+identified by the link field. The bidirectional link belongs to the domain in
+which the link exists. Thus, the identifier for the link MUST include the
+domain field which MUST be identical to that field in the identifier for the
+domain to which the link belongs. The value of the field can be anything, but
+MUST be unique inside the port and MUST NOT include any trailing spaces. It
+SHOULD be a human readable description of the link and SHOULD be the same 
value
+as the undirectional links that make up the link.
+
+Bidirectional Inter-domain Links
+
+A bidirectional link that begins and ends in differing domains MUST be
+identified by the link field. The bidirectional link MUST NOT include any
+fields other than link. The value of the field can be anything, but MUST be
+globally unique and MUST NOT include any trailing spaces. It SHOULD be a
+human readable description of the link and SHOULD be the same value as the
+undirectional links that make up the link.
+
+Intra-domain Path
+
+The path field MUST be used for any named path that passes only inside a
+domain. An intra-domain path SHOULD include the domain field for the domain
+common to all elements in the path. The value of the path field can be 
anything
+but MUST NOT include any trailing spaces. If it includes the domain field, 
the
+value of the path field MUST be unique inside the domain. If the domain field
+is not included, the value of the path field MUST be globally unique.
+
+Inter-domain Path
+
+The path field MUST be used for any named path that passes through multiple
+domains. An inter-domain path MUST not include any fields except path. The
+value of the path field can be anything but MUST be globally unique and MUST
+NOT include any trailing spaces. 
+
+Network
+
+The network field is used to describe arbitrary groupings of network 
elements.
+If all the elements in the network fall under the same domain, the identifier
+SHOULD include the domain field. If the identifier includes the domain field,
+the field MUST contain the same identifier as the domain containing all the
+elements. The value of the network field can be anything but MUST NOT include
+any trailing spaces. If it includes the domain field, the value of the 
network
+field MUST be unique inside the domain. If the domain field is not included,
+the value of the network field MUST be globally unique.
+
+
+
+
+
 The Topology identifiers have been designed to be flexible, be very explicit 
in
 its meaning and still be reasonably human-readable. The identifier builds off
 the standard URN format described in RFC 2141. Thus, each ID begins with:
 
-<pre>
 urn:ogf:network:
-</pre>
 
 The format for the rest of the message consists of a series of name/value 
pairs
 separated by colons. The ordering of the name/value pairs is important 
because
@@ -115,24 +187,22 @@
 general portion (the domain) and proceeds to the most specific portion of 
each
 id. 
 
-A domain id might look like this:
+urn:ogf:network:domain=237
 
-urn:ogf:network:domain=Internet2
-
 Nodes, Paths, Networks and Bidirectional Links can come immediately 
following the domain. For example:
 
-urn:ogf:network:domain=Internet2:node=packrat
-urn:ogf:network:domain=Internet2:link=WASH to ATLA OC192
-urn:ogf:network:domain=Internet2:path=Mark's Path
-urn:ogf:network:domain=Internet2:network=192.168.0.0%2F24
+urn:ogf:network:domain=237:node=packrat
+urn:ogf:network:domain=237:link=WASH to ATLA OC192
+urn:ogf:network:domain=237:path=Mark's Path
+urn:ogf:network:domain=237:network=192.168.0.0%2F24
 
 Below a node can exist ports. For example:
 
-urn:ogf:network:domain=Internet2:node=packrat:port=eth0
+urn:ogf:network:domain=237:node=packrat:port=eth0
 
 Below a port can exist a unidirectional link corresponding to the link that 
can be written via this port. For example:
 
-urn:ogf:network:domain=Internet2:node=packrat:port=eth0:link=1
+urn:ogf:network:domain=237:node=packrat:port=eth0:link=1
 
 Paths and Network can be global in scope as well as beneath a domain. For 
example:
 
@@ -150,14 +220,14 @@
 urn:ogf:network:network=*
 
 Top-Level Domain IDs:
-urn:ogf:network:domain=Internet2:node=* 
-urn:ogf:network:domain=Internet2:link=*
-urn:ogf:network:domain=Internet2:path=*
-urn:ogf:network:domain=Internet2:network=*
+urn:ogf:network:domain=237:node=* 
+urn:ogf:network:domain=237:link=*
+urn:ogf:network:domain=237:path=*
+urn:ogf:network:domain=237:network=*
 
 Node-specific IDs:
-urn:ogf:network:domain=Internet2:node=packrat:port=*
-urn:ogf:network:domain=Internet2:node=packrat:port=eth0:link=*
+urn:ogf:network:domain=237:node=packrat:port=*
+urn:ogf:network:domain=237:node=packrat:port=eth0:link=*
 
 Each element of the id is encoded using the URN syntax as stated in RFC 2141.
 This requires encoding the characters as follows:
@@ -177,13 +247,13 @@
 
 The actual contents of each of the id's elements can be anything. The domain 
id element will be registered with an LS to allow an individual with an ID to 
easily find where to obtain information on the ID while minimizing the amount 
of information needed to be store in the LS.
 
-To look up information on an ID, a user would extract the domain id from the 
full id(e.g. if the user has the ID 
"urn:ogf:network:domain=Internet2:node=packrat:port=eth0", the domain id 
would be "urn:ogf:network:domain=Internet2"). The user would then connect to 
the LS (an easier task once the Multi-LS is widely available) and lookup the 
Topology MA using a query like:
+To look up information on an ID, a user would extract the domain id from the 
full id(e.g. if the user has the ID 
"urn:ogf:network:domain=237:node=packrat:port=eth0", the domain id would be 
"urn:ogf:network:domain=237"). The user would then connect to the LS (an 
easier task once the Multi-LS is widely available) and lookup the Topology MA 
using a query like:
 
 declare namespace nmwg="http://ggf.org/ns/nmwg/base/2.0/";;
 
 for $data in /nmwg:data
   let $metadata_id := $data/@metadataIdRef
-  where 
$data//*:domain[@id="urn:ogf:network:domain=Internet2"]
+  where 
$data//*:domain[@id="urn:ogf:network:domain=237"]
         and 
$data//nmwg:eventType[text()="http://ggf.org/ns/nmwg/topology/query/xquery/20070809";]
   return 
/nmwg:metadata[@id=$metadata_id]