perfsonar development work

Author: aaron
Date: 2007-09-16 23:38:02 -0400 (Sun, 16 Sep 2007)
New Revision: 270

Modified:
   trunk/nmwg/doc/nm-topo/nm-topo.xml
Log:
Cleanup the wording a bit in the path identifier section and include some 
examples.



Modified: trunk/nmwg/doc/nm-topo/nm-topo.xml
===================================================================
--- trunk/nmwg/doc/nm-topo/nm-topo.xml  2007-09-15 05:27:48 UTC (rev 269)
+++ trunk/nmwg/doc/nm-topo/nm-topo.xml  2007-09-17 03:38:02 UTC (rev 270)
@@ -63,200 +63,196 @@
          Reuse the namespace thing from NM.
        </t>
 
-       
 
+
   </section>
 
   <section id="identifiers" title="Identifiers">
 
+The network topology identifiers have been designed to be flexible, be 
explicit
+in their meaning and still be reasonably human-readable. 
+
 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 these identifiers from other
-identifying URNs in the OGF namespace. Thus, all identifiers MUST begin with
-"urn:ogf:network:".
+the ``ogf'' namespace is used to differentiate identifiers from others 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
-``=''.
+Each of these fields is separated by a ``:'' and each name and value is
+separated by a ``=''. The value MUST be encoded using the standard URN 
encoding
+scheme with one addition. The ``='' character MUST be encoded with the value
+``%D3''. 
 
-The only exception to this rule is when the identifier is ambiguous. If one
-wishes to construct an identifier, but does not know the address of the
-specific network element, 
+A single ``*'' may appear instead of a name/value field to connote an 
ambiguous
+identifier. If a '*' field is included, that field MUST be the last field in
+the identifier.
 
-The ordering of the name/value pairs goes from the most general network 
element
-to most specific network element.
+The name/value pairs MUST be ordered from most general network element to 
most
+specific network element. For example, the domain field MUST come before the
+node field which MUST come before the port field.
 
-Domain
+There MUST NOT exist repeated fields in the identifier.
 
-The domain field must be used to describe an administrative domain. The
+<section id="fields">
+<section title="Domain" id="fields_domain">
+
+The domain field MUST be used to identify 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.
+of this field MUST correspond to the AS number for the given network, and 
MUST
+NOT include any trailing spaces. Setting the value of this field to '*'
+connotes the domain is unknown. However, if the value of this field is
+'*', the field MUST be the last one in the identifier.
 
-Node
+urn:ogf:network:domain=237
+urn:ogf:network:domain=*
+</section>
 
-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. 
+<section title="Node" id="fields_node">
 
-Interfaces
+An identifier for a physical, logical or virtual device in a domain MUST
+include the domain and node fields. The domain field MUST be identicial to
+the domain field in the identifier for the domain containing the device. The
+value of the node field can be anything, but MUST be unique inside the domain
+and MUST NOT include any trailing spaces. The value SHOULD be a human 
readable
+description of the device. Setting the value of the node field to '*' 
connotes
+the device is unknown. If the value of the node field is '*', the field MUST 
be
+the last one in the identifier.
 
-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.
+Examples:
 
-Unidirectional Intra-domain/Inter-domain Links
+urn:ogf:network:domain=237:node=packrat
+urn:ogf:network:domain=237:node=207.75.164.10
+urn:ogf:network:domain=237:node=Joe's Machine
+urn:ogf:network:domain=237:node=Los Angeles NOC
+urn:ogf:network:domain=237:node=*
+</section>
 
-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.
+<section title="Interfaces" id="fields_interfaces">
 
-Bidirectional Domain Links
+An identifier for a physical, logical or virtual interface to a device MUST
+include the domain, node and port fields. The node and domain fields MUST be
+identicial to those fields in the identifier for the device containing the
+interface. The value of the port field can be anything, but MUST be unique
+inside the device and MUST NOT include any trailing spaces. The value SHOULD 
be a
+human readable description of the port. Setting the value of the port field 
to
+'*' connotes that the actual interface is unknown. However, if the value of 
the
+port field is '*', the field MUST be the last one in the identifier.
 
-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.
+Examples:
 
-Bidirectional Inter-domain Links
+urn:ogf:network:domain=237:node=packrat:port=eth0
+urn:ogf:network:domain=237:node=packrat:port=207.75.164.10
+urn:ogf:network:domain=237:node=packrat:port=*
+</section>
 
-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.
+<section title="Unidirectional Intra-domain/Inter-domain Links" 
id="fields_unilinks">
 
-Intra-domain Path
+An identifier for a unidirectional link MUST include the domain, node, port 
and
+link fields. The undirectional link belongs to the port which can write to 
the
+link. Thus, the domain, node and port fields in the identifier MUST be
+identical to those fields in the identifier for the port to which the link
+belongs. The value of the link field can be anything, but MUST be unique 
inside
+the port and MUST NOT include any trailing spaces. The value 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 
link
+field on the identifier for the other direction of the bidirectional link.
+Setting the value of the link field to '*' connotes that the actual link is
+unknown. 
 
-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.
+Examples:
 
