OpenTravel™ Alliance XML Schema Design Best Practices

Version 3.04 June 2006

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 2

1 2 3

OTA XML Schema Design Best Practices............................................................................. 4 XML Standard Specifications................................................................................................. 5 Best Practices.......................................................................................................................... 6 3.1 Scope.............................................................................................................................. 6 3.2 Schema Design Component Parts and Roles ................................................................. 6 4 OTA XML Schema Design Guidelines .................................................................................. 7 4.1 Tag Naming Conventions .............................................................................................. 7 4.1.1 Mixed Case ................................................................................................................ 7 4.1.2 Underscore................................................................................................................. 7 4.1.3 Acronyms................................................................................................................... 7 4.1.4 Word Abbreviations................................................................................................... 7 4.1.5 Tag Length................................................................................................................. 8 4.1.6 Complex Type Tag Names ........................................................................................ 8 4.1.7 Simple Type Tag Names 1 ........................................................................................ 8 4.1.8 Simple Type Tag Names 2 ........................................................................................ 8 4.1.9 Naming of Elements Based on Simple or Complex Types........................................ 8 4.1.10 Naming of Attributes Based on Simple Types ...................................................... 8 4.1.11 Common Suffixes.................................................................................................. 9 4.1.12 Standard Suffixes .................................................................................................. 9 4.2 Root Element, Message, and File Naming Conventions.............................................. 10 4.2.1 Root Element Naming ............................................................................................. 10 4.2.2 Use of Notif in Root Element Name........................................................................ 11 4.2.3 Message XML Schema File Naming....................................................................... 11 4.2.4 File naming for collections of Attribute Groups, Simple, and Complex Types ...... 11 4.2.5 Naming of XML Schema Files that Contain Common Components ...................... 11 4.3 Use of Elements and Attributes .................................................................................. 11 4.3.1 Elements vs. Attributes............................................................................................ 11 4.3.2 Number of Attributes per Element .......................................................................... 12 4.3.3 Encapsulating Element ............................................................................................ 12 4.4 Use of XML Schema.................................................................................................... 13 4.4.1 OTA Specification Uses XML Schema................................................................... 13 4.5 Global vs. Local Element Types .................................................................................. 13 4.5.1 Simple and Complex Types..................................................................................... 13 4.5.2 Type Attribute vs. Ref Attribute.............................................................................. 13 4.5.3 Attribute Groups ...................................................................................................... 14 4.6 Namespaces.................................................................................................................. 14 4.6.1 OTA Namespace...................................................................................................... 14 4.6.2 No Namespace for Common XML Schema Files ................................................... 15 4.6.3 Use of OTA Namespace in Instance Documents..................................................... 15 4.7 Versioning XML Schemas........................................................................................... 16 4.7.1 Version Attribute in XML Schema.......................................................................... 16 4.7.2 Version Attribute in Common XML Schema Files ................................................. 16 4.7.3 Version Attribute in XML Instance Documents...................................................... 16 4.7.4 ID Attribute in Message and Common XML Schema ............................................ 17 4.7.5 Use of schemaLocation Attribute ............................................................................ 17 4.8 Schema Markup and Annotations ................................................................................ 17 4.8.1 Use of Annotation and Document Elements............................................................ 17 4.8.2 Use of lang Attribute ............................................................................................... 18 4.8.3 Meaningful Annotations .......................................................................................... 18
© 2005 OpenTravel™ Alliance www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 3

4.8.4 Annotation of Typed Elements ................................................................................ 18 4.8.5 Annotations of Root Elements................................................................................. 19 4.8.6 Use of “may be”....................................................................................................... 19 4.8.7 Reference to Code Tables........................................................................................ 19 4.8.8 No Use of Processing Instructions........................................................................... 20 4.9 Enumerations vs. Code Lists........................................................................................ 20 4.9.1 Use of Enumerations................................................................................................ 20 4.9.2 Use of Code Lists .................................................................................................... 20 4.10 Code Lists .................................................................................................................... 20 4.10.1 Name of Code List Table .................................................................................... 20 4.11 OTA General................................................................................................................ 21 4.11.1 Required Attributes of XML Instance Root Elements ........................................ 21 4.11.2 Use of TPA_Extensions ...................................................................................... 21 4.11.3 Standard Simple Types vs. OTA Simple Types.................................................. 22 4.11.4 New Data Types Based on Extending Existing Types........................................ 22 4.11.5 Simple Type Restrictions .................................................................................... 22 4.11.6 Deprecation Policy .............................................................................................. 23 4.11.7 License Agreement Documentation .................................................................... 23

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 4

