C.2  
 

XML Data Interchange Format

This appendix contains examples of yosokumo protocol documents formatted in the XML DIF. The canonical specification for the documents is given in ASN.1 in Appendix C.1. In general, the following conventions apply:

  1. XML protocol documents are encoded in either UTF-8 or US-ASCII.
  2. Each ASN.1 production is represented by an XML root element.
  3. Each subproduction corresponds to a nested XML element.
  4. Terminal fields are (generally) represented as XML attributes.
  5. SET OF or SEQUENCE OF attributes that may be repeated are represented as repeating elements.
  6. When an attribute takes one of a set of enumerated values, the value in the XML element or attribute is set to a string containing the mnemonic value from the canonical list, not the numeric value.
  7. Numeric values may be formatted in integer, decimal or exponential representation (most common variants are accepted) as appropriate for their type; positive numbers may include an optional leading '+' sign.
  8. All time values are RFC 3339 formatted as 'YYYY-MM-DDThh:mm:ss.nnn', where 'nnn' represents milliseconds.
  9. When a 'null' value is permitted by the specification, the XML attribute is set to attribute='' or the XML element is set to: <element/>

Normally, to maintain conformity with the XML specification and to reduce bandwidth usage, an XML document contains no unecessary whitespace or control characters. Also, by default, documents sent by the server contain the namespace declaration xmlns:yx='http://yosokumo.ws/xml' and contain elements and attributes namespace prefixed by yx. For example, a study document is formatted:

<?xml version='1.0' encoding='UTF-8'?><yx:study xmlns:yx='http://yosokumo.ws/xml' yx:study_identifier='0123456789ABCDEF' yx:study_name='Study name' yx:type='number' yx:status='running' yx:location='http://yosokumo.ws/study.0123456789ABCDEF'><yx:owner yx:user_identifier='0123456789ABCDEF' yx:user_name='User name'/><yx:table yx:location='http://yosokumo.ws/study.0123456789ABCDEF/table'/><yx:model yx:location='http://yosokumo.ws/study.0123456789ABCDEF/model'/><yx:panel yx:location='http://yosokumo.ws/study.0123456789ABCDEF/panel'/><yx:roster yx:location='http://yosokumo.ws/study.0123456789ABCDEF/roster'/></yx:study>

To obtain a document from the server with a namespace prefix other than yx, clients should include the x-yosokumo-namespace-prefix header containing the desired prefix in their request:

	x-yosokumo-namespace-prefix: new

To obtain a document from the server with no namespace declaration or prefixes, clients should set the desired prefix to (none) in the x-yosokumo-namespace-prefix header for the request:

	x-yosokumo-namespace-prefix: (none)

Clients may include or omit both namespace declarations and prefixes in documents sent to the server.

Below, documents are formatted for exposition with linebreaks and tabs that would not ordinarily appear, and without namespace declarations or prefixes. In addition, the documents here generally are shown with all attributes present. Consult the canonical specification for information about optional attributes and permitted values; consult the main text for contexts in which attributes are optional (or required) and the meaning of the permitted values.

Catalog and study documents:

<catalog user_identifier='0123456789ABCDEF' user_name='User One' location='http://yosokumo.ws/user.0123456789ABCDEF/catalog'>
	<study study_identifier='FEDCBA9876543210' study_name='Trial Study' type='class' status='running' visibility='public' location='http://yosokumo.ws/study.FEDCBA9876543210'>
		<owner user_identifier='AAAABBBBCCCCDDDD' user_name='User One'/>
		<table location='http://yosokumo.ws/study.FEDCBA9876543210/table'/>
		<model location='http://yosokumo.ws/study.FEDCBA9876543210/model'/>
		<panel location='http://yosokumo.ws/study.FEDCBA9876543210/panel'/>
		<roster location='http://yosokumo.ws/study.FEDCBA9876543210/roster'/>
	</study>
	<study study_identifier='ABCDEF0123456789' study_name='Panel Study' type='number' status='paused' visibility='private' location='http://yosokumo.ws/study.ABCDEF0123456789'>
		<owner user_identifier='1111222233334444' user_name='User Two'/>
		<table location='http://yosokumo.ws/study.ABCDEF0123456789/table'/>
		<model location='http://yosokumo.ws/study.ABCDEF0123456789/model'/>
		<panel location='http://yosokumo.ws/study.ABCDEF0123456789/panel'/>
		<roster location='http://yosokumo.ws/study.ABCDEF0123456789/roster'/>
	</study>
</catalog>

<study study_identifier='FEDCBA9876543210' study_name='Trial Study' type='class' status='running' visibility='public' location='http://yosokumo.ws/study.FEDCBA9876543210'>
	<owner user_identifier='AAAABBBBCCCCDDDD' user_name='User One'/>
	<table location='http://yosokumo.ws/study.FEDCBA9876543210/table'/>
	<model location='http://yosokumo.ws/study.FEDCBA9876543210/model'/>
	<panel location='http://yosokumo.ws/study.FEDCBA9876543210/panel'/>
	<roster location='http://yosokumo.ws/study.FEDCBA9876543210/roster'/>