-Inter-domain Path
+urn:ogf:network:domain=237:node=packrat:port=eth0:link=Link Between Packrat 
And Router1
+urn:ogf:network:domain=237:node=packrat:port=eth0:link=*
+</section>
 
-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. 
+<section title="Bidirectional Domain Links" id="fields_bidilinks">
 
-Network
+An identifier for a bidirectional link that begins and ends solely in one 
domain
+MUST include the link field. Since the link begins and ends in one domain, 
the identifier
+SHOULD include the domain field. If the domain field is included, it MUST be
+identical to the domain field in the identifier for the domain to which the 
link
+belongs. The value of the link field can be anything, but MUST be unique 
inside
+the domain if the domain field is included or globally unique if not and MUST
+NOT include any trailing spaces.  The value SHOULD be a human readable
+description of the link and SHOULD be the same value as the undirectional 
links
+that make up the link. Setting the value of the link field to '*' connotes 
the
+actual link is unknown.
 
-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.
+Examples:
 
+urn:ogf:network:domain=237:link=Link Between Packrat And Router1
+urn:ogf:network:domain=237:link=*
+</section>
 
+<section title="Bidirectional Inter-domain Links" id="fields_bidiinterlinks">
 
+An identifier for a bidirectional link that begins and ends in different
+domains MUST include ONLY the link field. The value of the link field can be
+anything, but MUST be globally unique and MUST NOT include any trailing 
spaces.
+The value SHOULD be a human readable description of the link and SHOULD be 
the
+same value as the undirectional links that make up the link.  Setting the 
value
+of the link field to '*' connotes the link is  unknown.  However, if the 
value
+of the link field is '*', the field MUST be the last one in the identifier.
 
+Examples:
 
-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:
+urn:ogf:network:link=Link Between Internet2 And ESNet
+urn:ogf:network:link=*
+</section>
 
-urn:ogf:network:
+<section title="Intra-domain Path" id="fields_intrapath">
 
-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
-that defines the hierarchical structure of the device. It starts with the 
most
-general portion (the domain) and proceeds to the most specific portion of 
each
-id. 
+An identifier for a named path that passes begins and ends inside a domain 
MUST
+include the path field. An intra-domain path identifier 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 
the
+identifier 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. Setting the value of the path field to 
'*'
+connotes the path is unknown.  However, if the value of the path field is 
'*',
+the field MUST be the last one in the identifier.
 
-urn:ogf:network:domain=237
+Examples:
 
-Nodes, Paths, Networks and Bidirectional Links can come immediately 
following the domain. For example:
+urn:ogf:network:domain=237:path=DRAGON Path From 207.75.164.10 to 
207.75.160.5
+urn:ogf:network:path=DRAGON Path From 207.75.164.10 to 207.75.160.5
+urn:ogf:network:path=*
+</section>
 
-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
+<section title="Inter-domain Path" id="fields_interpath">
 
-Below a node can exist ports. For example:
+An identifier for a named path which passes through multiple domains MUST
+include ONLY the path field. The value of the path field can be anything but
+MUST be globally unique and MUST NOT include any trailing spaces. Setting the
+value of the path field to '*' connotes the path is unknown. 
 
-urn:ogf:network:domain=237:node=packrat:port=eth0
+Examples:
 
-Below a port can exist a unidirectional link corresponding to the link that 
can be written via this port. For example:
+urn:ogf:network:path=DRAGON Path From 207.75.164.10 to 134.55.209.97
+urn:ogf:network:path=*
+</section>
 
-urn:ogf:network:domain=237:node=packrat:port=eth0:link=1
+<section title="Network" id="fields_network">
 
-Paths and Network can be global in scope as well as beneath a domain. For 
example:
+An identifier for an arbitrary grouping of network elements MUST include the
+network field.  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 domain field MUST contain the same value as the domain 
field
+in the identifier for the domain containing all the elements. The value of 
the
+network field can be anything but MUST NOT include any trailing spaces. If 
the
+identifier 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. Setting the value of the network field
+to '*' connotes the network is unknown. However, if the value of the network 
field
+is '*', the field MUST be the last one in the identifier.
 
-urn:ogf:network:path=anna-11537-176
-urn:ogf:network=128.4.0.0%2F16
+Examples:
 
-Partially-Known IDs:
-
-Replace the unknown element of the id with a '*'. It is only applicable, 
however, to the final
-piece of the ID. 
-
-Global domain, path and network IDs
-urn:ogf:network:domain=*
-urn:ogf:network:path=*
+urn:ogf:network:domain=237:network=207.75.164.0%2F24
+urn:ogf:network:network=207.0.0.0%2F8
 urn:ogf:network:network=*
+</section>
 
-Top-Level Domain IDs:
-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=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:
-
-{| border="1" cellpadding="5" align="center"
- | : || %3A
- |-
- | / || %2F
- |-
- | ? || %3F
- |-
- | # || %23
- |-
- | % || %25
- |}
-
-
-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=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=237"]
-        and 
$data//nmwg:eventType[text()="http://ggf.org/ns/nmwg/topology/query/xquery/20070809";]
-  return 
/nmwg:metadata[@id=$metadata_id]
-
   </section>
 
   <section id="basic_elements" title="Basic Elements">