1 OTA XML Schema Design Best Practices
The IT Business world has long employed the principles of producing high quality products with a reduction of product development cost and faster “time-to-market” product delivery. In today’s global, Internet-ready marketplace, these principles are as critical to the bottom line as ever. One way that corporations can apply these “increased earning potential principles” is by establishing a common set of best practice XML and XML Schema guidelines. The current W3C XML specifications were created to satisfy a very wide range of diverse applications, which is why there may be no single set of “good” guidelines on how best to apply XML technology. However, when the application environment can be restricted by corporate direction or by a common domain, one can determine, by well-informed consensus, a set of effective guidelines that will lead to the best practice of using XML in that environment. This document defines the OpenTravel™ Alliance (OTA) Best Practices Guidelines for all of the OTA XML data assets. OTA message specifications released prior to the 2002A Specification release may not follow the guidelines defined in this document.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 5

2 XML Standard Specifications
Currently, there are several XML related specification recommendations produced by W3C (http://www.w3.org/Consortium/). This section refers to the W3C recommendations (http://www.w3.org/Consortium/Process-20010719/) and versions listed below: • Extensible Markup Language (XML) 1.0 (Second Edition): • • http://www.w3.org/TR/2000/REC-xml-20001006

XML Schema Parts 0 - 2: • • • • http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/ http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/ http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 6

3 Best Practices
3.1 Scope
The OTA Best Practices Guidelines cover all of the OTA XML components (elements, attributes, tag names, and Schema definitions). This document defines guidelines for all OTA XML data assets. The general OTA guideline approach is to maximize component (element/attribute) reuse for the highly diverse and yet closely related travel industry data. This is accomplished by building messages via context-driven component assembly. An example is the construction of a ‘Flight Leg’ segment from base objects such as ‘Time,’ ‘Date,’ and ‘Location’ (departure/arrival). The best mechanism that XML Schemas have to support this approach is by encapsulating lower level components (element and attribute objects) within named type definitions while using (and reusing) these base components to construct messages.

3.2 Schema Design Component Parts and Roles
The critical XML Schema guidelines that best support the OTA goal of a consistent set of reusable travel industry message content are listed below: • • • • • • • • • • • Tag Naming conventions Root Element, Message, and File Naming Conventions Elements and Attributes Use of XML Schema Global vs. Local Element Types Namespaces Versioning XML Schemas Schema Markup and Annotations Enumerations vs. Code Lists Code Lists General

Each of the items above plays a unique role, supporting a common vocabulary, syntax, and semantic grammar for XML Schema and XML component (element and attribute) definitions.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 7

4 OTA XML Schema Design Guidelines
The subsections below form the complete set of OTA XML Schema Design Best Practices Guidelines. Each guideline is presented as follows: Guideline: The base rule (or rules) that should be followed for compliance with OTA Best Practices. Rationale: OTA general consensus reasoning for the guideline. Example:
An example (if applicable).

4.1 Tag Naming Conventions
4.1.1 Mixed Case
Guideline: Use mixed case tag names, with the leading character of each word in upper case and the remainder in lower case without the use of hyphens or spaces between words (a.k.a. Upper Camel Case (UCC) or “PascalCasing”). Rationale: This format increases readability and is consistent with common industry practices. Example:

4.1.2 Underscore
Guideline: Where the merger of tag name words and acronyms causes two upper case characters to be adjacent, separate them with an underscore (‘_’). Rationale: This technique eliminates or reduces any uncertainty for tag name meaning. Example:

4.1.3 Acronyms
Guideline: Acronyms are discouraged, but where needed, use all upper case. Rationale: In some cases, common acronyms inhibit readability. This is especially true for internationally-targeted audiences. However, in practice, business requirements and/or physical limitations may require the need to use acronyms. Example:

4.1.4 Word Abbreviations
Guideline: Word abbreviations are discouraged. However, where needed, use UCC camel case. Rationale: Abbreviations may inhibit readability. This is especially true for internationallytargeted audiences. However, in practice, business requirements and/or physical limitations may require the need to use abbreviations. Example:

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 8

4.1.5 Tag Length
Guideline: Element and attribute names should not exceed 25 characters. Tag names should be spelled out except where they exceed 25 characters, when standardized abbreviations should be applied. Rationale: This approach can reduce the overall size of a message significantly and limit impact to any bandwidth constraints. Example:
The tag: can be reduced to:

4.1.6 Complex Type Tag Names
Guideline: Complex type tag names should be suffixed with the word “Type” Rationale: This approach allows for complex types to be easily recognized, which encourages reuse. Example:

4.1.7 Simple Type Tag Names 1
Guideline: OTA data type simpleType tag names should clearly indicate the pattern that is used to define the simple type. Rationale: This approach supports meaningful tag names. Example:

4.1.8 Simple Type Tag Names 2
Guideline: All other OTA simpleType tag names should clearly indicate the usage of that type and should be suffixed with the word “Type”. Rationale: This approach supports meaningful tag names. Example:

4.1.9 Naming of Elements Based on Simple or Complex Types
Guideline: Elements that are based on complex or simple types must not be suffixed by “ComplexType,” “SimpleType,” or “Type.” Rationale: This technique reserves the “Type” suffix for complex and simple types, which allows for easy identification and reuse of types. Example: of type ProfilesType of type UniqueID_Type

4.1.10

Naming of Attributes Based on Simple Types

Guideline: Attributes that are based on simple types must not be suffixed by “SimpleType” or “Type”

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 9

Rationale: This technique reserves the “Type” suffix for complex and simple types, which allows for easy identification and reuse of types. Example: of type StringLength1to32 of type UpperCaseAlphaNumericLength3to5

4.1.11

Common Suffixes

Guideline: Use common tag name suffixes for elements defined by similar or common XML Schema type definitions. Rationale: This approach supports a consistent syntax and semantic meaning for elements and attributes. Example:

4.1.12

Standard Suffixes

Guideline: The OTA XML Schema attribute declarations should incorporate the following list of suffixes. These suffixes were taken from the list of Representation Terms found in the Core Components Technical Specification (CCTS) published by UN/CEFACT1. For simplicity, a ‘Representation Term’ is referred to here as a ‘Suffix’. For cases in which the length of an attribute name may exceed the 25 character limit, the Suffix abbreviation (included parenthetically) should be used since it requires fewer characters. Suffix Amount (Amt) Binary Object (BinObj) Definition A number of monetary units specified in a currency where the unit of currency is explicit or implied A set of finite-length sequences of binary octets. [Note: This Suffix shall also be used for Data Types representing graphics (i.e., diagram, graph, mathematical curves, or similar representation), pictures (visual representation of a person, object, or scene), sound, video, etc.] A character string (letters, figures, or symbols) that for brevity and / or language independence may be used to represent or replace a definitive value or text of a Property. [Note: The term 'Code' should not be used if the character string identifies an instance of an Object Class or an object in the real world, in which case the Suffix identifier should be used.]

Code

United Nations Centre for Trade Facilitation and Electronic Business Core Components Technical Specification- part 8 of the ebXML Framework 15 November 2003 Version 2.01. Available on-line at < http://www.untmg.org/doc_tmg.html>.

1

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 10

Suffix DateTime, Date, Time

Definition A particular point in the progression of time (ISO 8601). [Note: This Suffix shall also be used for Data Types representing only a Date or a Time.]. Examples: (CCYY-MM-DD); (hh:mm:ss[.ssss…[Z | +/-hh:mm]]); (CCYY-MM-DD [Thh:mm:ss [.ssss…[Z | +/-hh:mm]]])

Identifier (ID)

A character string used to establish the identity of, and distinguish uniquely, one instance of an object within an identification scheme from all other objects within the same scheme. A list of exactly two mutually exclusive Boolean values that expresses the only possible states of a Property. [Note: Indicated by a Boolean data type.] A numeric value determined by measuring an object. Measures are specified with a unit of measure. The applicable unit of measure is taken from UN/ECE Rec. 20. [Note: This Suffix shall also be used for measured coefficients (e.g., m/s).] Numeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or a unit of measure. [Note: This Suffix shall also be used for Data Types representing Ratios (rates where the two units are not included or where they are the same), Percentages, etc.] A counted number of non-monetary units. Quantities need to be specified with a unit of quantity. [Note: This Suffix shall also be used for counted coefficients (e.g., flowers/m²).] A character string (i.e., a finite set of characters) generally in the form of words of a language. [Note: This Suffix shall also be used for names (i.e., word or phrase that constitutes the distinctive designation of a person, place, thing, or concept).]

Indicator (Ind)

Measure (Meas)

Numeric (Num), Value, Rate, Percent (Pct) Quantity (Qty)

Text

Rationale: This approach supports a consistent syntax and semantic meaning for OTA XML Schema attribute declarations, which is where most OTA data is passed.

4.2 Root Element, Message, and File Naming Conventions
4.2.1 Root Element Naming
Guideline: The format of root elements for messages shall be “OTA_” + Vertical name or area of focus + function + RQ or RS. Rationale: This format allows for easy identification of message, Vertical, and function.
© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 11

Example:

4.2.2 Use of Notif in Root Element Name
Guideline: The word “Notif” in a message name indicates that this message does not follow the normal requirements of a Request/Response transaction. This type of message provides (pushes) information from the originator to the recipient in support of a trading partner agreement. Rationale: This technique allows for quick and easy identification of push messages. Example:

4.2.3 Message XML Schema File Naming
Guideline: The .xsd file is given the same name as the root element of the XML Schema. Rationale: Easily identifies the contents of the .xsd file. Example:
Root element: File name: OTA_AirFlifoRQ.xsd

4.2.4 File naming for collections of Attribute Groups, Simple, and Complex Types
Guideline: CommonType and SimpleType XML Schema files are used to house attribute groups, simple types, and complex types that are used among multiple messages. Items that apply to a specific Vertical are housed in a common file that includes the Vertical name. Rationale: This approach easily identifies reusable components. Example:

4.2.5 Naming of XML Schema Files that Contain Common Components
Guideline: Schema files that are not used as messages by themselves, but contain components for use in messages, should not contain RQ or RS in the Schema name. These files are primarily used for maintaining consistency between common message structures, usually in an RQ/RS set and its Notif counterparts. Rationale: This approach allows for easy differentiation between messages and message components. Example:

4.3 Use of Elements and Attributes
4.3.1 Elements vs. Attributes

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 12

Guideline: For a given OTA data requirement, the preferred method is to represent that data as an attribute. The data is represented as an element if and only if: • • • • it is not atomic (i.e., it has attributes or child elements of its own) OR the anticipated length of the data is greater than 64 characters2 OR

the data requires a choice or branch within the schema OR it is likely that the data in question will be extended in the future

Rationale: The intention is to create a consistent OTA message design approach and to reduce the overall message size as well as avoid the potential of tag name collisions. Example: In the following example, ‘LocationDescription’ is defined as an element since the text it contains is greater than 64 characters. ‘LocationCode’, however, is defined as an attribute since it contains a 3 character code and is not likely to be extended.
Element: Five miles South of highway 85 and Main St. intersection next to Town Square Mall Attribute:

4.3.2 Number of Attributes per Element
Guideline: Element tags should not be overloaded with too many attributes (no more than 10 as a rule of thumb); instead, encapsulate attributes within child elements that are more closely related (or more granular). This should be done for those attributes that are likely to be extended by OTA or by specific trading partners. Rationale: This approach maintains the built-in extensibility that XML provides with elements and is necessary to provide forward compatibility as the specification evolves. It also provides a consistent guide to the level of granularity used to compose OTA Schema objects (or fragments).

4.3.3 Encapsulating Element
Guideline: XML element containers should be used for repeating elements if the XML Schema 'maxOcc' attribute exceeds 5 repetitions. The encapsulating element container is optional if the XML Schema 'maxOcc' attribute is less-than or equal to 5. However, a single XML container can be used for "simpleType" repeating content (via the XML Schema "list" construct). OTA work groups have the option to override this guideline if: 1) Adding the container to existing repeating elements would break backward compatibility. 2) The work group believes that, in practice, there will be minimal instances of messages that will use more than 5 occurrences, such that adding a container adds an unnecessary layer. With respect to this guideline, an OTA work group can remove existing containers only when backwards compatibility is already being broken. Rationale: This technique provides consistency for repeating data fields. Example:

