xCBL Style Guide

last updated on:	
07/11/02

Version 1.0
Introduction
Audience
Resources
xCBL and SOX Basics
xCBL Building Blocks
xCBL Building Block Types
xCBL Code Lists
xCBL Basic Components
xCBL Data Types
xCBL Component Types
xCBL Aggregate Components
xCBL Aggregate Structures
Using the xCBL Building Blocks
Reusing New Elementtypes
SOX Basics
Datatypes
Extensions
Designing the Document
Sections of a Document
Header
Detail
Summary
Grouping
Cardinality
Using Special Types of Elements
Attributes
Booleans
Choices
Code Lists
Custom Datatypes
Lists
Other Considerations
Namespaces
File Names
Anticipate Expansion and Use By Others
Symmetry of Responses
Documentation
Documenting Elements
Documentation Tags
Final Notes

Introduction

The xCBL Style Guide is a resource for individuals or companies looking to create new xCBL documents. This specification details style guidelines that are to be considered and followed when creating a new document for xCBL. The guide includes a look at the basics of creating an xCBL document, the document design considerations, other helpful points to consider about a document, and rules about the accompanying documentation required for an xCBL document.  This guide does not provide a step-by-step process for creating a new document, but rather provides the reader a resource of information containing general guidelines and useful tips to ensure that the xCBL document they create will undergo as little rework as possible when reviewed by the xCBL team.  A document of this scope could not encompass every possible aspect of creating a document, nor will it attempt to.  Rather, this document will highlight the key points for consideration when creating a document.  The best asset to have when creating a new document is a strong familiarity with the existing library, and the methods used within it.

Audience

This document was written based on the assumption that the reader is familiar with xCBL and SOX.  Familiarity is defined by having reviewed the xCBL website, have basic understanding of the components that make up current xCBL documents, read the SOX Tutorial, and has followed the xCBL Development Resources Process to determine that a new xCBL document is required.  The Resources section below outlines documents that are to be reviewed in conjunction with the style guide.  

Resources 

1.  www.xcbl.org	
2.  xCBL Document Creation Methodolgy.doc 
1.	3.  SOX Tutorial  

xCBL and SOX Basics
The following section describes the fundamental concepts the user is expected to be familiar with in regards to the current version of xCBL as well as what functionality is available in SOX.  These basic concepts are absolutely necessary to understand in order to fully utilize the existing xCBL as well as what SOX has to offer.  

xCBL Building Blocks

It is important to reuse existing structures from xCBL documents in order to minimize the size of the library, and to ensure consistency across documents as well as business processes.  To help with this, there are several xCBL components that, as defined, serve as building blocks for other xCBL components and business messages (documents). These building blocks have been defined so that they can be used and re-used across several different business areas.  Whenever possible, users are to use these elements when creating new documents.  Furthermore, whenever possible the highest aggregate element should be used reviewed to see if there are usable structures before using the components inside these structures.  The only acceptable case for not using an existing element is when a mandatory field within that element does not apply to the needs of the document being created, and can not be logically defaulted. 

xCBL Building Block Types
These elements can be found in the xCBL Structured Reference, however the section below provides a summary of the different type of building blocks available, followed by a brief explanation of how to use them

xCBL Code Lists
This category consists of enumerated datatypes that are of a general use across several business messages.  Typically these code lists are based on EDI codes, but do allow for non-standard codes with the use of the coded value ‘Other’.

xCBL Basic Components
This category is the lowest level of xCBL building blocks. These elementtypes are made up of usually one or two elements, or a single element and attributes that communicate a single piece of information. For instance, the elmenttype Purpose contains the elements PurposeCoded and PurposeCodedOther. Its child elements only describe a purpose, thus making it a xCBL Basic Component. Furthermore, any sub element, which is of an intrinsic datatype, contained within any other building block is assumed to be an xCBL Basic Component.  For instance, the xCBL Aggregate Structure, NameAddress, contains the child element Name1, which is of the intrinsic datatype, string.  Therefore the element Name1 is considered an xCBL Basic Component.

xCBL Data Types 
This category includes elements that extend or restrict intrinsic data types. These data types are commonly used to limit lengths of strings, and restrict the precision of numbers.  AlphaNum80 and Decimal8_2 are examples of this category.

