How to Use PEF XML

PEF XML is intended to be a format for exchanging data that is stored in, or mapped to, Epicentre. It has been developed with the intent of describing this mapping with a few, simple rules.

The purpose of this document is to give a step-by-step procedure to generate the XML. The result of following these rules should lead to a consistent XML that can be readily produced and interpreted.

Step 1: Know your data

In order to do the mapping, you must know how your data maps to Epicentre:

• Entity name
• Attribute name
• Data type

In order to help with this effort, the leaf_ent_att.txt file may be downloaded. This file is a four column list that contains the entity name, attribute name, underlying data type, and ndt (or instance reference) information. The first three columns are the information mentioned above, but the fourth column may be useful also.

Step 2: Write the header for the XML file

In the simplest form, the header lines of the XML file are the following:

  <?xml version="1.0"?>

  <!DOCTYPE defineIDs [
  <!ATTLIST uomReference uid ID #REQUIRED>
  <!ATTLIST UnitOfMeasure uid ID #REQUIRED>
     ]>

  <PEFExchange 
       xmlns="http://www.posc.org/pef"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.posc.org/pef
                  http://www.posc.org/pef/peftypes.xsd">

These lines do the following (You do not need to understand these):

• Define this to be an xml file
• Define the ID attribute in the ENTITY, and the uid attribute of uomReference, to be of type ID so that the id() function can be used.
• Define the default namespace to be http://www.posc.org/pef
• Define the PEF schema at the level of the peftypes.xsd file (comments on this later)

Step 3 (optional): Write the PEF Objects Block

The PEF Objects Block is the XML version of the PEF Objects, as defined in the Data Exchange specification. These objects were mapped into the XML to insure completeness of information, with respect to the exchange file. However, these are not normative, and are intended to be used only if they are of use to the exchange. The information contained in these is given by the Data Exchange Specification, and is not repeated here. The XML Schema that governs these objects may be viewed in the file daeents.xsd.

This block of information is optional and may be omitted.

Step 4: Write the Units of Measure Block

It is mandatory that a block of information be given that defines the units of measure that appear in the file. The block should appear as follows:

  <UomBlock>
    <uomReference uid="xxx1" To="http://www.posc.org/pef/poscDict.xml#yyy1"/>
    <uomReference uid="xxx2" To="http://www.posc.org/pef/poscDict.xml#yyy2"/>
       ...
  </UomBlock>

  <quantity uom="#ft">

  <uomReference uid="ft" To="http://www.posc.org/pef/poscDict.xml#ft">

Because of the restrictions of the URL referencing, the unit of measure symbol may differ from the symbol used for referencing. In particular, the slash (/) mark cannot be used. Thus, the unit of measure, ft/s, would be referenced using ftPs. The file, uommatch.txt contains this information. The first column gives the reference that is to be used, and the second column is the POSC Epicentre symbol for the unit of measure.

You may download the poscDict.xml file.

Step 5: Write the data

Begin with the tag, ExchangeData:

  <ExchangeData>

Then, for each Epicentre instance to be recorded in the XML file, you must follow the pattern:

  <ENTITY_NAME>           !all uppercase
                          !then, for each attribute,
    <attribute_name>      !all lowercase    
      <datatype>          !such as string, real, instance, etc.
         ...              !whatever is needed for the datatype
      </datatype>         !close off every tag
    </attribute_name>
    ...                   !other attributes in the same instance
  </ENTITY_NAME>

  </ExchangeData>

Step 6: Close the main tag

  </PEFExchange>

Summary

A sample is given in pefExample.xml.

Additional comments

Use of Schemas:

The schema for the PEFExchange application is found in the file PEFxml.xsd. This file includes two other schemas, pefents.xsd and daeents.xsd, which define the schemas for all the Epicentre entities (the ExchangeData block) and all the DAE objects (the PEFObjects block). None of these three schemas are included in the schema referenced in the file header: peftypes.xsd. Why are we bypassing the main schemas?

A Schema has two main uses. One is to serve as a specification for XML files that are to use it. For this purpose, the full XML schema has been developed for a PEF exchange file for Epicentre 3.0. This full specification gives the overall structure of the file (the PEFxml.xsd file). It also gives the structure of the PEF Objects information (the daeents.xsd file). This structure was defined for informative purposes only in this specification. It also gives the list of all the entities and the attributes in Epicentre 3.0 (the pefents.xsd file).

This third file, pefents.xsd, is too large (1.56 Mbytes). The file is so large that many validators will not be able to validate the input xml file against this large schema file. Thus, it is not feasible to include the entire schema in the validation process.

In addition, the pefents.xsd file is particular to the 3.0 version of Epicentre. If it were included in the header for the validation, the xml file generated from version 2.2, or any other version of Epicentre, may not work. For these reasons, the validation is done only on the pef datatypes (which are the normative part of the recommendation).

The second use of a Schema is to specify the structure of an xml file. Even if the schema is not invoked to validate the file, it remains as a formal specification of the structure of the xml file. Thus, the schema becomes a specification document, in addition to a potential validation document.