2

URLs are considered to be less than 64 characters.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 13

complexTypes NY FL CA simpleTypes NY FL CA or

4.4 Use of XML Schema
4.4.1 OTA Specification Uses XML Schema
Guideline: The XML Schema recommendations from W3C should be used to define all XML message documents. Rationale: • • Schemas are written in XML syntax, rather than complex SGML regular expression syntax. Because XML Schemas are themselves well-formed XML documents, they can be programmatically generated and validated using a meta-schema -- a Schema used to define other Schema models. XML Schemas have built-in data types and an extensible data-typing mechanism. (DTDs understand only markup and character data.) Using XML syntax to define data model requirements allows for more constraints, strong data typing, etc. XML Schemas provide for a consistent Data Repository syntax.

• • •

4.5 Global vs. Local Element Types
4.5.1 Simple and Complex Types
Guideline: Define XML Schema element types globally in the namespace for the elements that are likely to be reused (instead of defining the type anonymously in the Element declaration). This applies to both simpleType and complexType element type definitions. Rationale: This approach supports a domain library or repository of reusable XML Schema components. Also, since simpleType and complexType names are not contained in XML instance documents, they can be verbose to avoid element type name collisions.

4.5.2 Type Attribute vs. Ref Attribute
Guideline: Define XML Schema elements as nested elements via the ‘type’ attribute or an inline type definition (‘simpleType’ or ‘complexType’) instead of the ‘ref’ attribute that references a global element. Rationale: This approach for local element naming reduces the possibility of tag name collisions and allows the creation of short tag names. Globally-defined elements should be reserved only

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 14