xCBL Component Types
This category defines basic common business entities that communicate a single piece of data by combining one or more elements essential to the data and other elements, which add further meaning to the data. This category can contain other xCBL Component Types, xCBL Data Types, xCBL Basic Components, or xCBL Code Lists. An example of this is the Measurement elementtype. This elementtype contains either a range or value of the measurement and a unit measurement. Furthermore, the range or the value can be further qualified by significance or conditions. Since the whole elementtype is simply communicating a basic piece of data (i.e. a physical measurement), and all of the sub elements only pertain directly to the value of the measurement, this elmenttype is classified as an xCBL Component Type.

xCBL Aggregate Components
This category can include any of xCBL Basic Components, xCBL Component Types, xCBL Code Lists, or xCBL Data Types.  xCBL Aggregate Components represent xCBL building blocks that have broader definitions than xCBL Component Types and xCBL Basic Components. For example, while the xCBL Component Type UnitPrice simply defines a price per unit, the xCBL Aggregate Component Price defines other information relating to an entire pricing scheme.

xCBL Aggregate Structures
This category can consist of one or more xCBL Aggregate Components, xCBL Basic Components, xCBL Data Types, xCBL Code Lists or other xCBL Aggregate Structures. xCBL Aggregate Structures represent the highest level of xCBL Building Block.  For example, ItemDetail is an xCBL Aggregate Structure. It is made up of xCBL Basic Components as well as other xCBL Aggregate Structures. It defines basic information, pricing information, and delivery information for an item, and is central to most procurement documents.

Using the xCBL Building Blocks
When using the xCBL Building Blocks, it is important to review the list of existing elements and their classifications as building blocks (if any).  The user should also be familiar with any similar existing documents, or other existing documents in the same business process realm of the document they are creating.  This will allow the user to be more aware of what structures are already available.  When reusing existing elements, it is important the highest possible building block be used.  For instance, if an xCBL Aggregate Component seems to fit the need for a document, ensure that it is not part of a xCBL Aggregate Structure that may also fit.  That is to say, it is important to use an entire xCBL Aggregate Structure if possible, as opposed to picking apart the pieces of it.  Finally, when reusing an xCBL building block, it is important to locally name the elements, when further context is needed, so that they are used correctly.  For instance, if the Party element is being used, it is usually necessary for a local name to define the exact role of the party.

Reusing New Elementtypes

Many times it is necessary for someone creating a new document to create new elementtypes.  If this is the case, it is important that these new elementtypes be defined in such a way that they are reusable across any similar documents.  Reusing elements, whether existing in xCBL, or created for a new document, makes any new document easier to use for both you and anyone else that may find a need for it.

SOX Basics  
Although it is highly recommended that you be very familiar with the SOX Tutorial before creating a document, the following section will highlight some of the key functionality available in SOX that you should be aware of before creating a document.  This is not meant to serve as a substitution for reading the SOX Tutorial, rather to highlight a couple of points you should be familiar with.

Datatypes
SOX allows for some datatypes that are not allowed in XML.  It is important to use these datatypes whenever possible to ensure the content of a document can be processed.  For instance, if a field should be limited to a date, the date or datetime datatype should be used.  It is important not to create a document of merely strings, unless of course, that is what is necessary.  For instance, if a field should be numeric, use a number datatype.  If the number should be limited to some level of precision, then use an existing custom datatype, or create a new one.  For further information on intrinsic datatypes in SOX, read Appendix A of the SOX Tutorial.  For information on creating custom datatypes, read section 4.3 of the SOX Tutorial.

Extensions
Although SOX does allow for the extension of existing elements, it is recommended that this not be done.  A lot of software cannot handle extensions, therefore the use of them is somewhat unreliable.  Furthermore, because of the polymorphic properties of extended elements, undesired results often occur.  For instance, if you were to extend one of the xCBL Building Blocks to add some additional information for one particular document, then this new structure could technically be used anywhere the base element exists.  Therefore, it is recommended that if information is to be added to an existing elementtype, the existing elementtype and the information to be added be grouped together in a parent, or container elementtype.

Designing the Document

