5 XML Standards and Conventions

This chapter defines standards in the areas of naming conventions, XML standards, and customization/extension.

The standards in this document are for the artifacts used in Oracle Retail integration products, such as the RIB, Integration Gateway Services and Web Service Providers created by the Retail SOA Enabler tool. For Oracle AIA this section applies to edge-application Web services and integration patterns. These standards do not overlap the AIA standards for middle layer integrations. For those integrations, the AIA standards are directly applicable.

The standards and conventions described in this section are retail domain specific. The naming conventions and standards are only patterned after AIA concepts.

XML Standards and Conventions

This section describes XML standards and conventions.

The underscore (_) must be used for readability in naming simple elements

This standard is a significant deviation from generally accepted WS standards, including AIA. The underscore is used by the Business Objects in the RIB and by Oracle Retail PL/SQL applications.

Topic	Description
Recommendation	The underscore must be used for readability in naming simple elements, with no spaces or hyphens between words; lower camel case cannot be used (for example, supplierName). Lower case must be used. The simple element names must not be more than 30 characters in length.
Rationale	This is not the generally accepted recommendation in other XML standards. Because Business Objects are translated into Oracle Objects for use within the database by PL/SQL APIs, all elements are made uppercase by default. Readability is enhanced by using the underscore instead of the industry standard lower camel case.
Example	<xsd:element name="supplier_name" type="varchar2240"/>

Names must not contain special characters

Topic	Description
Recommendation	Names must not contain special characters.
Rationale	This is recommended to be similar to other XML standards. Note that the underscore is allowed. This is not the same as other standards.
Examples	space, '-', '.', '$', '%', '#',<, >, &, ?

UpperCamel case must be used for naming complex types

Topic	Description
Recommendation	Upper camel case must be used for naming complex types with no spaces, hyphens or underscores between words. The complex type elements must not be more than 22 characters in length.
Rationale	This is recommended to be similar to other XML standards..
Example	<xsd:complexType name="SupplierType"/>

Avoid XML schema keywords as element names

Topic	Description
Recommendation	Avoid XML schema keywords as element names. Do not use XSD keywords, such as element, sequence, and complexType as element names.
Rationale	This is recommended to be similar to other XML standards.
Example	<xs:element name="element" type="xs:integer"/>

Avoid Java keywords

Topic	Description
Recommendation	Avoid Java keywords as element names.
Rationale	This is recommended to be similar to other XML standards.
Examples	abstract, assert, boolean, break, byte, case, catch, char, class, const, continue, default, do, double, else, enum, extends, false, final, finally, float, for, goto, if, implements, import, instanceof, int, interface, long, native, new, null, package, private, protected, public, return, short, static, strictfp, super, switch, synchronized, this, throw, throws, transient, true, try, void, volatile, while.

Avoid PLSQL keywords

Topic	Description
Recommendation	Avoid PLSQL keywords as element names.
Rationale	This is recommended to be similar to other XML standards.
Example	comment,clob

Avoid having numeric characters in the name

Topic	Description
Recommendation	Avoid having numeric characters in the name.
Rationale	This is recommended to be similar to other XML standards.
Example	<xsd:element name="supplier1Name" type="varchar2240"/>

All XSD elements should be annotated

Topic	Description
Recommendation	The definitions of all elements/attributes/enumerations should be included in the schema as notations. Each XSD file should declare as a namespace: xmlns:retailDoc="http://www.w3.org/2001/XMLSchema
Rationale	This is recommended to be similar to other XML standards. The XSD should be the source of truth and include the business functional documentation of the element. The annotation standard should be independent of any repository specific requirements. The retailDoc namespace will allow intelligent processing in the XML/XSD parser in the future. There can be different behavior for a documentation element when the prefix is retailDoc versus anything else (including xs: or xsd:), even though all of them belong to same namespace.
Example	xmlns:retailDoc="http://www.w3.org/2001/XMLSchema" <xs:element name="unit_qty" type="number12_4"> <retailDoc:annotation> <retailDoc:documentation>Contains the number of items expected to be received based on the supplier's ASN for this Item/Shipment combination.</retailDoc:documentation> </retailDoc:annotation> </xs:element>

Topic

Description

Recommendation

The definitions of all elements/attributes/enumerations should be included in the schema as notations.

Each XSD file should declare as a namespace:

xmlns:retailDoc="http://www.w3.org/2001/XMLSchema

Rationale

This is recommended to be similar to other XML standards.

The XSD should be the source of truth and include the business functional documentation of the element.

The annotation standard should be independent of any repository specific requirements.