for travel domain elements with well-defined meanings; such global names should be constructed with sufficient roots and modifiers to identify their domain of use and avoid tag-name collisions. Example:

4.5.3 Attribute Groups
Guideline: Define common attribute parameters globally as a reusable component via the XML Schema ‘attributeGroup’ element definition. Rationale: This approach supports a domain library or repository of reusable XML Schema components. Also, since the names used for the XML Schema ‘attributeGroup’ components are not contained in XML instance documents, they can be verbose to avoid name collisions with other ‘attributeGroup’ definitions. Example:

4.6 Namespaces
4.6.1 OTA Namespace
Guideline: All OTA message Schemas are declared in one targetNamespace, which is http://www.opentravel.org/OTA/2003/05. However, during the specification review period, the domain name will include an extension of alpha or beta corresponding to member review and public review respectively. If additional releases are necessary, they would continue with gamma, delta, etc.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 15

Starting with release 2003A, the year and month on this targetNamespace is set to the initial publication of the 2003A OTA specification (the baseline specification). This value will not be changed in the subsequent releases, and the same namespace will also be used for new messages. The only reason to change the namespace would be to deprecate the 2003 baseline specification. This value would change to support the new OTA baseline specification, an action which should occur only on a 3- or 4-year cycle. Rationale: This approach supports a consistent way to manage and identify OTA XML-based transaction assets both internally and externally (via trading partners and global e-business repositories such as UDDI). It also avoids the need for explicit prefixes on both XML Schema and XML instance documents. Example: http://www.opentravel.org/OTA/2003/05 or http://www.opentravel.org/OTA/2003/05/alpha

