UBL Naming and Design Rules Version 3.0

COM06 Minimum set of dictionary information values describing an ABIE

Each ABIE shall have the following set of dictionary information values: Component Type (mandatory) shall be the value "ABIE" Definition (mandatory) this value shall describe the ABIE using complete natural language sentences in a single paragraph Alternative Business Terms (optional) this value shall list any other commonly used terms that are synonyms for the ABIE Object Class Qualifier (optional) this value shall qualify the object class for a specific context Object Class (mandatory) this value shall identify the object of interest within an information bundle; it is the class to which the ABIE's BIEs belong Name (mandatory) this value shall be the concatenation of Object Class Qualifier and the Object Class without any spaces, abbreviating the values as required Example (using an XPath expression) Given the following: $OCQ = Object Class Qualifier $OC = Object Class C:ABBREV(arg) = custom function to return the abbreviation of an argument, or the argument itself if no abbreviation, and all spaces removed concat( C:ABBREV($OCQ), C:ABBREV($OC) ) Dictionary Entry Name (mandatory) this value shall be the concatenation of the Object Class Qualifier, followed by an underscore and space when defined, followed by the Object Class, followed by a period and space, followed by the word "Details" Example (using an XPath expression) Given the following: $OCQ = Object Class Qualifier $OC = Object Class concat( if( $OCQ ) then concat($OCQ,'_ ') else '', $OC, '. Details' ) Example ABIE Fixed value: Component Type="ABIE" Entered values: Definition="A class to define common information related to an address." Object Class="Address" Derived values: Name="Address" Dictionary Entry Name="Address. Details"

COM07 Minimum set of dictionary information values describing a BBIE

Each BBIE shall have the following set of dictionary information values: Component Type (mandatory) shall be the value "BBIE" Cardinality (mandatory) shall be one of: "1" (required and not repeatable), "0..1" (optional and not repeatable), "0..n" (optional and repeatable) or "1..n" (required and repeatable) Definition (mandatory) this value shall describe the BBIE using complete natural language sentences in a single paragraph Alternative Business Terms (optional) this value shall list any other commonly used terms that are synonyms for the ABIE Object Class Qualifier (optional) this value shall qualify the object class for a specific context Object Class (mandatory) this value shall identify the object class of the ABIE to which the BBIE belongs Property Term Qualifier (optional) this value shall qualify the property term for a specific context Property Term Possessive Noun (optional) this value shall identify a distinguishing nature of the characteristic of the object class Property Term Primary Noun (mandatory) this value shall identify the principle nature of the characteristic of the object class Property Term (mandatory) this value shall identify a characteristic of the object class as the concatenation of Property Term Possessive Noun followed by a space should it exist, followed by the Property Term Primary Noun Example (using an XPath expression) Given the following: $PTPsN = Property Term Possessive Noun $PTPrN = Property Term Primary Noun concat( $PTPSN, if( $PTPSN ) then ' ' else '', $PTPRN ) Representation Term (mandatory) this value shall identify the form of the value domain and shall be selected from the set of primary and secondary representation terms specified in CCTS Table 8.3 Permissible Representation Terms (ordered by primary term with secondary terms in parentheses): Amount Binary Object (Graphic, Picture, Sound, Video) Code Date Time (Date, Time) Identifier Indicator Measure Numeric (Value, Rate, Percent) Quantity Text (Name) Name (mandatory) this value shall be the concatenation of Property Term Qualifier, Property Term Possessive Noun and, when the Property Term Primary Noun is not "Text" or it is "Text" and both the Property Term Qualifier and the Property Term Possessive Noun are not defined, then the Property Term Primary Noun (abbreviating it as required) and, when the Representation Term is not "Text" and the Property Term Primary Noun is not equivalent to the Representation Term, then also the Representation Term component (abbreviating it as required), all without intervening spaces Example (using an XPath expression) Given the following: $PTQ = Property Term Qualifier $PTPsN = Property Term Possessive Noun $PTPrN = Property Term Primary Noun $RT = Representation Term C:ABBREV(arg) = custom function to return the abbreviation of an argument, or the argument itself if no abbreviation, and all spaces removed, or the argument itself if no abbreviation, and all spaces removed C:EQUIVALENT(noun,term) = custom function to return TRUE/FALSE if the primary noun and representation term are to be considered equivalent concat( C:ABBREV($PTQ), C:ABBREV($PTPSN), if( $PTPRN!='Text' OR ( not($PTQ) AND not($PTPSN) ) ) then C:ABBREV($PTPRN) else '', if( $RT!='Text' AND not(C:EQUIVALENT($PTPRN,$RT))) then C:ABBREV($RT) else '' ) Dictionary Entry Name (mandatory) this value shall be the concatenation of the Object Class Qualifier, followed by an underscore and space when defined, followed by the Object Class, followed by a period and space, followed by the Property Term Qualifier, followed by an underscore and space when defined, followed by the Property Term, and then, when either the Property Term Qualifier is defined or the Property Term is not equal to the Representation Term, followed by a period and space and the Representation Term Example (using an XPath expression) Given the following: $OCQ = Object Class Qualifier $OC = Object Class $PTQ = Property Term Qualifier $PT = Property Term $RT = Representation Term concat( $OCQ, if( $OCQ ) then '_ ' else '',$OC,'. ', $PTQ, if( $PTQ ) then '_ ' else '',$PT, if( $PTQ OR ( $PT != $RT ) ) then concat( '. ',$RT) else '' ) Data Type Qualifier (optional) this value shall distinguish particular restrictions on a data type from the use of a data type with other (or no) restrictions Data Type (mandatory) this value shall be the concatenation of the Data Type Qualifier followed by an underscore and space when it exists, the Representation Term, followed by a period and space, followed by the word "Type" Example (using an XPath expression) Given the following: $DTQ = Data Type Qualifier $RT = Representation Term concat( $DTQ, if( $DTQ ) then '_ ' else '', $RT, '. Type' ) Example BBIE Fixed value: Component Type="BBIE" Entered values: Cardinality="0..1" Definition="An additional street name used to further clarify the address." Object Class="Address" Property Term Qualifier="Additional" Property Term Possessive Noun="Street" Property Term Primary Noun="Name" Representation Term="Name" Derived values: Name="AdditionalStreetName" Dictionary Entry Name="Address. Additional_ Street Name. Name" Property Term="Street Name" Data Type="Name. Type"