This section of the xCBL Style Guide will outline some key considerations in designing a new xCBL document.  The important thing to take away from this is that the ultimate goal is a level of consistency across documents and business processes in the library.  It should be emphasized again, that these are merely highlights of the most important points to consider when creating a document, and that it is strongly recommended that you be familiar with the existing library and the methods used before attempting to create a new document.

Sections of a Document

Like any well-formatted message, an xCBL document should be sectioned into useable pieces of information.  At the highest level for a business document, this usually means a header, detail, and summary section.  The following sections describe the recommended structure and typical information contained within each of these sections.

Header
The header section of a document should contain any metadata that pertains to the document, along with any information that should be applied to the rest of the message.  By metadata, it is meant information that identifies the document such as identification numbers, issue dates, the sender of the message, the recipient(s) of the message, and any other information that could potentially be used to uniquely identify the message.  Typical information that may apply to the entire message could be parties, dates, currencies, or language.  A good example of information that applies to an entire message is delivery and transport information for an order.  If all of the items are being shipped to the same place and being shipped by the same means of transport, it is best to specify this information in the header of the document, rather than repeat it for each individual item.  Information at the header level serves as the default dada for the entire document unless over written at the line item level.   

Detail
The detail section of a document should carry the bulk of the information.  For instance, in the Order document, the detail section contains the item and packaging information.  Whereas the header section is used to define which document is being sent, the detail section can be thought of as the document itself.  It is important to structure the detail section in a way that allows multiple instances where applicable.  For example, in an ASN there is a ListOfASNItemDetail.  This is to allow multiple line items in an ASN.  The “ListOf” construct is often used in the detail to allow for this use case.

Summary
The summary section of a document is used to hold totals, or similar information.  Usually this section will be optional, although in some cases, it may not be present at all.  Typical types of totals that are included in a summary are number of details (for instance line items), monetary amounts, and physical totals (such as weights). 

Grouping

Grouping of data becomes important as the size of documents grow.  In order to make documents easier to use, the information should be organized into usable groups.  Doing so allows a user of the document to ignore entire sections of a document they do not need.  For instance, in the ItemDetail element of the Order, all general line item information is grouped in BaseItemDetail, pricing information is grouped in PricingDetail, and all delivery information is grouped into DeliveryDetail.  Therefore, if someone using the Order does not utilize delivery information at the item level, they can totally ignore the DeliveryDetail section.  Using this sort of grouping also allows conditional mandatory elements.  For instance, in the Order, PaymentInstructions are optional.  However, if they are to be specified, a payment term code is required.

Cardinality

Perusing the xCBL library you probably noticed that the majority of elements are optional.  In fact in most documents only a handful of elements will be mandatory.  This design rule is to allow for documents to be used by a variety of trading partners.  When designing a proprietary document this rule becomes less important as the designer knows the intended users and the fields they require.  Documents created to be included in the xCBL library are written for future use by a variety of users that may not be known at design time.  Elements that are most often mandatory are those that describe the document and are needed for processing.  

•	Document identification
•	Document issue date
•	Line item numbers

Using Special Types of Elements

When creating a new document for xCBL, it important to use certain types of data correctly.  This section will outline some of the most commonly misused types of data, and the correct use of these.

Attributes
In general, attributes should be used sparingly.  The only time they should be used is when the information contained within the attribute is a property of the element or a default needs to be applied.  For instance, in the case of a measurement, the conditions in which the measurement was taken and the significance of the measurement are properties of that measurement.  Therefore, this information is contained in attributes of the measurement value.  In the case where a default is necessary, attributes can be used, but generally the aforementioned rule should still apply.

Booleans
The boolean datatype should be used only for elements where there are two and only two possible values.  Furthermore, the element should be named as such, that the acceptable values of either true or false are intuitive.   For instance, say an element calls for the color either red or blue.  Rather than call this element ‘Color’ and say true is equal to red and false is equal to blue, the element should be named ‘IsRed’.  In this case, a value of true is intuitively red, and a value of false is implied to be blue.

Choices
Choice elements can be used anywhere information is mutually exclusive.  For instance, if an item can either be ordered in terms of volume or weight, but not both, the weight and volume elements should be contained within a choice.  This method is preferred over making both elements optional.