Usage:

4.7.2 Version Attribute in Common XML Schema Files
Guideline: The ‘version’ attribute in the root element of OTA common data type Schema files (e.g., OTA_CommonTypes.xsd) will contain an independent self-describing version value (e.g., version=“19.127”, where ‘19’ is the major version and ‘127’ is the minor version). Rationale: Common data type Schema files (i.e., type definitions only) are version independent from message Schemas that may include them, and this content may be applied to multiple versions of a message. Example: The following example shows the header of an OTA common Schema file.

4.7.3 Version Attribute in XML Instance Documents
Guideline: XML instance documents being validated against an OTA message Schema will contain a ‘Version’ attribute on the root element. The value of this attribute should map directly to the value of the ‘Version’ attribute on the root ‘Schema’ element of the message Schema being used for validation. Rationale: This approach provides version correlation between XML instance message and the corresponding XML Schema.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 17

Example:
Schema value: version=”1.050” matches instance value: version=”1.050”

4.7.4 ID Attribute in Message and Common XML Schema
Guideline: The ‘id’ attribute in the root element of OTA XML Schemas will contain the release. The ‘id’ attribute in the root element of OTA common data type XML Schemas will contain the range release. The OTA specification manager will update the ‘id’ attribute of all schemas to the current release prior to publishing the schemas. The ‘id’ attribute is only found in the XML Schema, it is not used in the instance. Rationale: This attribute indicates the release in which the XML Schema was published. It is important to note that the ‘id’ attribute does not indicate if a message format has changed between releases, this is determined by comparing the ‘version’ attribute in the root element of the XML Schemas. Example:
Message schema files: id=”OTA2003A” CommonType schema files id=”OTA2003A2003B”

