Document Schema Rules

  • Article

Important

This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

This topic describes the schema rules and conventions for the document schemas in Application Integration Framework (AIF). Each document in AIF has a schema that defines the structure and format of the XML that the document can serialize and deserialize. This is called the document XML Schema Definition (XSD) or the schema. The document schema defines the structure and format for all possible fields in the document.

Note

When you create an integration port for an exchange, you can enable different fields per document. You can set the fields on the Data policies form. For more information, see Customize service contracts.

Document XSD

In AIF, the schema for each document is generated by iterating through the query associated with the document class. For example, the PurchPurchReqService document service class is associated with document class AxdPurchaseRequisition and a query by the same name. The data source for this query contains multiple nested tables with the VendPurchOrderJour table at the parent level.

When an XML document is sent or received in AIF, the XML can be validated against the document schema. Microsoft Dynamics AX generates the schema internally by calling the getSchema method from the document data object as shown in the following diagram. The getSchema method is not overridden by the document object so the call is passed on to the base class AfStronglyTypedDataContainer which implements the AifXmlSerializable interface.

Warning

The getSchema method is not overridden by default.

Getting the Document Schema

The classes AIF uses to build the document schema

The document schema is generated directly from the document query. During schema generation, if an Ax <Table> class exists for a table in the query, the elements in the schema that represent the source table fields are built from that Ax <Table> class; otherwise, the elements are built from the source table referenced in the query. For more information about generating a document schema (.xsd) file, see How to: Generate a Document Schema.

XSD Naming Conventions

The following table shows the conventions used by AIF when naming schema elements. These conventions are used to ensure that none of the schema element names conflict with other names like the document name, query name, and so on.

Element prefix

Element type

Description

<none>

Document

None

AxdEntity_

Data source

A complexType element is generated for each data source in the query. In the schema, each data source name must be unique so the name is prefixed by "AxdEntity_", for example, AxdEntity_<DS_Name>.

AxdExtType_

Extended data types

An <xsd:simpleType> element is generated for each field or property of an extended data type that is to be included in the XML document if that field or property is not derived from a Container X++ data type. The name of the generated <xsd:simpleType> is the name of the extended data type prefixed with "AxdExtType_", for example AxdExtType_RecVersion.

AxdUnion_

Unions

If the extended data type, for which a <xsd:simpleType> element is being created, is subject to value mapping, then the field element will reference an <xsd:union> between the data type of the field and the type representing the external values. This element is a union between the data type of the value mapped field and the type representing the external values, as shown in the following schema XML.

<xsd:simpleType  name="AxdUnion_AxdExtType_<ExtendedDataTypeName>_AxdType_ExtCodeValue">
    <xsd:union memberTypes="AxdExtType_<ExtendedDataTypeName>AxdType_ExtCodeValue" />
</xsd:simpleType>

AxdArray_

Arrays

A schema element is created for each field or property of an extended data type that is to be included in the XML document if that field or property is not derived from a Container X++ data type and has an ArrayLength greater than 1. This element has the format AxdArray_AxdExtType_<ExtendedDataTypeName>.

AxdEnum_

Enumerations

An <xsd:simpleType> element is generated for each field or property of an enumerated data type that is to be included in the XML document. The name of the generated <xsd:simpleType> is the name of the enumerated data type prefixed with "AxdEnumType_", for example AxdEnum_<DataType>.

AxdEntityKey_

Surrogate key

A schema element is generated for each reference data source that is used by each data source in the query. The element has the form AxdEntityKey_<DataSourceName_ReferenceDataSourceName>. For more information, see Table Keys: Surrogate, Alternate, Replacement, Primary, and Foreign.

Mapping Data Types

In a document schema, the following X++ data types are mapped to their corresponding XSD types.

X++ data type

XSD type

string

xsd:string, maxLength=StringSize

(maxLength=max(StringSize,50) in case of value mapping)

integer

xsd:int

timeOfDay

xsd:time, ISO format: HH:MM:SS

(Time stamp if global::isTypeTime is true)

int64

xsd:long

real

xsd:decimal, fractionDigits=NoOfDecimals

date

xsd:date, ISO format: YYYY-MM-DD

utcdatetime

xsd:datetime

enum

xsd:string, enumeration=<EnumName>, ...

GUID

xsd:string, pattern=’[0-9A-Fa-f]{8}-...’

BLOB

xsd:string, Base64 encoded

Note

The schemas in AIF are strongly typed. Incorrect data types will cause an error during schema validation. This enables errors to be captured as early as possible in an exchange.

Other Data Considerations

Null Values

