LIGO_LW XML Format Guidelines

The LIGO_LW( LIGO lightweight ) XML format is a subset of the XML( Extensible Markup Language ). The Lightweight API was designed to allow object-model access and customizing of the LIGO_LW format documents. More information about this format can be found in LIGO-T990023-01.

There are few guidelines to follow in creating LIGO_LW format documents which Lightweight API can process successfully.

• LIGO_LW Header.
• LIGO_LW wrapping container.
• LIGO_LW elements.

Guidelines for the LIGO_LW header.

Each XML document has a prolog that can contain an XML declaration followed by a document type declaration( known as DTD ).

• The XML declaration.

<?xml version="1.0"?> 
           

• The DTD( document type declaration ).

<!DOCTYPE LIGO_LW[
<!ELEMENT LIGO_LW ((LIGO_LW|Comment|Param|Table|Array|Stream|IGWDFrame|AdcData|Time)*)>
<!ATTLIST LIGO_LW
          Name CDATA #IMPLIED
          Type CDATA #IMPLIED>

<!ELEMENT Comment (#PCDATA)>

<!ELEMENT Param (#PCDATA|Comment)*>
<!ATTLIST Param 
          Name CDATA #IMPLIED
          Type CDATA #IMPLIED
          Unit CDATA #IMPLIED>

<!ELEMENT Table (Comment?,Column*,Stream?)>
<!ATTLIST Table 
          Name CDATA #IMPLIED
          Type CDATA #IMPLIED>

<!ELEMENT Column EMPTY>
<!ATTLIST Column
          Name CDATA #IMPLIED
          Type CDATA #IMPLIED
          Unit CDATA #IMPLIED>

<!ELEMENT Array (Dim*,Stream?)>
<!ATTLIST Array 
          Name CDATA #IMPLIED
          Type CDATA #IMPLIED>

<!ELEMENT Dim (#PCDATA)>
<!ATTLIST Dim 
          Name  CDATA #IMPLIED
          Units CDATA #IMPLIED>

<!ELEMENT Stream (#PCDATA)>
<!ATTLIST Stream 
          Name      CDATA #IMPLIED
          Type      (Remote|Local) "Local"
          Delimiter CDATA ","
          Encoding  CDATA #IMPLIED
          Content   CDATA #IMPLIED>

<!ELEMENT IGWDFrame ((Comment|Param|Time|Detector|AdcData|LIGO_LW|Stream?|Array)*)>
<!ATTLIST IGWDFrame 
          Name CDATA #IMPLIED>

<!ELEMENT Detector ((Comment|Param|LIGO_LW)*)>
<!ATTLIST Detector 
          Name CDATA #IMPLIED>

<!ELEMENT AdcData ((AdcData|Comment|Param|Time|LIGO_LW|Array)*)>
<!ATTLIST AdcData 
          Name CDATA #IMPLIED>

<!ELEMENT Time (#PCDATA)>
<!ATTLIST Time 
          Name CDATA #IMPLIED
          Type (GPS|Unix|ISO-8601) "ISO-8601">
]>
   
         

Guidelines for the LIGO_LW wrapping container.

Document content has to be enclosed into wrapping LIGO_LW container.

<LIGO_LW name="optional_name"> 
    ....
</LIGO_LW>    
           

Guidelines for specific LIGO_LW elements.

• Table - LIGO_LW representation of LDAS Metadata Table

Table element

<Table Name="name">
   <Column Name="name1" Type="type1"/>
   <Column Name="name2" Type="type2"/>
   <Column Name="name3" Type="type3"/>
   <Stream Name="name" Type="locationType" Delimiter=",">
      ...delimiter separated stream data...
   </Stream>
</Table>
        

The following guidelines are to be observed for successful data insertion into ldas:

• Stream data should be comma separated.
• XML special characters should be substituted by their escaping characters: <( &lt; ), >( &gt; ), &( &amp; ).
• Each entry in 'char' or 'char_u' type of Column should meet the following requirements:
  1. Must be enclosed by double quotes if data is printable character: "a" or "&lt;".
  2. All numerical data should be octal based, preceded by backslash, i.e. \005.
  3. Special characters such as backslash and comma must be escaped with a backslash, i.e. "\\" or "\,".
• Each entry in 'ilwd:char_u' or 'ilwd:char' type of Column should meet the following requirements:
  1. Must be enclosed by double quotes: "\010\020\030\040\050" or "teststring" or "\007 \032 a b".
  2. All numerical data should be octal based, preceeded by backslash, i.e. \005.
  3. Must use space as a data delimiter within the entry if its data includes both characters and numeric values, i.e. "\007 \032 a # \037".
  4. Characters such as spaces, backslashes, and commas which are part of the data should be escaped with a backslash: "Some\ test\ data\,\ with\ \\escapes." is a LIGO_LW representation for "Some test data, with \escapes.".
  5. Null entry is represented by missing entry, i.e. <entry-before>,,<entry-after>.

'ilwd:char_u' type of Column is used mainly to store binary data. It accepts string data but converts it into its numerical representation.

The best format to store string data is 'lstring'.

• Columns of 'lstring' type:
  1. Is used to store string data.
  2. The following characters when appearing as part of the data must be escaped: comma.
  3. Empty entry is represented by two double quotes, such as: "".
  4. Null entry is represented by missing entry, i.e. <entry-before>,,<entry-after>.
• Naming convention for Table and Column Name attribute:

  The naming convention is the same as for ilwds;

  for Table: [ <project> ] <organization> <table>

  for Column: [ <group> ] <table> <column>

  Note that the project and group are optional. e.g. to insert into table dbmdctest, column seqid,

  <LIGO_LW Name="ligo:ldas:file"> 
  	<Table Name="dbmdctest:table"> 
  	<Column Name="dbmdctest:seqid" Type="int_4s"/> 
  	<Stream Name="dbmdctest:table" Type="Local" Delimiter=","> 
  	191,192,193 
  	</Stream> 
  	</Table> 
  </LIGO_LW> 

Example of a LIGO_LW Tables with null values

Example of an empty LIGO_LW Table.