4.7.5 Use of schemaLocation Attribute
Guideline: The attribute schemaLocation is to be used on elements in instances to name the location of a retrievable Schema for that element associated with that namespace. Rationale: This approach supports use of OTA XML Schemas. Example:
Attribute: xsi:schemaLocation=”http://www.opentravel.org/OTA http://www.opentravel.org/OTA/2002AREC/VEH- availability/VehAvailRateRQ-23.xsd”

4.8 Schema Markup and Annotations
4.8.1 Use of Annotation and Document Elements
Guideline: OTA XML Schemas will use the sub-element of the element for Schema documentation. Rationale: Schema comments “” are not part of the core information set of a document and may not be available or in a useful form. Example: Privacy sharing control attributes.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 18

4.8.2 Use of lang Attribute
Guideline: Documentation elements will include the xs:lang attribute. The initial value of the attribute will be set to “en”. Rationale: This approach allows for future inclusion of documentation in other languages. Example: xs:lang="en" 4.8.3 Meaningful Annotations
Guideline: OTA requires that all complex types, simple types, elements, attribute groups, attributes, and enumerations are meaningfully annotated. • • • Complex type annotation: Describe the overall purpose of a complex type. Simple type annotation: Define the structure and its usage. Element annotation: Must describe the element in a meaningful manner so that the trading parties, who may not always have full understanding of the business context of the messages they are implementing, can understand the usage of the element. Attribute group: At the attribute group declaration, describe the overall functionality of the grouping. Within the element where the attribute group is referenced, include a description of the specific use of the attribute group. Attributes: Must include usage information. Enumerations: Provide an explanation of each value.

•

• •

Rationale: These standards enable the readers of a Schema to understand the usage of each data item. Example: This identifies the seat map details for the flight segment in the corresponding 'FlightSegmentInfo' element. If the responding system has different seat maps for different passengers for the same flight segment then this element will recur accordingly. The availability of seats can differ based upon various conditions, such as a passenger's status within a loyalty program or by the amount paid or class of service booked for the ticket. For example, if one passenger has a certain status in the Frequent Flyer program of the airline, certain desirable seats may be available for selection. A passenger without such status may not be able to select those seats. Thus the availability of seats can differ by passenger.