Outbound Null Values

Null values are not serialized for outbound documents. Arrays can contain empty elements and will be serialized.

Inbound Null Values

Empty string elements are interpreted as zero-length strings and not null values when processing an inbound document.

Use <element xsi:nil="true"/> to specify a null value.

Time Values

When .NET serializes time values to XML, it includes fractional seconds and an offset. For example, .NET could create an XML element like the following:

<AxTime>23:18:29.8108671-08:00</AxTime>

AIF will accept an XML time value in this format. However, when it deserializes a time value, the fractional seconds and offset are truncated and the value will contain hours, minutes, and seconds (hh:mm:ss). AIF deserializes the previous time value to the following:

<AxTime>23:18:29</AxTime>

Note

AIF does not support the timespan type in .NET data contracts. If you create a data contract class with a timespan data member and attempt to consume the service, you will receive an error message containing information resembling “The InnerException message was 'There was an error deserializing the object of type DotNetDataContractsAssembly.NonPrimitiveTypes.NonPrimitiveTypesDataContractClass. The value '01:02:03' cannot be parsed as the type 'TimeSpan'.'.”.

Time Zone Values

Some documents contain time zone elements. The schema time zone values correspond to the time zone values in the time zone system enum. For more information, see Timezone Enumeration and Time Zone Overview and Terminology.

The valid time zone values are specified in the document schema as shown in the following XML.

