perfsonar-dev - nmwg: r388 - trunk/nmwg/schema

Subject: perfsonar development work

List archive

nmwg: r388 - trunk/nmwg/schema

From:
To: ,
Subject: nmwg: r388 - trunk/nmwg/schema
Date: Mon, 10 May 2010 13:05:38 -0400

Author: zurawski
Date: 2010-05-10 13:05:38 -0400 (Mon, 10 May 2010)
New Revision: 388

Modified:
trunk/nmwg/schema/README.txt
Log:
Updating README (since it is 3 years old...)

-jason

Modified: trunk/nmwg/schema/README.txt
===================================================================
--- trunk/nmwg/schema/README.txt 2009-03-04 10:20:24 UTC (rev 387)
+++ trunk/nmwg/schema/README.txt 2010-05-10 17:05:38 UTC (rev 388)
@@ -2,195 +2,204 @@
-----------------------------------

-1). Model (as detailed as possible) the interactions that will
- occur between the system and other actors (the LS, clients,
- other entities in pS) in XML markup. A simple tutorial on
- XML can be found here:
+1). Model (as detailed as possible) the interactions that will occur
between the
+ system and other actors (the LS, clients, other entities in perfSONAR) in
+ XML markup. A simple tutorial on XML can be found here:

- http://en.wikipedia.org/wiki/XML#Quick_syntax_tour
+ http://en.wikipedia.org/wiki/XML

- Additionally, consult the numerous examples to get a
- feel of how other services have been developed using XML.
+ Additionally, consult the numerous examples from the NMWG and
perfsONAR:
+
+ -
http://anonsvn.internet2.edu/svn/nmwg/trunk/nmwg/schema/example_instances/
+ -
http://svn.geant.net/GEANT/SA2/ps-java-services/trunk/perfsonar/schema/example-instances/perfSONAR/
+
+ to get a feel of how other services have been developed using XML.

- - Each interaction should consist of a request
- and a response. Make each interaction a separate
- file.
-
- - Start with older examples to get a feel of what
- items you need to include in your instances. The
- most important part is to capture the unique
- requirements of a particular service (ex. netflow uses
- 'router' descriptions; this is something not modeled
- anywhere in previous pS services. A full description
- of what a 'router' is and what it may contain is
- necessary).
+ - Each interaction should consist of a request and a
response. Make
+ each interaction a separate file. For example consider the
following
+ example of how to construct the "EchoRequest" and
"EchoResponse"
+ messages:

+
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-SNMPMA/etc/requests/EchoRequest.xml
+
+ - Start with older examples to get a feel of what items you
need to
+ include in your instances. The most important part is to
capture the
+ unique requirements of a particular service (ex. netflow
uses 'router'
+ descriptions; this is something not modeled anywhere in
previous
+ perfSONAR services. A full description of what a 'router'
is and what
+ it may contain is necessary).
+
- Give descriptive names to the elements.