4.8.4 Annotation of Typed Elements
Guideline: Annotation of elements that are typed should reflect the specific usage of that complex or simple type at that location. If there is no additional specific usage information, then the global annotation found at the complex or simple type must be duplicated at the element level. Rationale: This approach enables the readers of a Schema to understand the usage of a typed element in its specific context. Example: The following example shows a complexType ‘AirItineraryType’ as defined in an OTA common Schema file. The ‘AirItinerary’ element following it is based on that complexType and contains a shorter annotation that describes only contextual usage of the content.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 19

Specifies the origin and destination of the traveler. Attributes: DirectionInd - A directional indicator that identifies a type of air booking, either one-way, round-trip, or open-jaw with the enumeration of (OneWay | RT | OpenJaw) respectively. ActionCode - Indicates the status of the booking, such as OK or Wait-List. NumberInParty - Indicates the traveler count. ... A collection of all flight segments requested for booking.

4.8.5 Annotations of Root Elements
Guideline: The root element of each RQ message shall include an overall description of the functionality of the message pair. If an RS message (e.g., OTA_ErrorRS) does not have a companion RQ message, then the full description of the message is to be included in the RS. Rationale: This approach enables the readers of a Schema to understand the functionality of a message. Example: The following example shows message-level annotation for the OTA_HotelAvailRQ Schema file. ... Requests availability of hotel properties by specific criteria that may include: dates, date ranges, price range, room types, regular and qualifying rates, and/or services and amenities. The availability message can be used to get an initial availability or to get availability for the purpose of modifying an existing reservation. ...

4.8.6 Use of “may be”
Guideline: The term “may be” is used only to indicate a possible use of an element or attribute; it does not denote that the element or attribute is optional. Optionality is defined in the Minimum Occurrence (MinOcc) indicator of the element and the Use indicator of the attribute. Rationale: Consistency in terminology helps eliminate confusion between usage and optionality. Example:
“May be used to give further detail on the code or to remove an obsolete item.”

4.8.7 Reference to Code Tables
Guideline: When the OTA_CodeType type is used, the following annotation must be included: "Refer to OTA Code List n..n (xxx)" where n..n is the name of an OTA Code List and xxx is its 3-character identifier.

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 20

Rationale: This reference enables the reader or implementer of a Schema to find the code values of the referenced OTA code table (within either the code list spreadsheet or the XML instance document). Example:
Refer to OTA Code List Room Amenity Type (RMA).

4.8.8 No Use of Processing Instructions
Guideline: OTA XML Schemas will avoid the use of Processing Instructions (PI) by replacing them with the sub-element of the element that supplies this functionality. Rationale: elements are available to users of the Schema. PIs require knowledge of their notation to be parsed correctly. Extensions to the XML Schema can be made using . An extension will not change the Schema-validity of the document.

4.9 Enumerations vs. Code Lists
4.9.1 Use of Enumerations
Guideline: Enumerations are used in the case where the list of values is static or there is little likelihood that additional values will be added. Rationale: This method allows for the values to be validated. Example:

4.9.2 Use of Code Lists
Guideline: Code lists are used in the case where the list of values is dynamic or there is great likelihood that additional values will be added. Rationale: This method allows for new codes to be added and used between releases. Example:
Communication Location Type 1 Home 2 Business 3 Other

4.10 Code Lists
4.10.1 Name of Code List Table www.opentravel.org/ © 2005 OpenTravel™ Alliance

OpenTravel™ Alliance Best Practices Specification

Page 21

Guideline: The name of a code list table should be the same or similar to the name of the attribute in XML Schema, but should be in plain English with spaces between the words. Rationale: This approach provides the reader or implementer with better understanding of how the code values are used. Example:
Code set name Coverage Type for Code set name Phone Technology Type for

4.11 OTA General
4.11.1 Required Attributes of XML Instance Root Elements

Guideline: The root element of all OTA payload documents (XML instance messages), must contain the following attributes:
• • •

xmlns=”http://www.opentravel.org/OTA/2003A/05” Version=”[current version here]” xmlns:xsi=”http://www.w3c.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://www.opentravel.org/…”

•

