Data Format Description Language (DFDL) v1.0 Specification
OGF Proposed Recommendation GFD-P-R.174, January 31, 2011


7.1 Component Format Annotations

A data format can be 'used' or put into effect for a part of the schema by use of the component format annotation elements.
There are specific annotations for each type of schema component that supports only the representation properties applicable to that component. The table below gives the specific annotation for each schema component.

Schema component

DFDL annotation

xs:choice

dfdl:choice

xs:element

dfdl:element

xs:element reference

dfdl:element

xs:group reference

dfdl:group

xs:schema

dfdl:format

xs:sequence

dfdl:sequence

xs:simpleType

dfdl:simpleType

Table 7 DFDL Component Annotations

 

In addition the dfdl:format annotation is used in a dfdl:defineFormat annotation to define a named reusable set of representation properties that can be referenced from any component specific format annotation.

A dfdl:format annotation at the top level of a schema, that is as an annotation child element on the xs:schema, provides a set of default properties for the lexically enclosed schema document. See Providing Defaults for DFDL properties.

Example of dfdl component annotation:

<xs:schema ...>
  ...
  <xs:element name="foo">

    <xs:annotation>
      <xs:appinfo source="http://www.ogf.org/dfdl/">
        <dfdl:element ref="aBaseConfig"
          representation="text"
          encoding="UTF-8"/>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      ...content here is described by the specified representation properties ...
  </xs:element>
      ...
</xs:schema>

7.1.1 Syntax of Component Format Annotations

Property Name

Description

ref

QName

Reference to a named dfdl:defineFormat annotation that provides a reusable set of DFDL format properties

The ref property is always local to the component format annotation on which it is used, even when specified on a format annotation on the xs:schema element.

See ‎7.2 dfdl:defineFormat - Reusable Data Format Definitions

Annotation: dfdl:element, dfdl:simpleType, dfdl:sequence, dfdl:choice, dfdl:group

representation properties

All other attributes on format annotation elements are representation property bindings. These are defined in sections starting with section ‎9 DFDL Processing Introduction

Annotation: dfdl:element, dfdl:simpleType, dfdl:sequence, dfdl:choice, dfdl:group

Table 8 Component Annotation Syntax

 

7.1.2 Ref Property

A named, reusable, dfdl:defineFormat definition is used by referring to its name from a format annotation using the 'ref' attribute. For example:

<dfdl:element ref=”reusableDef" encoding="ebcdic-cp-us" />

The behavior of this dfdl:defineFormat definition is as if all representation properties defined by the named dfdl:defineFormat definition were instead written directly on this format annotation; however, these are superseded by any representation properties that are defined here such as the encoding property in the example above.

7.1.3 Property Binding Syntax

The format properties may be specified in one of three forms:

  1. Attribute form
  2. Element form
  3. Short form

A DFDL property may be specified using any form with the following exceptions

It is a schema definition error if the same property is specified in more than one form at the same annotation point.

7.1.3.1 Property Binding Syntax: Attribute Form

Within the format annotation elements are bindings for properties of the form:

Property='Value'

For example:
<xs:annotation>
  <xs:appinfo source="http://www.ogf.org/dfdl/">
    <dfdl:format
      encoding="utf-8"
      separator="%NL;"
      />
  </xs:appinfo>
</xs:annotation>

The Property is the name of the property. The Value is an XML string literal corresponding to a value of the appropriate type.

7.1.3.2 Property Binding Syntax: Element Form

The representation properties can sometimes have complex syntax, so an element form for representation property bindings is provided as element content within the format element. This is provided to ease syntactic expression difficulties:

Element form looks like this:

<xs:annotation>
  <xs:appinfo source="http://www.ogf.org/dfdl/">
    <dfdl:format>
      <dfdl:property name='encoding'>utf-8</dfdl:property>
      <dfdl:property name='separator'>%NL;</dfdl:property>
    </dfdl:format>
  </xs:appinfo>
</xs:annotation>

Element form is mostly used for properties that themselves contain the quotation mark characters and escape characters so that they can be expressed without concerns about confusion with the XSDL syntax use of these same characters. CDATA encapsulation can be used so as to allow malformed XML and mismatched quotes to be easily used as representation property values:

<dfdl:property name=’initiator’><[CDATA[<!-- ]]></dfdl:property>

7.1.3.3 Property Binding Syntax:Short Form

To save textual clutter, short-form syntax for format annotations is also allowed. Attributes which are in the namespace "dfdl" and whose local name matches one of the DFDL representation properties are assumed to be equivalent to specific DFDL long-form annotations.

For example the two forms below are equivalent in that they describe the same data format. The first is a short-form of the second:
<xs:element name="foo">
  <xs:complexType>
     <xs:sequence dfdl:separator="%HT;" >
      ...
     </xs:sequence>
  </xs:complexType>
</xs:element>
<xs:element name="foo">
  <xs:complexType>
    <xs:sequence>
      <xs:annotation><xs:appinfo source=”http://www.ogf.org/dfdl/”>
        <dfdl:sequence separator="%HT;" /> 
      </xs:appinfo></xs:annotation>
      ...
    </xs:sequence>
  </xs:complexType>
</xs:element>
Another example:
<xs:element name="foo">
  <xs:complexType>
    <xs:sequence dfdl:separator="%HT;" >
      ...
    </xs:sequence>
  </xs:complexType>
</xs:element>

<xs:element name="foo">
  <xs:complexType>
    <xs:sequence>
      <xs:annotation><xs:appinfo source="http://www.ogf.org/dfdl/">
          <dfdl:sequence separator="%HT;" />
        </xs:appinfo>
      </xs:annotation>
      ...
    </xs:sequence>
  </xs:complexType>
</xs:element>

7.1.4 Empty String as a Property Value

DFDL provides no mechanism to un-set a property. Setting a representation property's value to the empty string doesn't remove the value for that property, but sets it to the empty string value. This may not be appropriate as a value for certain properties.

For example, in delimited text representations, it is sensible for the separator to be defined to be the empty string. This turns off use of separator delimiters. For many other string-valued properties, it is a schema definition error to assign them the empty string value. For example, the character set encoding property cannot be set to the empty string.


Copyright (C) Open Grid Forum (2005-2010). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the OGF or other organizations, except as needed for the purpose of developing Grid Recommendations in which case the procedures for copyrights defined in the OGF Document process must be followed, or as required to translate it into languages other than English.