- - Lay out what potential values each element may have
- (if it can only be 1 or two string values, name
- them, if it is all floating point numbers, say that.
+ - Lay out what potential values each element may have (if it
can only
+ be 1 or two string values, name them, if it is all floating
point
+ numbers, say that.

- For example, when we specify an interface address, we
- want to make sure we are accepting only two types:
+ For example, when we specify an interface address, we want
to make
+ sure we are accepting only two types:

<ifAddress type="IPv4 | IPv6">address string</ifAddress>

- Example:

- Consider a system that will register it's presence to
- the LS, and accept client requests for data. There
- should be 4 files:
+ Consider a system that will register it's presence to the
LS, and
+ accept client requests for data. There should be 4 files:

- LS Register Request:
- --------------------
+ LS Register Request:
+ --------------------

- <nmwg:message>
- <nmwg:metadata id="m1">
- <psservice:service>
- <-- Service description (from service.rnc) for this
system -->
- </psservice:service>
- </nmwg:metadata>
+ <nmwg:message>
+ <nmwg:metadata id="m1">
+ <psservice:service>
+ <-- Service description (from service.rnc) for this
system -->
+ </psservice:service>
+ </nmwg:metadata>

- <nmwg:data id="d1" metadataIdRef="m1" >
- <nmwg:metadata>
+ <nmwg:data id="d1" metadataIdRef="m1" >
+ <nmwg:metadata>

- 
+ 

- </nmwg:metadata>
+ </nmwg:metadata>

- 
+ 

- </nmwg:data>
- </nmwg:message>
+ </nmwg:data>
+ </nmwg:message>

- *NOTE: See examples such as the netflow LS registration
messages.
-
-
+ * NOTE: See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-LookupService/etc/requests/hLS/LSRegisterRequest.xml

- LS Register Response:
- ---------------------
+ LS Register Response:
+ ---------------------

- <nmwg:message>
- <nmwg:metadata id="m1">
- <nmwg:key>
- 
- </nmwg:key>
- </nmwg:metadata>
+ <nmwg:message>
+ <nmwg:metadata id="m1">
+ <nmwg:key>
+ 
+ </nmwg:key>
+ </nmwg:metadata>

- <nmwg:data id="d1" metadataIdRef="m1" >
- <nmwg:datum>result code response</datum>
+ <nmwg:data id="d1" metadataIdRef="m1" >
+ <nmwg:datum>result code response</datum>

- 
+ 

- </nmwg:data>
- </nmwg:message>
+ </nmwg:data>
+ </nmwg:message>

- *NOTE: See examples such as the netflow LS registration
messages.
+ * NOTE: See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-LookupService/etc/requests/hLS/LSRegisterRequest.xml
+

-
- Client Request:
- ---------------
- <nmwg:message>
- <nmwg:metadata id="m1">
- 
- </nmwg:metadata>
+ Client Request:
+ ---------------
+ <nmwg:message>
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>

- <nmwg:data id="d1" metadataIdRef="m1" />
+ <nmwg:data id="d1" metadataIdRef="m1" />

- 
+ 

- </nmwg:message>
+ </nmwg:message>

- *NOTE: See examples such as the rrdMA messages.
+ * NOTE: See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-SNMPMA/etc/requests/MetadataKeyRequest-1.xml
+ See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-SNMPMA/etc/requests/SetupDataRequest-1.xml

-

- Client Response:
- ----------------
- <nmwg:message>
- <nmwg:metadata id="m1">
- 
- </nmwg:metadata>
+ Client Response:
+ ----------------
+ <nmwg:message>
+ <nmwg:metadata id="m1">
+ 
+ </nmwg:metadata>

- <nmwg:data id="d1" metadataIdRef="m1">
+ <nmwg:data id="d1" metadataIdRef="m1">

- <nmwg:datum ... />
+ <nmwg:datum ... />

- 
+ 

- <nmwg:metadata ... />
+ <nmwg:metadata ... />

- 
+ 

- </nmwg:data>
+ </nmwg:data>

- </nmwg:message>
+ </nmwg:message>

- *NOTE: See examples such as the rrdMA messages.
+ * NOTE: See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-SNMPMA/etc/requests/MetadataKeyRequest-1.xml
+ See also:
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-SNMPMA/etc/requests/SetupDataRequest-1.xml

-2). Once you have your instances, fill in namespaces and make them as
- 'correct' as possible. Use comments to describe your intentions. An
- example of a namespace for the 'ping' tool would be:
+
+
+
+2). Once you have your instances, fill in namespaces and make them as
'correct'
+ as possible. Use comments to describe your intentions. An example of a
+ namespace for the 'ping' tool would be:

"http://ggf.org/ns/nmwg/tools/ping/2.0/";

- A namespace is basically a URI meant to describe a 'unique' set
- of objects that live in the XML world. Assigning a new URI to a
- set of objects sets them aside as being in a controlled environment.
+ A namespace is basically a URI meant to describe a 'unique' set of
objects
+ that live in the XML world. Assigning a new URI to a set of objects
sets
+ them aside as being in a controlled environment.

- The namespace you select does not have to correct right of the bat, we
- will help you with this. The important part is to select something,
- and then assign a 'prefix' to each element. A prefix is used like
this:
+ The namespace you select does not have to correct right of the bat,
we will
+ help you with this. The important part is to select something, and
then
+ assign a 'prefix' to each element. A prefix is used like this:

<ping:subject xmlns:ping="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />

- We assign the namespace to the prefix 'ping' and we can then use this
- as a shortcut to indicate membership. It is important to also note
- this similarity:
+ We assign the namespace to the prefix 'ping' and we can then use this as
a
+ shortcut to indicate membership. It is important to also note this
+ similarity:

- <ping:subject xmlns:ping="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />
- <foo:subject xmlns:foo="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />
- <bar:subject xmlns:bar="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />

+ <ping:subject xmlns:ping="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />
+ <foo:subject xmlns:foo="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />
+ <bar:subject xmlns:bar="http://ggf.org/ns/nmwg/tools/ping/2.0/"; />

Despite having different prefixes, they all map to the same
namespace,
therefore each of these objects would be semantically (although not
syntactically) similar.

- Namespaces and prefixes are a complex topic, we will be there to help
- anyone who needs it, but please make a good effort.
+ Namespaces and prefixes are a complex topic, we will be there to help
anyone
+ who needs it, but please make a good effort.

-3). Create a schema file, it is best to start with something simple like
- 'ping.rnc' as a base. This simple file builds off of the
'nmbase.rnc',
- 'result.rnc', 'nmtopo.rnc', 'nmtopo_v3.rnc', and 'nmtime.rnc' files
- (which are the basic building blocks of data representation). You
will
- need to also include a reference to 'service.rnc' (for service
- descriptions).
+3). Create a schema file, there are examples here:
+
+ https://svn.internet2.edu/svn/nmwg/trunk/nmwg/schema/rnc/
+
+ It is best to start with something simple like 'ping.rnc' as a base.
This
+ simple file builds off of the 'nmbase.rnc', 'result.rnc', 'nmtopo.rnc',
+ 'nmtopo_v3.rnc', and 'nmtime.rnc' files (which are the basic building
blocks
+ of data representation). You will need to also include a reference to
+ 'service.rnc' (for service descriptions - used in LS registration).
+ Examples of LS registration messages can be found here:
+
+
http://anonsvn.internet2.edu/svn/perfSONAR-PS/trunk/perfSONAR_PS-LookupService/etc/requests/hLS/

- *NOTE 'sonar.rnc' is not really a good place to start modeling a
- schema. It is a very general file, meant to lay out a very general
- structure for messages. Starting with a specific schema (such as
iperf
- or ping) will help you model the service to a more fine level.
+ * NOTE 'sonar.rnc' is not really a good place to start modeling a
schema.
+ It is a very general file, meant to lay out a very general
structure for
+ messages. Starting with a specific schema (such as iperf or ping)
will
+ help you model the service to a more fine level.

4). Follow other schema files for syntax hints, or read:

http://books.xmlschemata.org/relaxng/page2.html

- Although reading the book is not really necessary.
-
5). After your schema and instance files are prepared, try to manually
verify them. Take a look at the 'test*sh' shell scripts, or make your
own:
@@ -221,28 +230,11 @@
# ... more instances

- There may be errors, this is ok (there WILL be warnings, they can be
ignored). See if
- you can fix the errors as best as you can, if you get stuck this is
ok too.
-
-6). Even if you have correct schema and instance files (or lots of
errors) you need to file
- a 'bug' on bugzilla so that the experts can take a look and help you
out:
-
- https://bugzilla.perfsonar.net/
-
- Or:
-
- http://wiki.perfsonar.net/jra1-wiki/index.php/Bugzilla_details
-
- If you are not familiar with the bugzilla layout. The product in
question you
- wish to file the bug with will be:
-
- https://bugzilla.perfsonar.net/enter_bug.cgi?product=Schema
-
- Attach your files (or put the URL of the files if they are already in
svn), and CC
- as many other people as necessary. The Schema dev. team will work
with you to finalize
- the details.
-
+ There may be errors, this is OK to start, but they need to be
addressed.
+ There WILL be warnings, they can be ignored.
+

-----------------------------------------------------------------------------------------
Jason Zurawski
-
-03/08/07
+
+
+Last Updated: Mon May 10 12:17:50 EDT 2010

nmwg: r388 - trunk/nmwg/schema, svnlog, 05/10/2010

List archive

nmwg: r388 - trunk/nmwg/schema