COM08 Minimum set of dictionary information values describing an ASBIE

Each ASBIE shall have the following set of dictionary information values: Component Type (mandatory) shall be the value "ASBIE" Cardinality (mandatory) shall be one of: "1" (required and not repeatable), "0..1" (optional and not repeatable), "0..n" (optional and repeatable) or "1..n" (required and repeatable) Definition (mandatory) this value shall describe the BBIE using complete natural language sentences in a single paragraph Alternative Business Terms (optional) this value shall list any other commonly used terms that are synonyms for the ABIE Object Class Qualifier (optional) this value shall qualify the object class for a specific context Object Class (mandatory) this value shall identify the object class of the ABIE to which the BBIE belongs Associated Object Class Qualifier (optional) this value shall qualify the object class of the associated ABIE for a specific context Associated Object Class (mandatory) this value shall identify the object class of the ABIE the ASBIE associates to the ABIE must exist in the model with the same qualification (or lack thereof) as the ASBIE's associated object class qualifier Property Term Qualifier (optional) this value shall qualify the property term for a specific context Property Term (mandatory) this value shall be the concatenation of the Associated Object Class Qualifier, an underscore and a space when defined, and the Associated Object Class Example (using an XPath expression) Given the following: $AOCQ = Associated Object Class Qualifier $AOC = Associated Object Class concat( $AOCQ, if( $AOCQ ) then '_ ' else '', $AOC ) Representation Term (mandatory) this value shall be the same as the Property Term Name (mandatory) this value shall be the concatenation of Property Term Qualifier and the Property Term without any spaces or underscore, abbreviating the values as required Example (using an XPath expression) Given the following: $PTQ = Property Term Qualifier $PT = Property Term C:ABBREV(arg) = custom function to return the abbreviation of an argument, or the argument itself if no abbreviation, and all spaces removed, or the argument itself if no abbreviation, and all spaces removed concat( C:ABBREV($PTQ), C:ABBREV($PT) ) Dictionary Entry Name (mandatory) this value shall be the concatenation of the Object Class Qualifier, followed by an underscore and space when defined, followed by the Object Class, followed by a period and space, followed by the Property Term Qualifier, followed by and underscore and space when defined, followed by the Property Term, and then when the Property Term Qualifier is defined, followed by a period and space and the Representation Term Example (using an XPath expression) Given the following: $OCQ = Object Class Qualifier $OC = Object Class $PTQ = Property Term Qualifier $PT = Property Term $RT = Representation Term concat( $OCQ, if( $OCQ ) then '_ ' else '', $OC, '. ', $PTQ, if( $PTQ ) then '_ ' else '', $PT, if( $PTQ ) then concat('. ',$RT) else '' ) Example ASBIE Fixed value: Component Type="ASBIE" Entered values: Cardinality="0..1" Definition="The buyer of the item." Object Class="Forecast" Associated Object Class="Customer Party" Property Term Qualifier="Buyer" Derived values: Name="BuyerCustomerParty" Dictionary Entry Name="Forecast. Buyer_ Customer Party. Customer Party" Property Term="CustomerParty" Representation Term="CustomerParty"

COM09 Dictionary entry name uniqueness
All dictionary entry names in a semantic model shall be unique. Note The rationale is that a BIE describes a unique semantic component of business data within a specific business context.