Rationale: This format provides a standard way to identify OTA payload messages, message version, and the corresponding XML Schema. Example:

4.11.2

Use of TPA_Extensions

Guideline: Trading partner-specific data can be included in an XML instance message within the global element at OTA-sanctioned plug-in points defined in the XML Schema. This element may also contain the Boolean attribute ‘mustProcess’, which notifies that the message receiver must process the ‘TPA_Extension’ data. TPA_Extension content implemented by specific Trading Partners should be cycled back into the appropriate OTA workgroup for consideration to be incorporated into the specification. Rationale: This approach (along with the versioning Guideline of VI-2) provides a standard way for OTA to integrate and manage specific trading partner information. By filtering the trading partner content back into the workgroups, the specification will better reflect the business needs of the OTA stakeholder community. Additionally, companies will enhance their interoperability by aligning to the published specification as opposed to TPA_Extension content. Example: Schema fragment:

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 22

Sample XML:

4.11.3

Standard Simple Types vs. OTA Simple Types

Guideline: Wherever possible, OTA Schema data types should use the standard built-in simple types defined in the XML Schema specification. Rationale: This approach simplifies OTA message implementation because validation tools support built-in XML Schema simple types.

4.11.4

New Data Types Based on Extending Existing Types

Guideline: Create new Schema data types by using or extending existing OTA type definitions or from built-in XML Schema types whenever possible. Rationale: This technique maximizes reuse and avoids duplicating definitions.

4.11.5

Simple Type Restrictions

Guideline: OTA XML Schemas should avoid rigid simpleType restrictions unless the type is a common industry standard which is unlikely to change. Rationale: This approach allows OTA messages to interoperate globally in a more seamless manner and allows any particular trading partner to locally restrict content values as needed for unique business requirements. Example: The following example represents a valid type restriction since Day of the Week is a common industry standard and is unlikely to change: A three letter abbreviation for the days of the week (e.g. may be the starting date for the availability requested, days of operation, rate effective day, etc.).

© 2005 OpenTravel™ Alliance

www.opentravel.org/

OpenTravel™ Alliance Best Practices Specification

Page 23

4.11.6

Deprecation Policy

Guideline: Any construct (e.g. attribute, element, simpletype, complextype) requiring deprecation shall be annotated in the Schema with the following annotation: Candidate for removal, usage is not recommended. Deprecation Warning added in 2005B.

The following shall be done to document the deprecation intention: • • Any company registered as using a message with a candidate for removal should be notified of the intention to remove the construct. If no registration of a message is documented, due diligence to determine if in fact there are implementations will be served by sending an email via the OTA maintained mail distribution lists to the most appropriate work group(s).

The period of time from which the depreciation is highlighted and any users of the construct notified, to the time of the actual deprecation shall be no less than one public review comment cycle (e.g. notification would be sent before public review and if no feedback is received by the end of public review, the construct may be deprecated for the Publication). The Publication change file shall include all deprecation candidates and deprecated constructs. Rationale: This will provide a consistent and well-published mechanism by which content can be removed from the OTA specification. Also, existing implementations of the OTA specification will be made aware of content marked for deprecation.

4.11.7

License Agreement Documentation

Guideline: All OTA Schema files include a distinct message level annotation that references the OTA License Agreement (http://www.opentravel.org/ota_downloads_form.cfm). Rationale: With the 2004A publication, all OTA Schema files are accessible directly from the OTA public site without having to download a .zip file. Each Schema file is associated with a uniquely resolvable URL. For instance, the OTA_SimpleTypes.xsd file is accessible at: www.opentravel.org/OTA_SimpleTypes.xsd. Providing a reference to the License Agreement in ALL OTA Schema files will ensure that users of the specification are aware of the stipulations by which it is made publicly available. Example: The following example shows the header of the OTA_CommonTypes.xsd file with the License Agreement reference included in the documentation. All Schema files in the OTA specification are made available according to the terms defined by the OTA License Agreement at http://www.opentravel.org/ota_downloads_form.cfm ...

© 2005 OpenTravel™ Alliance

www.opentravel.org/