The retailDoc namespace will allow intelligent processing in the XML/XSD parser in the future. There can be different behavior for a documentation element when the prefix is retailDoc versus anything else (including xs: or xsd:), even though all of them belong to same namespace.

Example

xmlns:retailDoc="http://www.w3.org/2001/XMLSchema"
                <xs:element name="unit_qty" type="number12_4">
                    <retailDoc:annotation>
                        <retailDoc:documentation>Contains the number of items expected to be received based on the supplier's ASN for this Item/Shipment combination.</retailDoc:documentation>
                    </retailDoc:annotation>
                </xs:element>

All XSDs should use the date type, xsd:dateTime, and the XML format, 2002-05-30T09:00:00

Topic	Description
Recommendation	All XSDs should use the date type, xsd:dateTime, and the XML format, 2002-05-30T09:00:00
Rationale	This is recommended to be similar to other XML standards.
Example	<xs:element name="ship_date" type="xs:dateTime">

Retail Business Objects Schema

The logical representation of an Oracle Retail business entity is known as the Oracle Retail Business Object. For the purposes of this document, it describes the definition of that object in the form of an XML Schema (XSD). The schema represents the common object definition for business concepts such as Account, Supplier, Purchase Order, and Item.

Business Object (XSD) names should not contain names

Topic	Description
Recommendation	The Business Object name should not contain message related operations or actions, such as Request or Response.
Rationale	The name should be only a business noun and should not necessarily reference the usage of the object.
Example	Do not use Business Object names like ItemRequest.xsd or ItemResponse.xsd.

Business Object (XSD) names should not contain CRUD operations

Topic	Description
Recommendation	The Business Object name should not contain message related operations or actions, such as Create, Update, Process, and Get.
Rationale	The name should be only a business noun and should not necessarily reference the usage of the object CRUD operations.
Example	Do not use Business Object names like ItemCreate.xsd or ItemMod.xsd.

The Business Object (XSD) file must match the name of the top level element

Topic	Description
Recommendation	Every XSD file must define only one top level/global element, and the file name must match the name of the top level element.
Rationale	This is recommended to be similar to other XML standards.
Example	SupplierBO.xsd <xs:element name="SupplierBO"> <retailDoc:annotation> <retailDoc:documentation></retailDoc:documentation> </retailDoc:annotation> <xs:complexType>

Each Business Object (XSD) must have its own namespace

Topic	Description
Recommendation	Each Business Object must have its own namespace.
Rationale	This is to eliminate conflicts when a service consumer will consume multiple from the same provider and the generate client side code should not have conflict. Each BO having its own namespace also allows versioning of each BO. The file will be located in a directory structure that matches the path portion of the namespace URLs for the top level type that is defined in that file.
Example	targetNamespace="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1"

Topic

Description

Recommendation

Each Business Object must have its own namespace.

Rationale

This is to eliminate conflicts when a service consumer will consume multiple from the same provider and the generate client side code should not have conflict.

Each BO having its own namespace also allows versioning of each BO.

The file will be located in a directory structure that matches the path portion of the namespace URLs for the top level type that is defined in that file.

Example

targetNamespace="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1"
version="1.0"
xmlns="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1"

Each Business Object (XSD) namespace should not contain application identifiers

Topic	Description
Recommendation	Each Business Object namespace should not contain application identifiers.
Rationale	Business Objects are not tied to any specific retail applications. These are generic business objects that belong to the full retail domain. So the Business Object namespace should not contain application identifiers.
Example	targetNamespace="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1" version="1.0" xmlns="http://www.oracle.com/retail/integration/base/bo/SupplierBO/v1"

Each Business Object (XSD) root should be annotated

Topic	Description
Recommendation	The XSD should be the source of truth and include the business functional documentation of the element.
Rationale	This is recommended to be similar to other XML standards. The annotation standard is independent of any repository specific requirements for the Business Objects.
Example	<xs:element name="SupplierBO"> < retailDoc:annotation> < retailDoc:documentation> Merchandise Suppliers are suppliers of goods and services to be sold by the retailer to customers </ retailDoc:documentation> </ retailDoc:annotation>

Avoid Business Object (XSD) to have maxOccurs="unbounded" for elements

Topic	Description
Recommendation	Avoid maxOccurs="unbounded" unless it is absolutely required.
Rationale	Setting a maxOccurs value to unbounded can lead to resources exhaustion and ultimately a denial of service. Processing XML documents can be expensive. Attackers can take advantage of the schemas that allow unbounded elements by supplying an application with a very large number elements causing the application to exhaust system resources.
Example	The following is an example of a schema that allows unbounded bar elements.<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > <xs:element name="foo" > <xs:complexType> <xs:sequence> <xs:element name="bar" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element></xs:schema>