COM10 CCTS dictionary information item name value prohibited characters

All information items contributing to a component's dictionary entry name shall be void of all sensitive dictionary entry name markup characters. The following characters must not be used in any dictionary information values that contribute to the dictionary entry name: the characters "." (period) and "_" (underscore) leading, trailing or multiple sequential " " (space) characters Note The rationale is that prohibiting these characters in name values prevents ambiguity when assembled into the dictionary entry name using these characters to provide structure.

COM11 Use of the singular form in names
All information items contributing to a component's dictionary entry name shall be in the singular form unless the concept itself is plural. Example "Payment Terms" is the noun used for the collection of a plurality of various aspects of payment and has a cardinality of only "0..1". Note The rationale is that the cardinality of an item named in the singular confers the plurality of the item.

COM12 Use of leading upper case letter in dictionary entry name values
All words that are not abbreviated in name values contributing to the dictionary entry name shall have a leading upper-case letter and all other letters in lower-case.

FRG01 Document ABIE schema fragments
There shall be one schema fragment created for each Document ABIE.

FRG02 Document ABIE element declaration
Each Document ABIE schema fragment shall include a single element declaration, that being for the Document ABIE.

FRG03 Document ABIE type declaration
Each Document ABIE schema fragment shall include a single type declaration, that being for the content of the Document ABIE.

FRG04 Library ABIE schema fragment
There shall be one common schema fragment created to contain all ASBIEs (that is, from every Document ABIE and every Library ABIE) and all Library ABIEs. Example In UBL 2.1 the UBL-CommonAggregateComponents-2.1.xsd fragment serves this purpose.

FRG05 Library ABIE element declarations
The common Library ABIE schema fragment shall include an element declaration for every ASBIE in the model (that is, from every Document ABIE and every Library ABIE) and for every Library ABIE.

FRG06 Library ABIE type declarations
The common Library ABIE schema fragment shall include a type declaration for every Library ABIE, each being for the content of each Library ABIE.

FRG07 BBIE schema fragment
There shall be one common schema fragment created to describe all BBIEs in the model (that is, from every Document ABIE and every Library ABIE). Example In UBL 2.1 the UBL-CommonBasicComponents-2.1.xsd fragment serves this purpose.

FRG08 BBIE element declarations
The common BBIE schema fragment shall include an element declaration for every BBIE in the model (that is, from every Document ABIE and every Library ABIE) describing the content of each BBIE.

FRG09 Library ABIE type declarations
The one BBIE schema fragment shall include a type declaration for every BBIE in the model (that is, from every Document ABIE and every Library ABIE), each being for the content of each BBIE.

DCL01 Element declarations
Every BIE element declaration shall be global.

DCL02 Element declaration references
Every BIE element in an ABIE type definition shall be declared by reference.

DCL03 Type declarations
Every BIE type declaration shall be global.

DCL04 ABIE element declaration
Every ABIE element shall be declared with the ABIE name as the element name and the ABIE name suffixed with "Type" as the type. Example <xsd:element name="ApplicationResponse" type="ApplicationResponseType"/>

DCL05 ABIE type declaration
Every ABIE complex type name shall be declared with the name of the ABIE suffixed with "Type" as the name. Example <xsd:complexType name="ApplicationResponseType"> (... contents ...} </xsd:complexType>

DCL06 Library ABIE type declaration content order

The members of a Library ABIE shall be ordered as the sequence (in the order the BIEs appear in the semantic model of the ABIE) of all BBIE element references first, followed by all ASBIE references. Example <xsd:complexType name="CatalogueRequestLineType"> <xsd:sequence> <xsd:element ref="cbc:ID" minOccurs="1" maxOccurs="1"/> <xsd:element ref="cbc:ContractSubdivision" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:Note" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="cac:LineValidityPeriod" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cac:RequiredItemLocationQuantity" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="cac:Item" minOccurs="1" maxOccurs="1"/> </xsd:sequence> </xsd:complexType>

DCL07 Document ABIE type declaration content order

The members of a Document ABIE shall be ordered first with a reference to the extension collection element, followed by the sequence (in the order the BIEs appear in the semantic model of the ABIE) of all BBIE element references first, followed by all ASBIE references. Example <xsd:complexType name="ApplicationResponseType"> <xsd:sequence> <xsd:element ref="ext:UBLExtensions" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:UBLVersionID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:CustomizationID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:ProfileID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:ProfileExecutionID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:ID" minOccurs="1" maxOccurs="1"/> <xsd:element ref="cbc:UUID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:IssueDate" minOccurs="1" maxOccurs="1"/> <xsd:element ref="cbc:IssueTime" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:ResponseDate" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:ResponseTime" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:Note" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="cbc:VersionID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cac:Signature" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="cac:SenderParty" minOccurs="1" maxOccurs="1"/> <xsd:element ref="cac:ReceiverParty" minOccurs="1" maxOccurs="1"/> <xsd:element ref="cac:DocumentResponse" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> Note The rationale for positioning extension information at the very start of the XML instance is to allow processing applications acting sequentially on the document to consume and cache all non-modeled extension information in preparation for consuming any of the modeled document information. Should extension information follow modeled information, the sequential processing of the modeled information would have passed before recognizing the need to associate extension information. In essence, such a sequential processing application would have to cache the entire document, thus losing the benefit of sequential processing.