</study>

Roster and role documents:

<roster study_identifier='ABCDEF0123456789' study_name='Panel Study' location='http://yosokumo.ws/study.ABCDEF0123456789/roster'>
	<role location='http://yosokumo.ws/user.1111222233334444/study.ABCDEF0123456789/role'>
		<roleholder user_identifier='1111222233334444' user_name='User Two'/>
		<privileges get_study='true' delete_study='true' get_roster='true' post_roster='true' get_role='true' put_role='true' delete_role='true' get_panel='true' get_control='true' put_control='true' post_table='true' get_model='true' post_model='true'/>
		<study study_identifier='ABCDEF0123456789' study_name='Panel Study'/>
	</role>
	<role location='http://yosokumo.ws/user.AAAABBBBCCCCDDDD/study.ABCDEF0123456789/role'>
		<roleholder user_identifier='AAAABBBBCCCCDDDD' user_name='User One'/>
		<privileges get_study='true' delete_study='false' get_roster='false' post_roster='false' get_role='false' put_role='false' delete_role='false' get_panel='false' get_control='false' put_control='false' post_table='false' get_model='true' post_model='true'/>
		<study study_identifier='ABCDEF0123456789' study_name='Panel Study'/>
	</role>
</roster>

<role location='http://yosokumo.ws/user.AAAABBBBCCCCDDDD/study.ABCDEF0123456789/role'>
	<roleholder user_identifier='AAAABBBBCCCCDDDD' user_name='User One'/>
	<privileges get_study='true' delete_study='false' get_roster='' post_roster='false' get_role='' put_role='false' delete_role='' get_panel='false' get_control='' put_control='false' post_table='' get_model='true' post_model='true'/>
	<study study_identifier='ABCDEF0123456789' study_name='Panel Study'/>
</role>

Panel and controls:

<panel study_identifier='ABCDEF0123456789' location='http://yosokumo.ws/study.ABCDEF0123456789/panel'>
	<control location='http://yosokumo.ws/study.ABCDEF0123456789/panel.study_name'><study_name>Panel Study</study_name></control>
	<control><type>number</type></control>
	<control location='http://yosokumo.ws/study.ABCDEF0123456789/panel.status'><status>paused</status></control>
	<control location='http://yosokumo.ws/study.ABCDEF0123456789/panel.visibility'><visibility>private</visibility></control>
	<control><block_count>64</block_count></control>
	<control><cell_count>4194304</cell_count></control>
	<control><prospect_count>0</prospect_count></control>
	<control><creation_time>2009-10-24T01:04:16.064Z</creation_time></control>
	<control><latest_block_time>2010-11-29T23:53:59.199Z</latest_block_time></control>
	<control><latest_prospect_time/></control>
</panel>

<control study_identifier='ABCDEF0123456789'>
	<status>paused</status>
</control>

<control study_identifier='ABCDEF0123456789'>
	<visibility>private</visibility>
</control>

<control study_identifier='ABCDEF0123456789'>
	<study_name>Panel Study</study_name>
</control>

Block and specimen documents:

<block/>

<block type='empty'/>

<block study_identifier='ABCDEF0123456789' type='row'>
	<specimen key='101' weight='1' type='empty'>
		<cell name='1'/>
		<cell name='2' type='natural' value='17365'/>
		<cell name='3' type='integer' value='+528'/>
		<cell name='4' type='real' value='-93.37'/>
		<cell name='5' type='special' value='55'/>
		<cell name='6' type='empty'/>
	</specimen>
	<specimen key='102' weight='3' status='active' type='integer' value='+151'>
		<cell name='1' type='natural' value='0'/>
		<cell name='2' type='natural' value='4782'/>
		<cell name='3' type='integer' value='-4092'/>
		<cell name='4' type='real' value='+218l.92'/>
		<cell name='5' type='special' value='50'/>
		<cell name='6' type='natural' value='1'/>
	</specimen>
</block>

<block type='column'>
	<predictor name='1' status='active' type='categorical' level='nominal'/>
	<predictor name='2' status='active' type='categorical' level='ordinal'/>
	<predictor name='3' status='active' type='continuous' level='interval'/>
	<predictor name='4' status='active' type='continuous' level='ratio'/>
	<predictor name='9' status='inactive'/>
</block>

<block study_identifier='ABCDEF0123456789' type='column'>
	<predictor name='4'>
		<cell key='1001' type='integer' value='+7'/>
		<cell key='1002' type='real' value='+4.3'/>
		<cell key='1003' type='integer' value='+5'/>
		<cell key='1004' type='real' value='-10.01'/>
	</predictor>
</block>

<specimen key='101' type='real' value='+1.0123'/>

<specimen key='102' weight='3' status='active' type='integer' value='+151'>
	<cell name='1' type='natural' value='0'/>
	<cell name='2' type='natural' value='4782'/>
	<cell name='3' type='integer' value='-4092'/>
	<cell name='4' type='real' value='+218l.92'/>
	<cell name='5' type='special' value='50'/>
</specimen>

A message:

<message type='error'><text>Message body.</text></message>