(MS-DSDG) : Dataset Diffgram Structure Specification: Open Specification Promise Community Promise
(MS-DSDG) : Dataset Diffgram Structure Specification: Open Specification Promise Community Promise
(MS-DSDG) : Dataset Diffgram Structure Specification: Open Specification Promise Community Promise
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that may cover your implementations of the technologies
described in the Open Specifications. Neither this notice nor Microsoft's delivery of the
documentation grants any licenses under those or any other Microsoft patents. However, a given
Open Specification may be covered by Microsoft Open Specification Promise or the Community
Promise. If you would prefer a written license, or if the technologies described in the Open
Specifications are not covered by the Open Specifications Promise or Community Promise, as
applicable, patent licenses are available by contacting iplg@microsoft.com.
Trademarks. The names of companies and products contained in this documentation may be
covered by trademarks or similar intellectual property rights. This notice does not grant any
licenses under those rights.
Fictitious Names. The example companies, organizations, products, domain names, e-mail
addresses, logos, people, places, and events depicted in this documentation are fictitious. No
association with any real company, organization, product, domain name, email address, logo,
person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights
other than specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications do not require the use of Microsoft programming tools or
programming environments in order for you to develop an implementation. If you have access to
Microsoft programming tools and environments you are free to take advantage of them. Certain
Open Specifications are intended for use in conjunction with publicly available standard
specifications and network programming art, and assumes that the reader either is familiar with the
aforementioned material or has immediate access to it.
1 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Revision Revision
Date History Class Comments
2 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
2 Structures ................................................................................................................ 8
2.1 DataSet Concepts .................................................................................................. 8
2.1.1 DataTable........................................................................................................ 8
2.1.1.1 DataColumn ............................................................................................... 9
2.1.1.2 DataRow ................................................................................................. 10
2.1.1.3 Constraint................................................................................................ 10
2.1.2 DataRelation .................................................................................................. 11
2.2 Data Model ......................................................................................................... 12
2.2.1 .NET Framework Types for DataColumn Objects ................................................. 12
2.2.2 Mapping [XMLSchema2] to .NET Framework Types ............................................. 14
2.2.3 Mapping .NET Framework Types to [XMLSCHEMA2] Types ................................... 16
2.2.4 XSD Data Type Keywords ................................................................................ 17
2.3 DiffGram XML Structure ........................................................................................ 18
2.3.1 DiffGram <schema> Elements ......................................................................... 19
2.3.1.1 DataSet DiffGram Schema Mapping ............................................................ 19
2.3.1.1.1 <schema> Element ............................................................................. 19
2.3.1.1.2 DataSet Schema Element ..................................................................... 20
2.3.1.1.3 <include> Element .............................................................................. 21
2.3.1.1.4 <import> Element .............................................................................. 21
2.3.1.1.5 <annotation> Elements within XSD Schemas ......................................... 22
2.3.1.1.6 <group> Element ............................................................................... 24
2.3.1.1.7 Usage of the ref Attribute ..................................................................... 24
2.3.1.1.8 Element Containing <complexType> Elements........................................ 24
2.3.1.1.9 <complexType> and <simpleType> Element Inheritance ......................... 26
2.3.1.1.10 <complexType> Inheritance ............................................................... 26
2.3.1.1.11 <complexType> <complexContent> .................................................... 26
2.3.1.1.12 <complexType> <simpleContent> ...................................................... 28
2.3.1.1.12.1 <simpleType> Inheritance via <restriction> ................................... 29
2.3.1.1.12.2 <simpleType> Columns Marked as Abstract .................................... 29
2.3.1.1.13 Content of <complexType> Element .................................................... 29
2.3.1.1.13.1 <element> Element ..................................................................... 30
2.3.1.1.13.2 <all>, <sequence>, and <choice> Elements .................................. 31
2.3.1.1.13.3 <any> Element ........................................................................... 32
2.3.1.1.13.4 <attribute> Groups...................................................................... 32
2.3.1.1.13.5 <anyAttribute> Element ............................................................... 32
2.3.1.1.13.6 <attribute> Element .................................................................... 32
2.3.1.1.14 <simpleType> Element Within <complexType> Elements ...................... 32
2.3.1.1.15 <attribute> Element within <complexType> ........................................ 35
2.3.1.1.16 Elements Containing <IdentityConstraintDefinition> Elements ................ 37
3 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
4 Security Considerations.......................................................................................... 52
6 Change Tracking..................................................................................................... 54
7 Index ..................................................................................................................... 55
4 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
1.1 Glossary
child element
root element
SOAP (Simple Object Access Protocol)
SOAP envelope
Web service
Web service method
XML attribute
XML document
XML element
XML namespace
XML namespace prefix
XML Schema
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as
described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or
SHOULD NOT.
1.2 References
References to Microsoft Open Specification documents do not include a publishing year because links
are to the latest version of the documents, which are updated frequently. References to other
documents include a publishing year when one is available.
We conduct frequent surveys of the normative references to assure their continued availability. If
you have any issue with finding a normative reference, please contact dochelp@microsoft.com. We
will assist you in finding the relevant information. Please check the archive site,
http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as an
additional source.
[ECMA-335] ECMA international, "Common Language Infrastructure (CLI) Partitions I to VI", ECMA-
335, June 2006, http://www.ecma-international.org/publications/standards/Ecma-335.htm
5 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC
2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt
[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC
2616, June 1999, http://www.ietf.org/rfc/rfc2616.txt
[RFC4646] A. Phillips, Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 4646,
September 2006, http://www.ietf.org/rfc/rfc4646.txt
[SOAP1.1] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn, N., Nielsen, H. F.,
Thatte, S., and Winer, D., "Simple Object Access Protocol (SOAP) 1.1", May 2000,
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
[XMLNS3] World Wide Web Consortium, "Namespaces in XML 1.0 (Third Edition)", December 2009,
http://www.w3.org/TR/2009/REC-xml-names-20091208/
[XMLSCHEMA1] Thompson, H.S., Ed., Beech, D., Ed., Maloney, M., Ed., and Mendelsohn, N., Ed.,
"XML Schema Part 1: Structures", W3C Recommendation, May 2001,
http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/
[XMLSCHEMA2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes", W3C
Recommendation, May 2001, http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
DataSet is a class that is part of the Microsoft® .NET Framework. The DataSet class provides an
in-memory representation of relational data. A DataSet object contains a set of DataTable objects,
Constraint objects, and DataRelation objects. A DataTable contains a collection of DataColumn
objects that represents the schema and a collection of DataRow objects that represents the data.
In addition to storing information in the DataSet, applications can attach additional data to the
DataSet, or to particular DataTable objects or DataColumn objects within a DataTable, by using
extended properties. Extended properties are name/value pairs that are exposed to consumers of
the DataSet, but do not affect the data or schema contained in the DataSet in any way.
The DiffGram is an XML document that contains a serialized form of a DataSet. Any DataSet
instance can be serialized into a DiffGram that can be transmitted over a service interface or
written to persistent storage. The DiffGram structure encapsulates all of the information required to
6 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Data types that the DataSet object uses for the type of the DataColumn object are specified in [MS-
DTYP] and in [MS-NRBF]. Other types not included in these references are specified in this
document. The schema and data in the DataSet are serialized as XML. There is a mapping between
the DataSet in-memory representation and the DiffGram XML representation. This mapping is
based on XML Schema specified in [XMLSCHEMA1] and [XMLSCHEMA2] .
Whenever a DataSet is returned from or received by a Web service method, the DiffGram
structure is used as the default serialization format. When used this way, the DiffGram can be
wrapped in other data structures (for example, as specified in [SOAP1.1], section 4) that
encapsulate other parts of the Web service call.
Web services that exchange DataSet objects can use a variety of network protocols and encodings
to transfer DiffGram XML documents. For example, one Web service can choose to use a plain-text
encoding of a DiffGram within a SOAP (Simple Object Access Protocol) envelope, transmitted by
using Hypertext Transfer Protocol (HTTP) as specified in [RFC2616]. Another Web service can use a
binary encoding for the SOAP envelope that contains the DiffGram and can transmit it by using
User Datagram Protocol (UDP). The network protocols and encodings that can be used to transmit
DiffGram XML documents are completely independent of the DiffGram XML format and are not
covered in this document.
The DiffGram structure can be used whenever a serialized representation of a DataSet object is
needed. More generally, the DiffGram can be used whenever it is necessary to serialize structure,
data values, changes, and error information for tabular data. This document specifies the
serialization of tabular data for the set of types that are supported by DataSet. Any other types are
not specifically covered by this document.
None.
None.
7 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
DataSet Concepts: This section provides an overview of the concept of the DataSet, the .NET
Framework class that contains an in-memory cache of data and schema information.
Data Model: This section describes the data model used by DataSet to store information about
data and schema. This section also covers the mapping between the .NET Framework data types
and XML Schema types.
DiffGram XML Structure: This section describes the DiffGram structure, which is a serialized
XML representation of a DataSet.
As previously discussed, a DataSet object contains DataTable objects and DataRelation objects. The
schema of the DataSet is defined by the DataColumn objects that make up each of the DataTable
objects together with the DataRelation objects and Constraint objects.
Property Description
CaseSensitive Indicates whether string comparisons within this DataSet are case-sensitive.
Namespace Specifies the XML namespace of the serialized DiffGram that represents this
DataSet.
Prefix Specifies the XML prefix that aliases a namespace of the DataSet.
2.1.1 DataTable
DataTable objects contain one or more DataColumn objects, zero or more DataRow objects, and
zero or more Constraint objects.
Property Description
CaseSensitive Indicates whether string comparisons within this DataTable are case-sensitive.
Namespace Specifies the XML namespace of the serialized DiffGram that represents this
DataTable.
Prefix Specifies the XML prefix that aliases a namespace of the DataSet.
8 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
2.1.1.1 DataColumn
As previously discussed, the DataColumn contains schema information for its corresponding data in
the DataRow. The DataColumn object is described by the following properties.
Property Description
AllowDbNull Indicates whether all DataRow objects that contain this DataColumn MUST
specify a non-null value.
AutoIncrement Indicates whether this DataColumn automatically populates and increments its
value for new DataRow objects that are added to the containing DataTable
object.
AutoIncrementSeed Indicates the number to increment from when the first DataRow is created.
AutoIncrementStep Indicates how much to increment for each new DataRow that is added.
DateTimeMode Specifies one of the following values: Local or Unspecified. Applicable only when
DataType is DateTime.
DefaultValue Optional. If specified, indicates the default value that this DataColumn will be
assigned when a new DataRow is created in which no other specific value is
assigned.
MaxLength Indicates the maximum length (in characters) of the values in this DataColumn
Applicable only when DataType is a string.
Namespace Specifies the XML namespace of the serialized DiffGram that represents this
DataSet.
Prefix Specifies the XML prefix that aliases a namespace of the DataSet.
ColumnMapping Indicates whether the instance values are represented in one of three different
ways, Attribute, Element, or Hidden. This information influences how the
DataInstance writes out values. For more information, see section 2.3.2.1.
9 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The DataRow object contains the actual data and errors, in addition to information on the changes
for the data. For each DataRow object, two separate rows of information, the original values and
the current values, are stored. These allow DataSet to track the changes.
Id Name
Original 1 Chris
Current 1 Kris
The original row in the preceding representation contains the values that were originally loaded into
the DataSet. The current row contains the current values, reflecting any changes to the original
values that might have been made in memory. The values for original or current might be empty,
but not both.
In addition to the values in current and original, there is information in the DataRow on error
information. There is a RowError property, which is a string that indicates an error for the
DataRow. There is also error information that is used for each DataColumn within the DataRow.
2.1.1.3 Constraint
There can be relationships and constraints between multiple DataTable objects or within a
DataTable object. There are three supported constraints: primary key, foreign key, and unique, as
specified in [SQL92].
When a DataRow is added to a DataTable that has a foreign key constraint on one or more of its
DataColumn objects, these DataColumn objects MUST contain values that exist in the linked
DataTable. Otherwise, the constraint will be violated.
Property Description
AcceptRejectRule Indicates the action that is to be taken when modifications become accepted as
the current values.
Columns Specifies the set of DataColumn objects to which this constraint applies.
RelatedColumns Specifies the set of DataColumn objects in the target DataTable to which this
DataTable is related.
10 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Table Specifies the name of the DataTable to which this constraint applies.
Property Description
Columns Specifies the set of DataColumn objects to which this constraint applies.
IsPrimary If true, specifies that the DataColumn objects to which this constraint applies
are a primary key. Otherwise, false.
Table Specifies the name of the DataTable to which this constraint applies.
2.1.2 DataRelation
A DataRelation object represents a parent/child relationship between two DataTable objects that
are connected by a ForeignKeyConstraint object. This DataRelation can be used to traverse the
relationship graph between DataTable objects.
The DataRelation can also be used to specify an action to be taken when DataRow objects in a
parent DataTable are deleted. The action can allow the change to cascade to the child DataTable
or not. An example of a cascading action specifies that when a parent DataTable has a DataRow
deleted, all DataRow objects in the child DataTable that were related to the deleted DataRow
should be subsequently deleted as well.
Property Description
ChildColumns Specifies the set of DataColumn objects in the child DataTable to which this
DataRelation applies.
ChildTable Specifies the DataTable that is the child DataTable in this DataRelation.
Nested Specifies whether this DataRelation is nested. In the DiffGram, a Nested child
DataTable is a child element of the parent DataTable element. For more
information, see section 2.3.
ParentColumns Specifies the set of DataColumn objects in the parent DataTable to which this
DataRelation applies.
ParentKeyConstraint Specifies the set of DataColumn objects that acts as a unique or primary key
11 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
for the parent DataTable. For more information, see section 2.2.
ParentTable Specifies the DataTable that is the parent DataTable in this DataRelation.
This section explains the data types that can be used with the DataSet and their relationship to
[XMLSCHEMA2] types in the context of the DataSet DiffGram structure. The conceptual
representation of these types is described in the following sections or referenced from other
protocols. These types are mapped to the [XMLSCHEMA2] type that each corresponds to. The
mapping to the [XMLSCHEMA2] type is important because in all cases except for two, these
mappings dictate the serialization of an instance of data.
The following types are specified in [MS-DTYP] (introduced in the Microsoft® .NET Framework 1.0).
Object Boolean
Byte
Int8
Int16
Int32
Int64
Uint16
Uint32
Double
String
The following types are specified in [MS-NRBF] (introduced in the .NET Framework 1.0).
Single
TimeSpan
DateTime
Decimal
The following table describes additional types that the DataSet object can use. Further information
about how values are serialized is specified in section 2.2.3.
12 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
System.Data.SqlTypes.SqlDateTime The date and time data - ranging in value .NET Framework
from January 1, 1753 to December 31, 2.0
9999 to an accuracy of 3.33 milliseconds -
to be stored in or retrieved from a
database.
13 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The following table details the mapping from types that are defined in [XMLSCHEMA2] to the types
in the .NET Framework. All types that are specified in the [XMLSCHEMA2] specification have a
mapping.
.NET
Framework
XML Schema type type Comments
string String
normalizedString String
Boolean Boolean
float Single
double Double
decimal Decimal
duration TimeSpan
Base64Binary Byte[]
hexBinary Byte[]
anyURI System.Uri
ID String
IDREF String
ENTITY String
NOTATION String Columns are not created for notation declaration elements;
elements whose base type is NOTATION are created as string
columns.
QName String
14 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
language String
IDREFS String
ENTITIES String
NMTOKEN String
NMTOKENS String
Name String
NCName String
integer Int64
nonPositiveInteger Int64
negativeInteger Int64
long Int64
int Int32
Short Int16
byte Sbyte
nonNegativeInteger UInt64
unsignedLong UInt64
unsignedInt UInt32
unsignedShort UInt16
unsignedByte Byte
positiveInteger UInt64
dateTime DateTime
time DateTime
date DateTime
15 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The following table details the mapping from Microsoft® .NET Framework types to types that are
defined in [XMLSCHEMA2].
For some .NET Framework types, the mapping to the [XMLSCHEMA2] type is not sufficient to fully
define the serialization format. In these cases, additional information is provided for what MUST be
specified to add to the XML schema and/or what MUST be specified for the layout of the data.
Types that are not listed in the following table can be used in the DiffGram. However, their
serialization formats are outside the scope of this document.
.NET Framework
type [XMLSCHEMA2] type
Char The XML schema of a Char MUST be written as restriction of a string type where the
length = 1, as in the following example.
<xs:simpleType> <xs:restriction base="xs:string"> <xs:length
value="1" /> </xs:restriction></xs:simpleType>
String String
Boolean Boolean
Double Double
Decimal Decimal
TimeSpan Duration
Byte[] base64Binary
Single Float
Int64 Long
Int32 Int
Int16 Short
Sbyte Byte
UInt64 unsignedLong
UInt32 unsignedInt
UInt16 unsignedShort
Byte unsignedByte
DateTime dateTime
Guid String
Any Guid instance MUST be serialized into a string form as defined by the following
ABNF form.
guidLiteral = 8*HEXDIG "-"
4*HEXDIG "-"
4*HEXDIG "-"
16 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
12*HEXDIG
Uri anyUri
BigInteger Anytype
Any BigInteger value MUST be serialized into the same form as the XSD type
integer as specified in [XMLSCHEMA2].
SqlBinary hexBinary
SqlBoolean Boolean
SqlByte Byte
SqlBytes base64Binary
SqlChars String
SqlDateTime dateTime
SqlDecimal Decimal
SqlDouble Double
SqlGuid Guid
SqlInt16 Short
SqlInt32 Int
SqlInt64 Long
SqlMoney Decimal
SqlSingle Float
SqlString String
SqlXml Anytype
The following [XMLSCHEMA2] type keywords are supported for the [XMLSCHEMA2] types float and
double. If the values of the .NET Framework types Double or Single are equal to the values that
are described in the following table, the values MUST be set by using the correct schema type
keyword as specified in [XMLSCHEMA2].
17 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The DiffGram MUST have a root element, hereafter referred to as the <root> element.
If the <root> element contains at least one <schema> element as specified in [XMLSCHEMA2],
the following rules MUST apply.
If the <root> element does not contain one or more <schema> elements, the schema is
assumed to be predefined between the producer and consumer.
The XML that comprises a DiffGram Data element MUST include required XML elements and
XML attributes as specified in the following sections of this document. These XML elements
and XML attributes are defined in various XML namespaces. The following table lists these XML
namespaces and specifies the XML namespace prefixes that are commonly associated with
them. Producers and consumers of DataSet DiffGram structures MUST ensure that the XML
references these namespaces by using the mechanisms that are specified in [XMLNS3], but
they SHOULD<1> use the prefixes that are shown in the following table. For clarity, when XML
elements and attributes from these namespaces are referenced in this document, their fully-
qualified names are used.
Commonly
Description Namespace URI used prefix Reference
The sections that follow define the <schema> elements and the DiffGram Data element in more
detail. At a basic level, the purpose of these elements can be explained as follows:
18 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The DiffGram Data element encapsulates the values of the data in the DataSet.
Any XML document that is specified in [XMLSCHEMA1] and [XMLSCHEMA2] can be mapped to a
relational structure in the DataSet object. Following is a formal set of rules that outlines this
mapping to a DataSet object. Cases in which the schema specified in [XMLSCHEMA1] and
[XMLSCHEMA2] are not understood are specifically mentioned.
Following are the rules that MUST be followed for the <schema> element:
If the schema element contains an element named element whose msdata:IsDataSet
attribute is set to true, this element MUST be mapped to the DataSet object and hereafter is
referred to as the DataSet Schema element. Otherwise, the <schema> element itself is
mapped to the DataSet, and the name of the DataSet is mapped from the id attribute, if it is
specified.
If a child element of the <schema> element has a msdata:IsDataSet attribute set to false, this
child element MUST be mapped to a DataTable object and not a DataSet.
If the <schema> element does not contain an element whose msdata:IsDataSet attribute is set
to true, the following rules apply:
If there is an id attribute of the <schema> element, it MUST be mapped to the name of the
DataSet.
If the attribute targetNamespace is specified on the <schema> element, it must be set as the
targetNamespace of the DataSet and MUST be a valid namespace string as specified in
[XMLSCHEMA1]. If the attribute targetNamespace is not specified, the namespace property of
the DataSet MUST be set to an empty string.
<Attribute> elements that are children of the <schema> element and are not referenced
elsewhere MUST be ignored. If the <attribute> elements are referenced, they MUST follow the
mapping rules that are specified in section 2.3.1.1.15.
Any element that is a <simpleType> element as specified in [XMLSCHEMA2] and that is a direct
child of the <schema> element and not referenced as specified in [XMLSCHEMA2], MUST be
ignored in the mapping. If the <simpleType> element is referenced, it MUST follow the mapping
rules that are specified in section 2.3.1.1.14.
Any element that is a <complexType> element as specified in [XMLSCHEMA2] and that is a direct
child of the <schema> element and not referenced as specified in [XMLSCHEMA2], MUST be
ignored in the mapping. If the <complexType> element is referenced, it MUST map to a
DataTable and MUST follow the rules that are specified in section 2.3.1.1.8.
Any element that is a <group> element that is a direct child of the <schema> element and not
referenced as specified in [XMLSCHEMA2], this element MUST be ignored in the mapping. If the
19 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Any element that has the abstract attribute equal to true and that is not referenced as specified
in [XMLSCHEMA2] by any other elements MUST be ignored. If the element that is referenced has
the abstract attribute equal to true, the referencing type follows the rules that are described in
section 2.3.1.1.10.
If the DataSet Schema element is present, the name of the DataSet object is determined by
the following rules:
If the name attribute is specified, the name of the DataSet MUST be set to the value of the
name attribute.
If the name attribute is not specified in the DataSet Schema element, the value of the id
attribute of the <schema> element MUST be mapped to the name of the DataSet.
If the DataSet Schema element contains one or more child <complexType> elements with a
<choice> element compositor, the child <complexType> elements will map to one or more
DataTable objects.
If the msdata:CaseSensitive attribute is specified within the DataSet Schema element, its
value MUST be true or false.
If the msdata:CaseSensitive attribute is not specified, the value MUST be false. The value
MUST map to the CaseSensitive property on DataSet.
If the msdata:Locale attribute is specified within the DataSet Schema element, the value of
the msdata:Locale attribute MUST follow [RFC4646]. If the attribute is not specified and
msdata:UseCurrentLocale is specified and is equal to true, the Locale property on the
DataSet MUST be set to the current local of the computer based on [RFC4646].
If the msdata:Prefix attribute is specified, the value will be the Prefix property of the DataSet.
If the attribute is not specified, the Prefix property of the DataSet MUST be an empty string.
If the DataSet Schema element contains attributes that specify the urn:schemas-microsoft-
com:xml-msprop namespace, each attribute name/value pair MUST specify a name/value pair in
the ExtendedProperties that exists on the DataSet object.
Any additional attribute that is not specified earlier in this section MUST be ignored.
20 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
As defined in [XMLSCHEMA2], the <include> element is optionally used within a <schema> element
to include other definitions and declarations in the schema. The following schema excerpt is a
sample usage.
Here the DataSet object, DataTable objects, and DataColumn objects all belong to the
targetNamespace <schema> element unless explicitly specified in the child elements of the
<include> element.
As defined in [XMLSCHEMA2] the <import> element is optionally used within the <schema>
element. If the <import> element is specified, it MUST follow the rules specified in [XMLSCHEMA1].
Following is an example that uses <import>.
<xs:schema id="SampleDataSet"
targetNamespace="http://www.microsoft.com"
xmlns=" http://www.microsoft.com"
xmlns:xs="http://www.w3.org/2000/10/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"
xmlns:myns="http://www.example.com/myns"
elementFormDefault = "qualified" >
<!-- import for types from myns -->
<xs:import namespace="http://www.example.com/myns" schemaLocation="
http://www.example.com/myns/person.xsd"/>
<xs:complexType name="Person">
<xs:sequence>
<xs:element name="name" maxOccurs="unbounded">
21 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The following rules MUST be used for processing <annotation> elements within XSD Schemas:
The <annotation> element MUST NOT be ignored in the mapping process when it contains an
<msdata:Relationship> subelement. An <msdata:Relationship> element MUST be mapped to
a DataRelation object. If an <msdata:Relationship> element is specified, the following rules
MUST be followed:
The msdata:parent attribute MUST exist and the value MUST map to a DataTable. If
the <msdata:Relationship> is nested within one element that is mapped to a
DataTable (known as a parent DataTable), which is in turn nested within another
element mapped to a DataTable (known as a child DataTable), the parent attribute
value MUST be the same name as the parent DataTable.
The msdata:child attribute MUST exist and the value MUST map to a DataTable. If the
<msdata:Relationship> is nested within one element that is mapped to a DataTable
22 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The name attribute MUST be specified and mapped to the RelationName property of
the DataRelation.
<xs:element name="table1">
<xs:complexType>
<xs:all>
<xs:element name="col1" minOccurs="0" type="xs:string" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="table2">
<xs:complexType>
<xs:all>
<xs:element name="col1" minOccurs="0" type="xs:string" />
</xs:all>
</xs:complexType>
</xs:element>
<xs:annotation>
<xs:appinfo>
<msdata:Relationship name="Relation1" msdata:parent="table1" msdata:child="table2"
msdata:parentkey="col1" msdata:childkey="col1" />
</xs:appinfo>
</xs:annotation>
</xs:schema>
23 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
As specified in [XMLSCHEMA2], the <group> element is optional and MUST follow the following
rules:
The minOccurs and maxOccurs attributes on the <group> element MUST be ignored and have
no effect in the mapping process.
The child elements of the <group> element MUST be deserialized in accordance with the rules in
section 2.3.1.1.13.1.
As defined in [XMLSCHEMA2], named <schema> elements are optionally used with ref attributes
within a DiffGram structure. If these <schema> elements are specified, they MUST follow
[XMLSCHEMA2]. For the purposes of the DiffGram, when the schema is being read, any named
elements that are not referenced within the declared schema instances will not be processed.
The following rules apply when a particular element is mapped to a DataTable object.
24 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
There MUST be a name attribute specified in the <complexType> element. The value of the
name attribute MUST map to the name of the DataTable. The combination of the name and
the XML namespace of the DataTable object MUST be unique. The name value MUST map to
the TableName property on the associated DataTable.
The following rules MUST be followed to determine the namespace property of the DataTable
from the DiffGram element that maps to a DataTable.
If there is a targetNamespace attribute on the DataSet element, the element MUST map to
the DataTable namespace property.
If the targetNamespace attribute is not specified or its value is empty, the namespace
property on the mapped DataTable MUST be the targetNamespace attribute of the current
<schema> element.
If the DataTable object is referenced from an <import> element schema, the DataTable
namespace property MUST be mapped to the targetNamespace of the imported schema.
If the msdata:CaseSensitive attribute is specified, the value MUST be true or false. If the
attribute is not specified, the default value is false. The value MUST map to the CaseSensitive
property on the mapped DataTable.
If the msdata:Locale attribute is specified, the value MUST follow [RFC4646]. If the attribute is
not specified, the value MUST be what the Locale value of the DataSet object is, as specified in
section 2.3.1.1.2. The value MUST map to the Locale property on the mapped DataTable.
If the element is mapped to a DataTable, each attribute that specifies the urn:schemas-
microsoft-com:xml-msprop namespace MUST specify a name/value pair in the
ExtendedProperties property that exists on the DataTable.
If the element is mapped to a DataColumn, each attribute that specifies the urn:schemas-
microsoft-com:xml-msprop namespace MUST specify a name/value pair in the
ExtendedProperties that exists on the DataColumn.
The following attributes within the element MUST be ignored for elements that contain
<complexType> elements:
block
default
equivClass
final
fixed
id
25 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
<xs:element name="orderdetail">
<xs:complexType>
<xs:all>
<xs:element name="orderID" minOccurs="0" type="xs:string"></xs:element>
<xs:element name="description" minOccurs="0" type="xs:string"></xs:element>
</xs:all>
</xs:complexType>
…
</xs:element>
XSD schemas support two styles of <complexType> element inheritance by using the extension or
restriction elements. The following rules MUST be followed when mapping elements to DataSet
concepts:
A derived <complexType> element MUST have as a base type either another <complexType> or
another <simpleType> element. Any derived <complexType> that is not referenced as specified in
[XMLSCHEMA2] MUST be ignored and not mapped.
base: This attribute MUST be used to determine any elements or attributes from the base class
that are used in the new derived class and mapped to DataColumn objects.
The following rules MUST be followed to map a <complexType> that contains a <complexContent>:
base: This attribute MUST be used to determine any elements or attributes from the base class
that are used in the new derived class and are mapped to DataColumn objects.
26 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cars.example.com/schema"
xmlns:target="http://cars.example.com/schema">
<complexType name="Car">
<complexContent>
<extension base="target:Vehicle">
<sequence>
<element name="EngineSize" type="string"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="Plane">
<complexContent>
<extension base="target:Vehicle">
<sequence>
<element name="WingSpan" type="string"/>
</sequence>
</extension>
</complexContent>
</complexType>
</schema>
In the preceding example, the "Car" and "Plane" tables both have a DataColumn named "type".
The "Car" DataTable also has a DataColumn that is called "EngineSize", and the "Plane" DataTable
has a DataColumn that is called "WingSpan". Note that a DataTable is not created for the
"Vehicle" <complexType> element.
<xs:complexType name="Address">
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element name="street" type="xs:string"/>
<xs:element name="city" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="USAddress">
<xs:complexContent>
<xs:extension base="Address">
<xs:sequence>
<xs:element name="state" type="xs:string"/>
27 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
In the preceding example, a DataTable is created for "USAddress" with columns called "name",
"street", "city", "state", and "zip".
When deriving from a <complexType> element, either the sequence or the <group> element MUST
be used. If there is a base class, it MUST NOT specify any other <group>, <choice>, or <all>
elements.
Each attribute MUST map to a DataColumn and MUST follow all the rules that are specified in
section 2.3.1.1.15.
Each element MUST map to a DataColumn, where the name of the DataColumn is specified by
the msdata:DataColumn attribute or, if this attribute is not specified, by the name of the
element together with "_text" appended to the end.
<xs:element name="internationalPrice">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:decimal">
<xs:attribute name="currency" type="xs:string" />
<xs:attribute name="diff" type="xs:decimal" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
The data instance might specify a value, as shown in the following example.
In this case, a column that has the name of the table, followed by "_text", is created in the
DataTable and populated with the values from the data instances. In the preceding example, the
element <internationalPrice> is mapped to a DataTable, and the <internationalPrice> value,
currency, and diff are mapped to DataColumn objects.
28 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
<SimpleType> elements can be derived from other <simpleType> elements via a <restriction>
element. When a <simpleType> derives from a <restriction> element where the type is a string,
the length or maxLength attributes MUST be mapped to the MaxLength property of the
DataColumn property. All the <restriction> attributes MUST be ignored except for maxLength
when the type is a string.
As defined in [XMLSCHEMA2], a <simpleType> can optionally derive from abstract types. These
elements MUST not be mapped to DataColumn objects.
This section details the mapping of <complexType> elements that are contained within an element
named <element>.
minBound
minExclusive
minInclusive
maxBound
maxExclusive
maxInclusive
precision
scale
length
minlength
maxlength
encoding
period
enumeration
pattern
any
anyAttribute
choice
fixed
29 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
If the element contains a <complexType> element or has a maxOccurs value that is greater than
1, it MUST be mapped to a DataTable object as defined in section 2.3.1.1.8.
The following criteria MUST be used to determine whether there is a nested DataRelation object or a
Constraint object:
If the <msdata:Relationship> element is specified in the child element that maps to the
DataTable, this <relationship> element MUST map to the DataRelation whose Nested
property MUST be set to true.
If there is no primary key for the parent DataTable, a DataColumn named "<tablename>_ID"
MUST be added to the DataTable that maps to the parent element.
If the element contains a <simpleType> element and if the maxOccurs attribute specifies a
value greater than 1, the element MUST be mapped to a DataTable as defined earlier in this
section.
Any <complexType> element in a <relationship> element MUST follow the rules specified in this
section.
If the element is a <simpleType> element or references a <simpleType> element and has a
maxOccurs attribute value of 1, or if the maxOccurs attribute is not specified, in which case
[XMLSCHEMA2] defines the default value to be 1, the element MUST map to a DataColumn and
MUST follow the rules in section 2.3.1.1.14.
30 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
A DataColumn that has a name equal to "Name" is added to the customer DataTable.
For example, in the following schema snippet, the <complexType> will map to a DataTable object
with a Name property set to "Order". "Orderdetails", "ordertype2", and "ordertype1" will map to
DataColumn objects.
<xs:element name="Order2">
<xs:complexType>
<xs:choice minOccurs="1">
<xs:element name = "ordertype1" type="xs:string"/>
<xs:sequence>
<xs:element name = "ordertype2" type="xs:string"/>
<xs:element name = "orderdetails" type="xs:string"/>
</xs:sequence>
</xs:choice>
</xs:complexType>
</xs:element>
31 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
<Attribute> groups are deserialized and individually mapped to DataColumn objects as described in
section 2.3.1.1.15. <Attribute> groups MUST be defined at the <schema> element level.
The element MUST be mapped to a DataColumn object within the DataTable object that the
parent element maps to.
If the type is a <complexType> with <simpleContent>, apply the rules described in section
2.3.1.1.12.
If the element contains a ref attribute, the referenced type MUST be used for the remainder of
the rules of this section.
The name of the DataColumn MUST be the name of the element. This name MUST be unique
within the targetNamespace attribute that the DataColumn element is in.
If the type references a type from an imported element schema, the namespace property of the
DataColumn MUST be the targetNamespace of this imported schema. Otherwise, the
namespace of the DataTable MUST be the targetNamespace attribute from the current
<schema> element.
The following rules that MUST be followed to determine what data type the DataColumn will
map to depending on how the type and the msdata:DataType attribute are used:
If the msdata:DataType attribute is present, the value MUST map to a data type as specified
in section 2.2.3. The msdata:DataType value will either be the namespace and the class
name or a fully qualified type name as specified by [ECMA-335]. Only types that are defined in
section 2.2.3 SHOULD<2> be specified in the non-fully-qualified form.
If the type attribute is present and the msdata:DataType attribute is present, the value of the
type attribute MUST be the correct [XMLSCHEMA2] type for the value of the
msdata:DataType attribute that is specified according to section 2.2.3.
If the type attribute is present and the msdata:DataType attribute is not present, the
DataColumn data type MUST map to the data type according to section 2.2.2.
32 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The default attribute MUST not be specified if the DataColumn data type is SqlXml or any other
data type that is not explicitly listed in section 2.2.3.
If the element has a default attribute, the DefaultValue property of the DataColumn is set to
this value. The value of the default attribute MUST be serialized according to the data type-to-
[XMLSCHEMA2]-type serialization rules that are described in section 2.2.3.
If the element has a minOccurs value of 0 and no nillable attribute is specified, the
AllowDbNull property of the DataColumn MUST be mapped to true. If the minOccurs value is
1, the value of the AllowDbNull property of the DataColumn MUST be false. As specified in
[XMLSCHEMA2], if minOccurs is not specified, the default value is 1, so the AllowDbNull
property MUST be false.
If the value of the minOccurs attribute is greater than 0, the nillable attribute optionally can be
specified as specified in [XMLSCHEMA2]. If the nillable attribute is specified, its value MUST be
true or false, and the AllowDbNull property of the DataColumn MUST be the value of the
nillable attribute. If the attribute is not specified and minOccurs is greater than 0, the nillable
value MUST be false and the AllowDbNull property of the DataColumn MUST be false.
If the element has a minOccurs value of 0, the nillable attribute MUST be ignored.
If the msdata:Caption attribute is specified, the DataColumn Caption property value MUST be
a valid string as specified in [XMLSCHEMA2]. If the attribute is not specified, the value MUST be
the name of the DataColumn name.
If the msdata:Expression attribute is specified, the DataColumn Expression property value
MUST be a valid string as specified in [XMLSCHEMA2]. If the attribute is not specified, the
DataColumn Expression property value is an empty string.
If the msdata:ReadOnly attribute is specified, the DataColumn ReadOnly property value
MUST be true or false. If the attribute is not specified, the DataColumn ReadOnly property
value MUST be false.
The following attributes MUST be ignored for <simpleType> elements within <complexType>
elements:
block
id
33 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Its ordinal is 0.
AllowDbNull is false.
Its ordinal is 1.
AllowDbNull is true.
Its ordinal is 2.
AllowDbNull is true.
Its ordinal is 3.
Its ordinal is 4.
34 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
An <attribute> element for which a use attribute is specified and the value is "prohibited" MUST be
mapped to a DataColumn object with a ColumnMapping property set to Hidden. An <attribute>
element that has a use attribute specified with a value that is other than "prohibited" MUST be
mapped to a DataColumn with a ColumnMapping property set to Attribute.
If the <attribute> element contains a ref attribute, the referenced type as specified in
[XMLSCHEMA2] MUST be used for the remainder of the rules of this section:
The name of the DataColumn MUST be the name of the <attribute> element. This name and its
targetNamespace attribute MUST be unique.
If the <attribute> element references a type from an imported schema, the namespace
property of the DataColumn MUST be the targetNamespace of this imported schema.
Otherwise, the namespace of the DataTable object MUST be the targetNamespace attribute
from the current <schema> element.
Following are the rules that MUST be followed to determine what data type the DataColumn
maps to depending on how the type attribute and msdata:DataType attribute are used:
If only the msdata:DataType attribute is specified, its value MUST map to a data type. The
msdata:DataType value will either be the namespace and the class name or a fully
qualified type name as specified in [ECMA-335]. Types defined in section 2.2.3 SHOULD<3>
be specified in the non-fully qualified form.
If the type attribute is present and the msdata:DataType attribute is present, the value of the
type attribute MUST be the correct [XMLSCHEMA2] type for the value of the
msdata:DataType attribute that is specified according to section 2.2.3.
If the type attribute is present and the msdata:DataType attribute is not present, the
DataColumn data type MUST map to the data type according to section 2.2.2.
If the type attribute is not present, the DataColumn data type MUST map to "string".
If the <attribute> element specifies a use attribute that is set to "default", the DefaultValue
property of the DataColumn MUST be set to the value of the value attribute. The value MUST
be serialized according to the data type to [XMLSCHEMA2] data type serialization rules that are
described in section 2.2.3.
If the <attribute> element specifies a use attribute that is set to "required", the AllowDbNull
property of the DataColumn MUST be set to false. Otherwise, the AllowDbNull property of the
DataColumn MUST be set to true.
If the <attribute> element specifies a use attribute that is set to optional, the AllowDbNull
property of the DataColumn MUST be set to true.
If the <attribute> element specifies a use attribute that is set to fixed, the DefaultValue
property of the DataColumn property MUST be set to the value of the value attribute. The value
MUST be serialized according to the data type to [XMLSCHEMA2] data type serialization rules that
are described in section 2.2.3.
If the <attribute> element has a use attribute that is set to fixed, the ReadOnly property of the
DataColumn MUST be set to true. If the attribute is not set to fixed, the ReadOnly property of
the DataColumn MUST be set to false.
35 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
If the minOccurs attribute is specified, the value MUST NOT be greater than 1:
All <attribute> elements within the <complexType> element MUST be children of the
<complexType> element and not part of any compositor element (<all>, <sequence>, or
<choice>).
If the msdata:Caption attribute is specified, the DataColumn Caption property value MUST be
a valid string as specified in [XMLSCHEMA2]. If the attribute is not specified, the value MUST be
the name of the DataColumn name.
If the msdata:Expression attribute is specified, the DataColumn Expression property value
MUST be a valid string as specified in [XMLSCHEMA2]. If the attribute is not specified, the
DataColumn Expression property value is an empty string.
If the msdata:ReadOnly attribute is specified, the DataColumn ReadOnly property value
MUST be true or false. If the attribute is not specified, the DataColumn ReadOnly property
value MUST be false.
<xs:element name="customer">
<xs:complexType>
<xs:all>
….
</xs:all>
<xs:attribute name="name" type="xs:string"></xs:attribute>
</xs:complexType>
</xs:element>
36 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
unique
key
keyref
If there are no constraints, there MUST NOT be constraints mapped to the DataSet object.
A <unique> element MUST map to a UniqueConstraint concept, which is part of the DataSet
concept. When a <unique> element is found within the schema as specified in [XMLSCHEMA1] and
[XMLSCHEMA2], the following rules MUST be followed:
If a <unique> element appears within a <complexType> element that has been mapped to a
DataTable, the <unique> element MUST map to a unique constraint for that DataTable.
The <selector> element MUST exist and MUST have an xpath attribute that maps to a
DataTable that the unique constraint is part of.
One or more <field> elements MUST exist. In each <field> element, as specified in
[XMLSCHEMA2], there MUST contain an xpath attribute that maps to a DataColumn that MUST
be part of the DataTable that is specified in the <selector> element.
If the element contains the msdata:PrimaryKey attribute and the value equals true, the
primary key of the DataTable MUST be mapped to the DataColumn objects that are specified
by the <field> elements. If the msdata:PrimaryKey attribute is not specified or its value is
equal to false, a UniqueConstraint MUST be mapped to the DataColumn objects that are
specified by the <field> elements.
Any DataColumn objects that are part of a UniqueConstraint object optionally can be used as
part of a ForeignKeyConstraint object to another DataTable. Any DataColumn objects that
are not part of a UniqueConstraint MUST NOT be a member of a ForeignKeyConstraint.
A <key> element in the XSD MUST map to a UniqueConstraint object, which is part of the
DataSet object. When a <key> element is found within the schema as specified in [XMLSCHEMA1]
and [XMLSCHEMA2], the following rules MUST be followed:
37 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The <selector> element MUST exist and MUST have an xpath attribute that maps to a
DataTable that the unique constraint is part of.
One or more <field> elements MUST exist. In each <field> element, there MUST exist an xpath
attribute that maps to a DataColumn object that MUST be part of the DataTable that is specified
in the <selector> element.
If the element contains the msdata:PrimaryKey attribute and the value equals true, the
primary key of the DataTable MUST be mapped to the DataColumn objects that are specified
by the <field> elements. If the msdata:PrimaryKey attribute is not specified or is equal to
false, a UniqueConstraint MUST be mapped to the DataColumn objects that are specified by
the <field> elements.
Any DataColumn objects that are part of a UniqueConstraint object optionally can be used as
part of a ForeignKeyConstraint object to another DataTable. Any DataColumn objects that
are not part of a UniqueConstraint MUST NOT be a member of ForeignKeyConstraint.
If a <keyref> element occurs in the XSD and the value of its msdata:ConstraintOnly attribute is
true, or this attribute is not specified, the <keyref> element MUST be mapped to a
ForeignKeyConstraint object and a DataRelation object in a DataSet object.
If the value of the msdata:ConstraintOnly attribute is false, the <keyref> element MUST be
mapped only to the ForeignKeyConstraint object. The following rules MUST be followed to map
the <keyref> element to a ForeignKeyConstraint:
If a <keyref> element appears within a <complexType> element that has been mapped to a
DataTable, the <keyref> element’s <selector> element MUST map to the same DataTable.
The <selector> element MUST exist and MUST have an xpath attribute that maps to a
DataTable that the ForeignKeyConstraint is part of. The Table property of the
ForeignKeyConstraint MUST map to the DataTable that is identified by the <selector>
element.
38 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The refer attribute MUST be a name that links this to another existing <keyref> element or
<unique> element to which this foreign key relates. The RelatedTable and RelatedColumns
properties of the ForeignKeyConstraint MUST map to the DataTable and DataColumn objects
that are specified by the other <unique> element.
If the msdata:UpdateRule attribute is specified, the value MUST be None, Cascade, SetNull, or
SetDefault. If the attribute is not specified, the value is set to Cascade. The UpdateRule
property of the ForeignKeyConstraint MUST be set to the specified value.
If the msdata:DeleteRule attribute is specified, the value MUST be None, Cascade, SetNull, or
SetDefault. If the attribute is not specified, the value is set to Cascade. The DeleteRule property
of the ForeignKeyConstraint MUST be set to the specified value.
If the msdata:AcceptRejectRule attribute is specified, the value MUST be None, Cascade,
SetNull, or SetDefault. If the attribute is not specified, the value is set to Cascade. The
AcceptRejectRule property of the ForeignKeyConstraint MUST be set to the specified value.
If the msdata:IsNested attribute is specified and the value equals true, the child DataTable
MUST be nested within an <all>, <sequence>, or <choice> element of the parent DataTable. If
msdata:IsNested equals false, the child DataTable MUST NOT be nested within the parent
DataTable. There MUST NOT be more than one nested Constraint for any one child DataTable.
Each attribute on the <keyref> element that specifies the namespace urn:schemas-microsoft-
com:xml-msprop MUST have an attribute name that starts with fk._
If the msdata:ConstraintOnly attribute is equal to true, the following rules MUST be followed to
map the already mapped ForeignKeyConstraint to the DataRelation:
If the msdata:RelationName attribute is specified, its value MUST be mapped to the
RelationName property of the DataRelation. If msdata:RelationName is not specified and
the msdata:ConstraintName attribute is not specified, its value MUST be mapped to the
RelationName property of the DataRelation.
If the msdata:ConstraintName attribute is not specified, the name attribute value MUST be
mapped to the RelationName property of the DataRelation.
The ChildColumns property of the DataRelation MUST be set to the same DataColumn
objects as the related Columns property of the ForeignKeyConstraint.
The ChildTable property of the DataRelation MUST be set to the same DataTable as the
RelatedTable property of the ForeignKeyConstraint.
The ParentColumns property of the DataRelation MUST be set to the same DataColumn
objects as the related RelatedColumns property of the ForeignKeyConstraint.
39 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
There MUST NOT be more than one nested DataRelation for any one child DataTable.
40 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
A "UniqueOrderID" unique constraint is created for the "orderID" DataColumn in the "order"
DataTable.
The "orderID" DataColumn of the "order" DataTable has a unique property of true.
An "OrderDetailKey" foreign key constraint is created between the "orderID" foreign key
DataColumn in the "orderDetail" DataTable and the "UniqueOrderID" key that is created in the
"order" DataTable.
Conceptually, the DiffGram Data element encapsulates the XML representation of the data in the
DataSet object. At a high-level, the DiffGram Data element contains the following child elements:
A DataInstance element's rows, and the data that they contain, MUST conform to the rules that
are specified in sections 2.1 and 2.2.
41 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
In the preceding XSD, the following are the definitions of the DiffGram Data element, the
DataInstance element, the <before> element, and the <errors> element.
<xs:element name="diffgram">
<xs:any namespace="##other" processContents="lax" minOccurs="0" />
<xs:element name="before" minOccurs="0">
<xs:element name="errors" minOccurs="0">
Note that because the schema of the DataInstance element is defined by the <schema> element
of the DiffGram (and varies per DataSet), it is not possible to write a single schema for the
DiffGram Data element that properly defines the DataInstance element. Therefore, the preceding
schema allows any content in the place of the DataInstance element. Producers and consumers of
DiffGrams MUST make sure that the DataInstance element's rows, and the data they contain,
MUST conform to the rules that are specified in sections 2.1 and 2.2 and 2.3.
The sub-sections that follow define the parts of the DiffGram Data element in more detail.
The DataInstance element contains one first-level child element per DataRow object of data in the
DataSet object’s tables (hereafter, first-level child elements of the DataInstance element are
referred to as "DataRow elements"). Each DataRow in the DataSet MUST be serialized by using
the XML element (defined in the <schema> element of the DiffGram) that corresponds to its
DataTable object.
The DataRow values in the DataInstance element MUST be the current DataRow values in the
DataSet at the time the DataSet is serialized into the DiffGram structure. That is, the
DataInstance element MUST reflect all changes made to the DataRow values within the DataSet
and the new rows that were added after the DataSet was last synchronized with its data source.
Rows that were deleted from the DataSet MUST NOT appear in the DataInstance element.
<SalesDS>
<Customers diffgr:id="Customers1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
<CustId>A</CustId>
<CustName>C1</CustName>
</Customers>
42 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The following rules apply to the DataRow elements within the DataInstance element:
Row elements that represent rows that were added or modified in the DataSet after it was last
synchronized with its data source MUST have the urn:schemas-microsoft-com:xml-diffgram-
v1:hasChanges attribute. This attribute’s value MUST be "inserted" for rows that were added to
the DataSet after it was last synchronized with its data source, and the value MUST be
"modified" for rows that were changed after the DataSet was last synchronized with its data
source.
Only DataRow elements that represent rows that are associated with error information that is
included in the <errors> element of the DiffGram MUST have the urn:schemas-microsoft-
com:xml-diffgram-v1:hasErrors attribute set to "true".
All DataColumn objects for which the ColumnMapping property equals Attribute MUST write out
the name of the DataColumn as the attribute name and the value of that DataColumn within
the DataRow element.
All DataColumn objects for which the ColumnMapping property equals Element MUST write
out the name of the DataColumn as the child element of the DataRow element along with the
corresponding value of that DataColumn within the DataRow element.
For all DataColumn objects for which the ColumnMapping property equals Hidden, the
msdata:hidden[ColumnName] attribute MUST be used. For example, <Customers
diffgr:id="Customers1" msdata:hiddenContactTitle="Owner"> would specify a hidden column
named ContactTitle.
Only if the schema for this data instance is nested MUST the data instance be nested as well. The
following is an example of this.
43 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
The <before> element contains the original values of rows that were modified or deleted in the
DataSet object after it was originally loaded. For each modified or deleted DataRow object, the
<before> element MUST contain a first-level child element that serializes the original values for the
DataRow as it was first loaded into the DataSet (before any modifications were made).
As is true for the DataInstance element, each DataRow MUST be serialized by using the XML
element (defined in the <schema> element of the DiffGram) that corresponds to its DataTable.
Hereafter, first-level child elements of the <before> element are referred to as "before DataRow
elements".
Rows that were not changed or deleted in the DataSet after it was last synchronized with its data
source MUST NOT appear in the <before> element. Rows that were added to the DataSet after it
was last synchronized with its data source MUST NOT appear in the <before> element.
<diffgr:before>
<Customers diffgr:id="Customers3" msdata:rowOrder="2">
<CustId>C</CustId>
<CustName>C33</CustName>
</Customers>
<Customers diffgr:id="Customers4" msdata:rowOrder="3">
<CustId>D</CustId>
<CustName>C4</CustName>
</Customers>
</diffgr:before>
The following rules apply to the before DataRow elements within the <before> element:
44 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Only <before> DataRow elements that represent rows that are associated with error
information that is included in the <errors> element of the DiffGram MUST have the
urn:schemas-microsoft-com:xml-diffgram-v1:hasErrors attribute set to true.
The <errors> element is used to serialize application-specified error information that is associated
with rows in a DataSet object. Similar to the DataInstance element and <before> element, error
information for a given DataRow object MUST be serialized by using the XML element (defined in the
<schema> element of the DiffGram structure) that corresponds to the DataTable of the DataRow.
Each first-level child element within the <errors> element (hereafter referred to as an "error
DataRow element") represents the error information associated with a single DataRow.
The following rules apply to the error DataRow elements within the <errors> element:
For every error DataRow element, the DiffGram structure’s DataInstance element or
<before> element MUST contain a corresponding DataRow element or before DataRow
element that has the same urn:schemas-microsoft-com:xml-diffgram-v1:id attribute value and
whose urn:schemas-microsoft-com:xml-diffgram-v1:hasErrors attribute is set to true.
<diffgr:errors>
<Customers diffgr:id="Customers5" diffgr:Error="This customer data is not correct">
<CustName diffgr:Error="This customer DataRow DataColumn value is not correct" />
</Customers>
</diffgr:errors>
45 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Relationships
Constraints
Changes to the data in the Before section (showing the data in different states, including
modified, inserted, and deleted).
46 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
47 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
48 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
49 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
50 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
51 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
52 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Exceptions, if any, are noted below. If a service pack or Quick Fix Engineering (QFE) number
appears with the product version, behavior changed in that service pack or QFE. The new behavior
also applies to subsequent service packs of the product unless otherwise specified. If a product
edition appears with the product version, behavior is different in that product edition.
Unless otherwise specified, any statement of optional behavior in this specification that is prescribed
using the terms SHOULD or SHOULD NOT implies product behavior in accordance with the SHOULD
or SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that the product
does not follow the prescription.
<1> Section 2.3: DataSet uses only those prefixes that are specified in the table.
<2> Section 2.3.1.1.14: The <simpleType> element within complexTypes: DataSet always writes
out the non-fully qualified form for types that are described in section 2.2.3.
<3> Section 2.3.1.1.15: DataSet always writes out the non-fully qualified form for types that are
described in section 2.2.3.
53 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
54 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
D ref attribute 24
referencing namespaces 18
data types root element 18
DataColumn object 12
DataSet object 12 S
DataSet objects 12
mapping (section 2.2.2 14, section 2.2.3 16) schema element 18
XSD keywords 17 schema mapping 19
55 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure
Tracking changes 54
types
DataColumn object 12
DataSet object 12
DataSet objects 12
mapping (section 2.2.2 14, section 2.2.3 16)
XSD keywords 17
UniqueConstraint object 10
User Datagram Protocol (UDP) 7
Web services 7
XML mapping 19
XMLSchema1 18
XMLSCHEMA2 types
DataSet data types 12
mapping from .NET Framework 16
mapping to .NET Framework 14
XSD keywords 17
XSD keywords 17
56 / 56
[MS-DSDG] — v20111108
DataSet DiffGram Structure