How to create schema/instance files
-----------------------------------


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:
	
	http://en.wikipedia.org/wiki/XML#Quick_syntax_tour
	
	Additionally, consult the numerous examples 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).
		  
		- 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.
		
		  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:
		
		LS Register Request:
		--------------------
		
		<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>
		      
		      <!-- What kind of data does this new service want to advertise?  
		           A topology service would advertise links or points, a ping
			   MP would advertise pairs of ping data.  This is the most
			   important part of this message, so look at other examples 
			   to see what can be reused, or propose something new. -->
		      
		    </nmwg:metadata>
		    
		    <!-- more MD blocks, perhaps different from the
		         first if applicable -->
		  
		  </nmwg:data>
		</nmwg:message>
		
		*NOTE: See examples such as the netflow LS registration messages.


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

		<nmwg:message>  
		  <nmwg:metadata id="m1">
		    <nmwg:key>
		      <!-- this will be a standard response from the LS -->
		    </nmwg:key>
		  </nmwg:metadata>
		  
		  <nmwg:data id="d1" metadataIdRef="m1" >
		    <nmwg:datum>result code response</datum>		  
		  
		    <!-- this will be a standard response from the LS -->
		  
		  </nmwg:data>
		</nmwg:message>

		*NOTE: See examples such as the netflow LS registration messages.
		
		
		
		Client Request:
		---------------
		<nmwg:message>  
		  <nmwg:metadata id="m1">
		    <!-- Information registered in 'LS Register Request' will 
		         be the basic pattern that is requested here. It may be 
			 partially complete, or totally complete (depending on 
			 your service) -->
		  </nmwg:metadata>
		  
		  <nmwg:data id="d1" metadataIdRef="m1" />

		  <!-- a data trigger -->

		</nmwg:message>		
		
		*NOTE: See examples such as the rrdMA messages.


		
		Client Response:
		----------------
		<nmwg:message>  
		  <nmwg:metadata id="m1">
		    <!-- Information registered in 'LS Register Request' will 
		         be the basic pattern that is requested here. This 
			 should be totally complete. -->
		  </nmwg:metadata>
		  
		  <nmwg:data id="d1" metadataIdRef="m1">
		  
		    <nmwg:datum ... />
		    
		    <!-- or -->
		    
		    <nmwg:metadata ... />
		    
		    <!-- return 'data' from the service.  This part is also
		         important and specific for each service. -->
		  
		  </nmwg:data>

		</nmwg:message>				


		*NOTE: See examples such as the rrdMA messages.		

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.
	
	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:
	
	<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. 

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).
	
	*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:
	
	
	#!/bin/sh
	
	JAVA=/PATH/TO/JAVA
	TRANG=./verify/trang.jar
	JING=./verify/jing.jar
	MSV=./verify/msv.jar

	SCHEMA_DIR=rnc
	INSTANCE_DIR=example_instances

	# test ping instance
	rm -f rnc/*rng rnc/*xsd

	$JAVA -jar $TRANG -I rnc -O rng $SCHEMA_DIR/SCHEMA_NAME.rnc $SCHEMA_DIR/SCHEMA_NAME.rng
	$JAVA -jar $TRANG -I rng -O xsd $SCHEMA_DIR/SCHEMA_NAME.rng $SCHEMA_DIR/SCHEMA_NAME.xsd
	
	$JAVA -jar $MSV -warning $SCHEMA_DIR/SCHEMA_NAME.rng $INSTANCE_DIR/INSTANCE_NAME1.xml
	$JAVA -jar $JING $SCHEMA_DIR/SCHEMA_NAME.rng $INSTANCE_DIR/INSTANCE_NAME1.xml	
	
	$JAVA -jar $MSV -warning $SCHEMA_DIR/SCHEMA_NAME.rng $INSTANCE_DIR/INSTANCE_NAME2.xml
	$JAVA -jar $JING $SCHEMA_DIR/SCHEMA_NAME.rng $INSTANCE_DIR/INSTANCE_NAME2.xml	
	
	# ... 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.
	
-----------------------------------------------------------------------------------------
Jason Zurawski
zurawski@eecis.udel.edu
03/08/07