Data Format Description Language (DFDL) v1.0 Specification
OGF Proposed Recommendation GFD-P-R.174, January 31, 2011
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 |
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>
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 |
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.
The format properties may be specified in one of three forms:
A DFDL property may be specified using any form with the following exceptions
The ref property may be specified in attribute or short form
The escapeSchemeRef property may be specified in attribute or short form
The hiddenGroupRef property may be specified in attribute or short form
The prefixLengthType property may be specified in attribute or short form
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'
<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.
<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>
<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>
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.