Code Lists
Code lists, or enumerated datatypes, should be used anywhere that a finite set of expected values are possible.  However, unless the list is absolutely limited in its possible values, a value of ‘Other’ should be included in the code list and a field for a non-standard code should be included.  The values of the code list should be descriptive if possible, as opposed to being a numeric or alphanumeric code representation.  Finally, when naming a code list, the datatype should always end in ‘Code’, and when using the code list in an element, the element should always be named ‘Coded’.

Custom Datatypes
If it is necessary to limit the length of a field, or the precision of a number, a custom datatype can be created, if one does not already exist.  See section 4.3 of the SOX Tutorial for details of this.

Lists
Anytime multiple elements may exist, it is recommended that these be contained in a ListOf structure.  By list of structure, it is meant a structure that is made up of only one child element that can occur one to many times.  For instance, the ListOfReference elementtype contains one to many Reference elements.
 
Other Considerations

There are a few other points that should be considered when creating a document.  This section will highlight these considerations.

Namespaces

Currently, all documents in xCBL reside in a single namespace.  This being the case, it is important that when creating a new document, it is validated against the namespace.  In the case that an element in a newly created document conflicts with an existing element, the new element should be changed to the existing datatype, or should be renamed. 

File Names 

When creating a new document, it is important that the schema files be named and organized properly.  First, the actual document file should end in a .sox extension.  For instance, if one is creating a MyBusDoc document, the details of the MyBusDoc element only should be contained in the file MyBusDoc.sox.  All other elementtypes should be contained in files ending in a .mod extension.  Each elementtype should be contained within its own schema file, unless it will only be used in another elementtype, in which case it can reside in that elementtype schema file.  If you are using the Document Definition tool this is a non-issue.

Anticipate Expansion and Use By Others

When creating a new document, it is important to anticipate the use of it by others, and the need for expanding the information contained within it.  Some common practices to allow for such expansion is the use of qualified elements.  For instance, in an Order, parties such as buyer, seller, and ship to are named.  However, another user may see a need for other parties.  Thus, a ListOfPartyCoded elementtype is added.  This element is a list of party elements that are qualified with a role.

Symmetry of Responses

It is important to understand the relationship between Request and Response documents and how they are processed.  These documents will have a very similar structure; the location of data in the source will often be in the same place in the response.  Take for example the AvailabilityToPromise and AvailabilityToPromiseResponse documents.  The header of these documents is virtually identical with the exception of the PurposeCode.  This is done so that the data can be “streamed” when transformed and makes the creation of the response document much simpler.  This makes the data easy to capture and to map.  Problems can occur when data in the header of a request document is in the detail of a response.  This can result in the header level information being held in a variable and then having to be executed at the line level.  

Documentation 

If is important that all new documents are documented thoroughly.  Documenting the document ensures that it is used properly and consistently by anyone using it.  The following section will outline some of the key points to consider, ensuring that a newly created document is documented sufficiently.  
Documenting Elements

Each elementtype, element, datatype, and attribute must have a definition in the schema files.  When documenting an attribute, these usually follow the definitions for each child element.  Documenting code lists is equally as important as documenting elements.  If the code lists is based on an existing standard such as ISO or UNECE; the standard and the code list should be documented.  Finally, insufficient definitions (such as ‘Self explanatory’), or blank definitions are unacceptable.  

Documentation Tags

The documentation tags in the schema are <title>, <synopsis>, <bq>, and <h5> tags contained within the <explain> tags of an elementtype.  First, the <title> tag restates the elementtype being defined.   The  <synopsis> tag defines the elementtype in a global sense.  That is to say in its most generic form.  The <bq> and <h5> tags follow, and occur in pairs for each child element and attribute of the elementtype.  The <bq> tag states the name of the element or attribute being defined, and the <h5> tag defines the element or attribute.  These definitions are local, meaning they only apply to the context of the elementtype they are defining.

Final Notes

This document is a working document.  As technologies advance, this document will be amended.  Currently, this document is written based on building new xCBL documents using SOX.  In the near future the document will be updated to add style guidelines for building documents with XSDL.  The guidelines in this document are written in a generic format so that the updates to accommodate XSDL will be minimum.