<xs:simpleType name="AxdEnum_Timezone">
    <xs:annotation>
        <xs:documentation xml:lang="EN-US">:</xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string">
        <xs:enumeration value="GMTMINUS1200INTERNATIONALDATELINEWEST"/>
        <xs:enumeration value="GMTMINUS1100MIDWAYISLAND_SAMOA"/>
        <xs:enumeration value="GMTMINUS1000HAWAII"/>
        <xs:enumeration value="GMTMINUS0900ALASKA"/>
        <xs:enumeration value="GMTMINUS0800PACIFICTIME"/>
        <xs:enumeration value="GMTMINUS0800TIJUANA_BAJACALIFORNIA"/>
        <xs:enumeration value="GMTMINUS0700ARIZONA"/>
        <xs:enumeration value="GMTMINUS0700MOUNTAINTIME"/>
        <xs:enumeration value="GMTMINUS0700CHIHUAHUA_LAPAZ_MAZATLAN"/>
        <xs:enumeration value="GMTMINUS0600CENTRALAMERICA"/>
        <xs:enumeration value="GMTMINUS0600CENTRALTIME"/>
        <xs:enumeration value="GMTMINUS0600GUADALAJARA_MEXICOCITY"/>
        <xs:enumeration value="GMTMINUS0600SASKATCHEWAN"/>
        <xs:enumeration value="GMTMINUS0500BOGOTA_LIMA_QUITO_
            RIOBRANCO"/>
        <xs:enumeration value="GMTMINUS0500EASTERNTIME"/>
        <xs:enumeration value="GMTMINUS0500INDIANA"/>
        <xs:enumeration value="GMTMINUS0400ATLANTICTIME"/>
        <xs:enumeration value="GMTMINUS0400CARACAS_LAPAZ"/>
        <xs:enumeration value="GMTMINUS0400MANAUS"/>
        <xs:enumeration value="GMTMINUS0400SANTIAGO"/>
        <xs:enumeration value="GMTMINUS0330NEWFOUNDLAND"/>
        <xs:enumeration value="GMTMINUS0300BRASILIA"/>
        <xs:enumeration value="GMTMINUS0300BUENOSAIRES_GEORGETOWN"/>
        <xs:enumeration value="GMTMINUS0300GREENLAND"/>
        <xs:enumeration value="GMTMINUS0300MONTEVIDEO"/>
        <xs:enumeration value="GMTMINUS0200MIDATLANTIC"/>
        <xs:enumeration value="GMTMINUS0100AZORES"/>
        <xs:enumeration value="GMTMINUS0100CAPEVERDIS"/>
        <xs:enumeration value="GMT_CASABLANCA_MONTROVIA_REYKJAVIK"/>
        <xs:enumeration value="GMT_DUBLIN_EDINBURGH_LISBON_LONDON"/>
        <xs:enumeration value="GMTPLUS0100_AMSTERDAM_BERLIN_BERN_
            ROME"/>
        <xs:enumeration value="GMTPLUS0100BELGRADE_BRATISLAVA_
            BUDAPEST"/>
        <xs:enumeration value="GMTPLUS0100BRUSSELS_COPENHAGEN_
            MADRID"/>
        <xs:enumeration value="GMTPLUS0100SARAJEVO_SKOPJE_WARSAW_
            ZAGREB"/>
        <xs:enumeration value="GMTPLUS0100WESTCENTRALAFRICA"/>
        <xs:enumeration value="GMTPLUS0200AMMAN"/>
        <xs:enumeration value="GMTPLUS0200ATHENS_BUCHAREST_ISTANBUL"/>
        <xs:enumeration value="GMTPLUS0200BEIRUT"/>
        <xs:enumeration value="GMTPLUS0200MINSK"/>
        <xs:enumeration value="GMTPLUS0200CAIRO"/>
        <xs:enumeration value="GMTPLUS0200HARARE_PRETORIA"/>
        <xs:enumeration value="GMTPLUS0200HELSINKI_KYIV_RIGA_VILNIUS"/>
        <xs:enumeration value="GMTPLUS0200JERUSALEM"/>
        <xs:enumeration value="GMTPLUS0200WINDHOEK"/>
        <xs:enumeration value="GMTPLUS0300BAGHDAD"/>
        <xs:enumeration value="GMTPLUS0300KUWAIT_RIYADH"/>
        <xs:enumeration value="GMTPLUS0300MOSCOW_STPETERSBURG_
            VOLGOGRAD"/>
        <xs:enumeration value="GMTPLUS0300NAIROBI"/>
        <xs:enumeration value="GMTPLUS0300TBILISI"/>
        <xs:enumeration value="GMTPLUS0330TEHRAN"/>
        <xs:enumeration value="GMTPLUS0400ABUDHABI_MUSCAT"/>
        <xs:enumeration value="GMTPLUS0400BAKU"/>
        <xs:enumeration value="GMTPLUS0400YEREVAN"/>
        <xs:enumeration value="GMTPLUS0430KABUL"/>
        <xs:enumeration value="GMTPLUS0500EKATERINBURG"/>
        <xs:enumeration value="GMTPLUS0500ISLAMABAD_KARACHI_TASHKENT"/>
        <xs:enumeration value="GMTPLUS0530CHENNAI_KOLKATA_MUMBAI"/>
        <xs:enumeration value="GMTPLUS0530SRIJAYAWARDENEPURA"/>
        <xs:enumeration value="GMTPLUS0545KATHMANDU"/>
        <xs:enumeration value="GMTPLUS0600ALMATY_NOVOSIBIRSK"/>
        <xs:enumeration value="GMTPLUS0600ASTANA_DHAKA"/>
        <xs:enumeration value="GMTPLUS0630_YANGON"/>
        <xs:enumeration value="GMTPLUS0700_BANGKOK_HANOI_JAKARTA"/>
        <xs:enumeration value="GMTPLUS0700KRASNOYARSK"/>
        <xs:enumeration value="GMTPLUS0800BEIJING_CHONGQING_HONGKONG"/>
        <xs:enumeration value="GMTPLUS0800IRKUTSK_ULAANBATAAR"/>
        <xs:enumeration value="GMTPLUS0800KUALALUMPUR_SINGAPORE"/>
        <xs:enumeration value="GMTPLUS0800PERTH"/>
        <xs:enumeration value="GMTPLUS0800TAIPEI"/>
        <xs:enumeration value="GMTPLUS0900OSAKA_SAPPORO_TOKYO"/>
        <xs:enumeration value="GMTPLUS0900SEOUL"/>
        <xs:enumeration value="GMTPLUS0900YAKUTSK"/>
        <xs:enumeration value="GMTPLUS0930ADELAIDE"/>
        <xs:enumeration value="GMTPLUS0930DARWIN"/>
        <xs:enumeration value="GMTPLUS1000BRISBANE"/>
        <xs:enumeration value="GMTPLUS1000CANBERRA_MELBOURNE_SYDNEY"/>
        <xs:enumeration value="GMTPLUS1000GUAM_PORTMORESBY"/>
        <xs:enumeration value="GMTPLUS1000HOBART"/>
        <xs:enumeration value="GMTPLUS1000VLADIVOSTOK"/>
        <xs:enumeration value="GMTPLUS1100MAGADAN_SOLOMONIS"/>
        <xs:enumeration value="GMTPLUS1200AUCKLAND_WELLINGTON"/>
        <xs:enumeration value="GMTPLUS1200FIJI_KAMCHATKA_MARSHALLIS"/>
        <xs:enumeration value="GMTPLUS1300NUKU_ALOFA"/>
    </xs:restriction>
</xs:simpleType>

See also

Document Schemas

How to: Generate a Document Schema

Document XML Generation