DCL08 Document ABIE extension element cardinality
In the content type for every Document ABIE the extension collection element cardinality shall be declared as optional and not repeatable. Example <xsd:element ref="ext:UBLExtensions" minOccurs="0" maxOccurs="1"/>

DCL09 ASBIE schema element declaration
Every ASBIE element shall be declared with the ASBIE name as the element name and the ABIE name of the associated object class suffixed with "Type" as the type. Example <xsd:element name="Party" type="PartyType"/> Example <xsd:element name="AgentParty" type="PartyType"/>

DCL10 BBIE element declaration
Every BBIE element shall be declared with the BBIE name as the element name and the concatenation of the BBIE name and "Type" as the type. Example <xsd:element name="SourceCurrencyCode" type="SourceCurrencyCodeType"/>

DCL11 BBIE type declaration
Every BBIE element type shall be declared as simple content extended from a base of either a qualified data type or an unqualified data type without the addition of any additional attributes. Example <xsd:complexType name="SourceCurrencyCodeType"> <xsd:simpleContent> <xsd:extension base="udt:CodeType"/> </xsd:simpleContent> </xsd:complexType>

EXT01 Extension collection schema fragment

The extension collection schema fragment shall include the declarations of the extension collection element, the extension element, the extension content element, the extension metadata elements and any required type information for metadata elements that are not BIEs in the Document ABIEs and Library ABIEs. Example In UBL 2.1 the UBL-CommonExtensionComponents-2.1.xsd fragment serves this purpose.

EXT02 Extension content element declaration

The extension collection schema fragment shall include the declaration of the mandatory extension content element, but not the type information for the extension content element. Note The rationale for not including the type information for the extension point element is that the type is subject to change, while the extension collection, the extension item and extension item metadata element and type information is not. This separation allows the extension collection and item schema fragment to be deployed as read-only, while the extension point data type schema fragment can be deployed as writable in order to be defined by users.

EXT03 Extension collection element content

The document's extension collection shall have one or more extension elements as its content. Example <xsd:complexType name="UBLExtensionsType"> <xsd:sequence> <xsd:element ref="UBLExtension" minOccurs="1" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> Note The rationale is that different users of a document may have different extension items added to the content. Also, different extensions may be thematically distinguished (e.g. the digital signature extension is semantically separate from an extension augmenting invoice line content).

EXT04 Extension element content ordering

The extension element shall declare all available metadata elements (if any) in advance of a last mandatory single extension content element being the extension point under which the extension information is added to the document. Example <xsd:complexType name="UBLExtensionType"> <xsd:sequence> <xsd:element ref="cbc:ID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="cbc:Name" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionAgencyID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionAgencyName" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionVersionID" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionAgencyURI" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionURI" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionReasonCode" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionReason" minOccurs="0" maxOccurs="1"/> <xsd:element ref="ExtensionContent" minOccurs="1" maxOccurs="1"/> </xsd:sequence> </xsd:complexType> Note There are no constraints on the selection, name, definition or cardinality of the extension metadata elements.

EXT05 Extension content data type schema fragment
The extension content element type schema fragment shall include the declaration of the content type for the extension content element and any import statements defining constraints on recognized constructs. Example In UBL 2.1 the UBL-ExtensionContentDataType-2.1.xsd fragment serves this purpose.

EXT06 Extension content data type declaration

The extension content element type schema fragment shall contain only a single complex type declaration being a sequence of exactly one element in a namespace other than the extension namespace to be processed with lax validation. Example <xsd:complexType name="ExtensionContentType"> <xsd:sequence> <xsd:any namespace="##other" processContents="lax" minOccurs="1" maxOccurs="1"/> </xsd:sequence> </xsd:complexType> Note The rationale for the lax validation is to allow for the extension point to contain, without error, any element for which there are no constraints in any schema fragment imported or included in the validation step.

EXT07 Extension content data type imports

The extension content element type schema fragment may contain import directives for the expected data content of an extension. Example <xsd:import namespace="urn:oasis:names:specification: ubl:schema:xsd:CommonSignatureComponents-2" schemaLocation="UBL-CommonSignatureComponents-2.1.xsd"/> Note The rationale for including import directives is to validate those constructs found in an extension that are expected. Note There is no order to the import directives.