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.
This section describes XML standards and conventions.
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"/> |
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, '-', '.', '$', '%', '#',<, >, &, ? |
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"/> |
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"/> |
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. |
Topic | Description |
---|---|
Recommendation | Avoid PLSQL keywords as element names. |
Rationale | This is recommended to be similar to other XML standards. |
Example |
comment,clob |
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"/> |
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 | 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"> |
date: dateTime
boolean: boolean
text: varchar2N
integer: number6
decimal: numberN_N
long: number10
example:
varchar24
number12_4
Topic | Description |
---|---|
Recommendation | Non top level CompleType cannot be empty, that is in xml we cannot have something like
<ExtOfReportLocDesc></ExtOfReportLocDesc> or <ExtOfReportLocDesc/>. So validation error is correct. |
Rationale | This is recommended to be similar to other XML standards. |
Example |
<ExtOfReportLocDesc></ExtOfReportLocDesc> |
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.
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. |
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. |
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> |
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 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" |
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> |
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> |