[Accessibility conventions are described at the bottom of the page]
5. Documents and document models
[> 6.][< 4.1.6][^^^]
5.0 Document model formal expressions
[> 5.1][> 6.][< 5.][^^][^^^]
A UBL document is an XML instance that satisfies constraints chosen by the UBL TC
[[1] - structural and lexical constraints are described by a document model
[1] - value constraints are described through supplemental declarative files
[[2] - see [Chapter 8.] for overview
][1] - instance constraints are described in the specification
]
A document model is a syntax formalism
[[1] - for machine processing of the constraints of information model components in a physical expression of a sequence of characters
[1] - two different expressions of the document model based on the form of the documents
[[2] - determined by the kinds of networks across which the documents are transmitted
][1] - compact binary-encoded documents
[[2] - ASN.1 ISO 8825
][1] - marked-up text-based documents
[[2] - W3C Schema XSD
][1] - note that the XML constraints are normative while the ASN.1 constraints are not normative
]
The document model constrains the interchange of information, not the application data model
[[1] - a popular misconception in XML-based system design is to equate the document model with the application data model
[1] - XML provides independence between the two data models of the applications performing an interchange
[1] - an application translates information from its data model to and from the interchange model
]
One of two normative components of UBL is the W3C Schema XSD expression of XML document constraints
[[1] - formal expression of document constraints expressed for automated processing
[1] - two instantiations of the document constraints:
[[2] - one with comments
[[3] - spreadsheet model information copied for reference purposes
][2] - one without comments
[[3] - streamlined file may be processed more quickly by some applications
[3] - referenced as the "run time versions" of the schemas
]][1] - the other normative component is the definitions in the spreadsheets
[[2] - recall the discussion on [Library of shared and specific information items - Section 3.2.2 Library of shared and specific information items]
]]
The UBL TC has mandated additional normative instance-oriented constraints that go beyond the formal document model
[[1] - this promotes interoperability and blind interchange of XML documents
[1] - some of these constraints are difficult or impossible to be checked using XML-based tools
]
5.1 ASN.1 document models
[> 5.2][< 5.0][^^][^^^]
5.1.1 ASN.1 documents and document models
[> 5.2][> 6.][< 5.0][^^][^^^]
http://docs.oasis-open.org/ubl/os-UBL-2.0/asn/ directory
[[1] - ASN.1 expressions of document models
[[2] - ASN.1 specification of the content
[2] - ASN.1 schema
][1] - one module per document type
]
Abstract Syntax Notation number One
[[1] - internationally-standardized binary encoding of arbitrary stream of nested hierarchical information
[[2] - formalism for the specification of abstract data types
[2] - [http://asn1.elibel.tm.fr]
][1] - reduces bandwidth use to 20% or even 10% of original size
[1] - very broad use over wireless networks
]
Packed Encoding Rules (PER)
[[1] - well-defined lossless transformation from XML to PER to XML
[1] - compiler can create a C binding to XML through PER
]
The UBL ASN.1 document models are programmatically derived from the XML document models
5.2 XML documents and document models
[> 6.][< 5.1.1][^^][^^^]
5.2.1 XML documents
[> 5.2.2][> 6.][< 5.1.1][^^][^^^]
XML documents are constrained at a syntax level by the XML Recommendation
[[1] - [http://www.w3.org/TR/REC-xml]
[1] - well-formedness rules govern the use of markup characters
[1] - a document isn't considered XML unless it is well-formed
[1] - the Document Type Definition (DTD) specification in XML is not used for UBL
]
XML markup is used to label the document content
[[1] - a well-formed document describes a hierarchy of nested elements, attributes and text
[[2] - outer-most element containing all content is called the "document element"
[2] - all child elements properly nested within their parent
][1] - document annotation constructs can be embedded in content within certain rules
[[2] - comment annotations are for humans to read
[2] - processing instruction annotations are for programs to read
][1] - the tree's root contains the document element and any annotations before or after the document element as its children
[1] - namespaces are used for richly-defined labels of the information items
[[2] - [http://www.w3.org/TR/xml-names11]
[2] - provides disambiguation between two items that have the same "local name"
[2] - label names are a combination of a namespace URI and a simple local name
[[3] - a useful metaphor for a namespace is a dictionary
[[4] - the same word in two languages may represent different meanings as defined in that language's dictionary
[4] - the same XML local name in two namespaces may represent different meanings as defined in that namespace's semantics
]][2] - e.g. there are two UBL elements named Location that are distinguished by their respective namespaces
[2] - XML-based applications acting on UBL documents must be namespace aware to distinguish the use of constructs
]]
W3C Schema (XSD) Recommendation is used to express constraints on XML labels
[[1] - [http://www.w3.org/XML/Schema]
[1] - an XSD file can specify the labels for only a single namespace
[1] - XSD files include other XSD files to get label specifications for the same namespace
[1] - XSD files import other XSD files to get label specifications for other namespaces
]
5.2.2 UBL documents
[> 5.2.3][> 6.][< 5.2.1][^][^^][^^^]
A UBL document is an XML document expressing the final content of information transformed from an application's data model
[[1] - all calculations have already been performed according to some calculation model
[[2] - e.g. all tax determinations and calculations are complete
[2] - e.g. all line item extensions, subtotals and totals express the final values
]]
The committee has specified additional document constraints (Section [6.])
[[1] - validation
[[2] - a UBL document must validate against the corresponding set of document constraints expressed in the W3C Schema expression
published by the UBL committee
[2] - this confirms the use of the labels for information items in the document matches the constraints in the document model
][1] - character encoding
[[2] - <?xml version="1.0" encoding="UTF-8"?>
[2] - a UBL document must include a declaration of the character encoding in the XML declaration
[[3] - this overrides the XML Recommendation that indicates this is optional when the character encoding is UTF-8
][2] - the character encoding must be UTF-8
[[3] - this overrides the XML Recommendation that indicates any character encoding may be specified in the XML declaration
][2] - this constraint cannot be tested using an XML processor as using any properly-declared character encoding is syntactically
correct
][1] - empty and absent elements constrained
[[2] - a UBL element can never be empty or indicated as having a nil value
[[3] - the only exception is the ExtensionContent element due to processing restrictions that might remove content from unrecognized namespaces
][2] - the absence of a UBL element cannot convey meaning to an application
[2] - this constraint cannot be tested using an XML processor as empty elements are syntactically correct
[2] - e.g. CustomerParty
[[3] - has only optional elements but the rule that an element cannot be empty means that CustomerParty can only be used in an instance if at least one of its children are being used in the instance
]]]
Not included in the specification but important for interoperability
[[1] - no embedded validation schema location of any kind
[[2] - e.g. W3C Schema offers the feature of embedding a linked association between a namespace URI string and a system URI location
[[3] - supposed to be implemented by validation tools as a hint only and not a directive
][2] - an example (that should not be followed) of embedding a W3C Schema schema association in a UBL Invoice instance:
[Example 5-1: 01 <Invoice
02 xmlns:cbc="urn:oasis:names:...:CommonBasicComponents-2"
03 xmlns:cac="urn:oasis:names:...:CommonAggregateComponents-2"
04 xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
05 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
06 xsi:schemaLocation="
07 urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
08 u:/cd/artefacts/os-UBL-2.0/xsd/maindoc/UBL-Invoice-2.0.xsd
09 ">
10 <cbc:UBLVersionID>2.0</cbc:UBLVersionID>
11 ...
]
[2] - for the trading partner creating the document, this might work fine and validate without error
[2] - for a trading partner receiving the document, this typically would not work because the system identifiers on the two systems
are different
[2] - some W3C Schema tools interpret this feature as an explicit directive that cannot be turned off
[[3] - the instance will fail validation when the system identifier cannot be resolved
]]]
A community of users must agree on a number of auxiliary specifications for the documents, including (but not limited to):
[[1] - a calculation model to use for the arithmetic performed on the information items
[[2] - e.g. Danish OIOUBL project documents their calculation model
[[3] - [http://www.oioubl.info/documents/en/en/Guidelines/OIOUBL_GUIDE_TOTALS.pdf]
]][1] - a suite of code lists and value lists and the contexts in which those lists are used
[1] - a set of business rules governing the content
[1] - altogether these form a customization specifications
[[2] - this is described in more detail in [Chapter 9.]
]]
Information semantic integrity and validation is not defined by the UBL specification
[[1] - the validity of the content of the document is the responsibility of applications
[[2] - e.g. whether columns add up or taxes are calculated properly
][1] - XML standards only govern the validity of the expression of the content in syntax
[1] - validation unburdens an application from having to check for syntactic accuracy
[[2] - having validated a document, an application can focus on the meaning of the values, not on the lexical constraints of the
text used for values
[[3] - an exception would be for patterns for identifiers or other values not checked by validation
][2] - all applications using the same validation are ensure of consistent checking of those constraints covered by the validation
tasks
][1] - an application may perform semantic validation based on business issues
[[2] - e.g. an ordered item is out of stock or has the wrong identification number
]]
The domain and scenario for a UBL document are encoded in the instance itself
[[1] - all document types have element information items reserved for identifying the domain
[1] - cbc:UBLVersionID - version of UBL document models
[[2] - unspecified value indicates version 2.0
[2] - a specified value indicates that the instance is posited to validate against the published document models for the given version
number
[[3] - e.g. the value "2.3" indicates that the instance is intended to be validated with any document model defined by version 2.3 or above
[3] - the actual items found within are defined by UBL 2.0, 2.1 or 2.2
][2] - to promote interoperability, this should (but is not required to) reflect the "high-water mark" of the earliest version of
UBL needed to support all of the information items in the instance
[[3] - the value may be any version later but cannot be any version earlier
]][1] - cbc:CustomizationID - domain of definition and use
[[2] - identifies the community of users or the defining collection of profiles and document types
][1] - cbc:ProfileID - scenario of definition and use
[[2] - identifies the collection of document types within a customization
[2] - identifies and informs the business rules and business processes associated with the document
[[3] - a given document type may be used differently and/or configured differently in different profiles
]][1] - document element (e.g. in:Invoice, po:Order, etc) - document type
[[2] - identifies which document within a profile
]]
5.2.3 Sample UBL instances
[> 5.2.4][> 6.][< 5.2.2][^][^^][^^^]
http://docs.oasis-open.org/ubl/os-UBL-2.0/xml/ directory
Excerpt from xml/UBL-Invoice-2.0-Example.xml, focusing on line 115:
[Example 5-2: 01 <Invoice xmlns="urn:oasis:...:ubl:schema:xsd:Invoice-2"
02 xmlns:cac="urn:oasis:...:ubl:schema:xsd:CommonAggregateComponents-2"
03 xmlns:cbc="urn:oasis:...:ubl:schema:xsd:CommonBasicComponents-2">
04 ...
05 <cac:PayeeFinancialAccount>
06 <cbc:ID>12345678</cbc:ID>
07 <cbc:Name>Farthing Purchasing Consortia</cbc:Name>
08 <cbc:AccountTypeCode>Current</cbc:AccountTypeCode>
09 <cbc:CurrencyCode>GBP</cbc:CurrencyCode>
10 <cac:FinancialInstitutionBranch>
11 <cbc:ID>10-26-58</cbc:ID>
12 <cbc:Name>Open Bank Ltd, Bridgstow Branch </cbc:Name>
13 <cac:FinancialInstitution>
14 <cbc:ID>10-26-58</cbc:ID>
15 <cbc:Name>Open Bank Ltd</cbc:Name>
16 <cac:Address>
17 <cbc:StreetName>City Road</cbc:StreetName>
18 <cbc:BuildingName>Banking House</cbc:BuildingName>
19 <cbc:BuildingNumber>12</cbc:BuildingNumber>
20 <cbc:CityName>London</cbc:CityName>
21 <cbc:PostalZone>AQ1 6TH</cbc:PostalZone>
22 <cbc:CountrySubentity>London</cbc:CountrySubentity>
23 <cac:AddressLine>
24 <cbc:Line>5th Floor</cbc:Line>
25 </cac:AddressLine>
26 <cac:Country>
27 <cbc:IdentificationCode>GB</cbc:IdentificationCode>
28 </cac:Country>
29 </cac:Address>
30 ...
31 </Invoice>
]
Looking at the mod/common/UBL-CommonLibrary-2.0 spreadsheet
[[1] - look on row 719 to find PayeeFinancialAccount ASBIE, and note in column M the associated object class is "Financial Account"
[1] - look on row 394 to find "FinancialAccount" ABIE
]
Looking at Crane's model report
[[1] - click on "PA" index entry, then scroll to "PayeeFinancialAccount" and click on row "719" to bring up the ASBIE
[1] - then click on the ASBIE name in order to bring up row 394 to find the "FinancialAccount" ABIE
]
5.2.4 XML Namespaces
[> 5.2.5][> 6.][< 5.2.3][^][^^][^^^]
Namespaces are used to create globally-unique labels for the information items
[[1] - without namespaces then element and attribute names may be ambiguous between different vocabularies
[1] - a namespace prefix is a proxy to a namespace URI string
[[2] - the prefix may be absent for elements
][1] - the processed label of an item is the combination of the namespace URI string and the item's name
[[2] - the prefix used is immaterial
[2] - no obligation to use the same prefixes used in UBL artefacts
]]
A UBL name is not unique without considering the namespace
[[1] - e.g. cac:Location and cbc:Location are two different information items
[[2] - the two elements have different semantics (meanings)
]]
Documentary convention for namespace prefixes in UBL documentation
[[1] - there is no obligation to use these prefixes in any given UBL document
[[2] - programs must not assume that these documentary prefixes will be used
][1] - e.g. harry:Location and sally:Location are the same information item if the two proxies point to the same URI strings
[1] - programs must not rely on the prefix used and must rely solely on the fully qualified name as indicated by dereferencing the
prefix to its associated URI string
]
Library namespace prefixes:
[Example 5-3: 01 xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
02 xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
03 xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"
04 xmlns:sdt="urn:oasis:names:specification:ubl:schema:xsd:SpecializedDatatypes-2"
05 xmlns:udt="urn:un:unece:uncefact:data:specification:UnqualifiedDataTypesSchemaModule:2"
]
Document type namespace prefixes:
[Example 5-4: 01 xmlns:ar="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2"
02 xmlns:ad="urn:oasis:names:specification:ubl:schema:xsd:AttachedDocument-2"
03 xmlns:bl="urn:oasis:names:specification:ubl:schema:xsd:BillOfLading-2"
04 xmlns:ct="urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2"
05 xmlns:cd="urn:oasis:names:specification:ubl:schema:xsd:CatalogueDeletion-2"
06 xmlns:cu="urn:oasis:names:specification:ubl:schema:xsd:CatalogueItemSpecificationUpdate-2"
07 xmlns:cp="urn:oasis:names:specification:ubl:schema:xsd:CataloguePricingUpdate-2"
08 xmlns:cr="urn:oasis:names:specification:ubl:schema:xsd:CatalogueRequest-2"
09 xmlns:co="urn:oasis:names:specification:ubl:schema:xsd:CertificateOfOrigin-2"
10 xmlns:cn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
11 xmlns:dn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2"
12 xmlns:da="urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2"
13 xmlns:fw="urn:oasis:names:specification:ubl:schema:xsd:ForwardingInstruction-2"
14 xmlns:fr="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2"
15 xmlns:in="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
]
[Example 5-5: 01 xmlns:po="urn:oasis:names:specification:ubl:schema:xsd:Order-2"
02 xmlns:ox="urn:oasis:names:specification:ubl:schema:xsd:OrderCancellation-2"
03 xmlns:oc="urn:oasis:names:specification:ubl:schema:xsd:OrderChange-2"
04 xmlns:or="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2"
05 xmlns:os="urn:oasis:names:specification:ubl:schema:xsd:OrderResponseSimple-2"
06 xmlns:pl="urn:oasis:names:specification:ubl:schema:xsd:PackingList-2"
07 xmlns:qn="urn:oasis:names:specification:ubl:schema:xsd:Quotation-2"
08 xmlns:ra="urn:oasis:names:specification:ubl:schema:xsd:ReceiptAdvice-2"
09 xmlns:rd="urn:oasis:names:specification:ubl:schema:xsd:Reminder-2"
10 xmlns:rt="urn:oasis:names:specification:ubl:schema:xsd:RemittanceAdvice-2"
11 xmlns:rq="urn:oasis:names:specification:ubl:schema:xsd:RequestForQuotation-2"
12 xmlns:sc="urn:oasis:names:specification:ubl:schema:xsd:SelfBilledCreditNote-2"
13 xmlns:si="urn:oasis:names:specification:ubl:schema:xsd:SelfBilledInvoice-2"
14 xmlns:st="urn:oasis:names:specification:ubl:schema:xsd:Statement-2"
15 xmlns:ts="urn:oasis:names:specification:ubl:schema:xsd:TransportationStatus-2"
16 xmlns:wb="urn:oasis:names:specification:ubl:schema:xsd:Waybill-2"
]
Common in UBL instances that the default namespace is used
[[1] - the absence of a prefix indicates the use of the default namespace
[1] - attributes without prefixes are in no namespace, not in the default namespace
]
An excerpt from an invoice instance:
[Example 5-6: Sample instance01 <?xml version="1.0" encoding="UTF-8"?>
02 <Invoice xmlns="urn:oasis:...:xsd:Invoice-2"
03 xmlns:cac="urn:oasis:...:xsd:CommonAggregateComponents-2"
04 xmlns:cbc="urn:oasis:...:xsd:CommonBasicComponents-2">
05 <cbc:ID>A00095678</cbc:ID>
06 <cbc:CopyIndicator>false</cbc:CopyIndicator>
07 <cbc:UUID>849FBBCE-E081-40B4-906C-94C5FF9D1AC3</cbc:UUID>
08 <cbc:IssueDate>2005-06-21</cbc:IssueDate>
09 <cbc:InvoiceTypeCode>SalesInvoice</cbc:InvoiceTypeCode>
10 <cbc:Note>sample</cbc:Note>
11 <cbc:TaxPointDate>2005-06-21</cbc:TaxPointDate>
12 <cbc:DocumentCurrencyCode>GBP</cbc:DocumentCurrencyCode>
13 <cac:OrderReference>
14 <cbc:ID>AEG012345</cbc:ID>
15 <cbc:SalesOrderID>CON0095678</cbc:SalesOrderID>
16 <cbc:UUID>6E09886B-DC6E-439F-82D1-7CCAC7F4E3B1</cbc:UUID>
17 <cbc:IssueDate>2005-06-20</cbc:IssueDate>
18 </cac:OrderReference>
19 ...
20 <cac:AllowanceCharge>
21 <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
22 <cbc:AllowanceChargeReasonCode>17</cbc:AllowanceChargeReasonCode>
23 <cbc:MultiplierFactorNumeric>0.10</cbc:MultiplierFactorNumeric>
24 <cbc:Amount currencyID="GBP">10.00</cbc:Amount>
25 </cac:AllowanceCharge>
26 ...
]
Note that most values are in elements while some are in attributes:
[[1] - e.g. an ABIE element
[[2] - <Invoice>...</Invoice>
[2] - this element is using the default namespace (because there is no name prefix)
[2] - the content of an ABIE is made up entirely of other elements
][1] - e.g. an ABIE element as an ASBIE:
[[2] - <cac:OrderReference>...</cac:OrderReference>
][1] - e.g. a BBIE element:
[[2] - <cbc:DocumentCurrencyCode>GBP</cbc:DocumentCurrency
Code>
[2] - the content of a BBIE is made up entirely of text
][1] - e.g. an attribute: currencyID="GBP"
[[2] - all attributes without prefixes are not in any namespace
]]
5.2.5 Unconstrained content
[> 5.2.6][> 6.][< 5.2.4][^][^^][^^^]
UBL extension point defined for customized extended content
[[1] - regarded by the UBL models as unconstrained content as from the UBL model's perspective there are no label constraints on
the descendants of the <ext:ExtensionContent> element
[[2] - XML syntax rules still apply
][1] - a UBL customization takes advantage of the extension point to add constructs to the document model that are not defined by
the UBL information model
[[2] - a customized UBL schema would then impose its own constraints on the extension content
][1] - the apex of the extension content should be in a non-UBL namespace
[[2] - but this cannot be expressed in W3C Schema constraints
][1] - <ext:ExtensionContent> is the only UBL element that is allowed to be empty
[[2] - intermediate processing may discard content in unrecognized namespaces
[2] - the fact that the element is empty does not convey any information or meaning
]]
Serial processing applications see extensions before seeing any standardized content
[[1] - the extensibility point is the first child of the document element of all document models
[1] - extension information can be cached until needed when correlating information found in the standardized constructs
[1] - the extensibility element is not present if the instance has no extensions
]
Any given UBL instance may include multiple extension fragments
[[1] - each extension is specified below a <ext:UBLExtension> element
[1] - all <ext:UBLExtension> elements are specified below a single <ext:UBLExtensions> element
[1] - meta data is available to describe the extension content
[1] - the name and namespace of the apex of extension content should also be distinct for each extension definition
]
An extension may have associated meta data with which to identify its source or use
[[1] - all extension meta data is optional, but should be used for clarity
[1] - note that extensions may include the use of standard UBL constructs
]
[Example 5-7: 01 <Invoice xmlns="urn:oasis:...:xsd:Invoice-2"
02 xmlns:cbc="urn:oasis:...:xsd:CommonBasicComponents-2"
03 xmlns:cac="urn:oasis:...:xsd:CommonAggregateComponents-2"
04 xmlns:ext="urn:oasis:...:xsd:CommonExtensionComponents-2"
05 xmlns:demo="urn:x-Demo:Demo">
06 <ext:UBLExtensions>
07 <ext:UBLExtension>
08 <cbc:ID>Demo1</cbc:ID>
09 <cbc:Name>Demonstration</cbc:Name>
10 <ext:ExtensionAgencyID>CSL</ext:ExtensionAgencyID>
11 <ext:ExtensionAgencyName>Crane Softwrights Ltd.
12 </ext:ExtensionAgencyName>
13 <ext:ExtensionVersionID>0.1</ext:ExtensionVersionID>
14 <ext:ExtensionAgencyURI>http://www.CraneSoftwrights.com/
15 links/res-dev.htm</ext:ExtensionAgencyURI>
16 <ext:ExtensionURI>urn:x-Demo:Demo:0.1</ext:ExtensionURI>
17 <ext:ExtensionReasonCode listURI="urn:x-Demo:Demo:ReasonCodes">1
18 </ext:ExtensionReasonCode>
19 <ext:ExtensionReason>Illustration</ext:ExtensionReason>
20 <ext:ExtensionContent>
21 <demo:Demo>
22 <demo:Thing>This is a test</demo:Thing>
23 <cbc:ID>DemoTest</cbc:ID>
24 <demo:Total currencyID="GBP">100.00</demo:Total>
25 </demo:Demo>
26 </ext:ExtensionContent>
27 </ext:UBLExtension>
28 </ext:UBLExtensions>
29
30 <cbc:ID>A00095678</cbc:ID>
31 <cbc:IssueDate>2005-06-21</cbc:IssueDate>
32 <cbc:Note>sample</cbc:Note>
33 <cac:AccountingSupplierParty>
34 <cac:Party>
35 <cac:PartyName>
36 ...
]
5.2.6 XML document models
[> 5.2.7][> 6.][< 5.2.5][^][^^][^^^]
XML documents are constrained at a label level by an expression of constraints in an XML document model
[[1] - constrains the use of elements and their attributes (the only labels for information)
[1] - different schema languages are used to describe document constraints using different approaches
[1] - a grammar-based expression of constraints
[[2] - XML Document Type Definition (DTD)- [http://www.w3.org/TR/REC-xml]
[2] - ISO/IEC 19757-2 RELAX-NG - [http://www.relax-ng.org]
[[3] - Regular Language for XML
]][1] - an assertion-based expression of constraints
[[2] - ISO/IEC 19757-3 Schematron - [http://www.schematron.com]
][1] - a type-hierarchy-based expression of constraints
[[2] - W3C Schema (chosen by the UBL TC for UBL document models)
[[3] - [http://www.w3.org/XML/Schema]
[3] - [http://www.w3.org/TR/xmlschema-0/] - primer
[3] - [http://www.w3.org/TR/xmlschema-1/] - structures
[3] - [http://www.w3.org/TR/xmlschema-2/] - datatypes
]][1] - the dispatch of portions of a document tree to different validation tasks
[[2] - ISO/IEC 19757-4 NVDL - [http://www.nvdl.org]
[2] - Namespace-based Validation Dispatching Language
][1] - a growing family of validation-related standards
[[2] - ISO/IEC 19757 DSDL - [http://www.dsdl.org]
[2] - Document Schema Definition Languages
]]
XML instance annotations cannot be constrained
[[1] - comments and processing instructions can be present or absent anywhere allowed by the XML Recommendation
[[2] - does not interfere with the constraints of the elements, attributes and text
][1] - can be added for explanatory or processing purposes without disturbing the validity of the document
[1] - comments are annotations for a person to read
[[2] - information about the instance
[[3] - e.g. creation meta data (author, generating software, etc.)
[3] - e.g. source code control strings
]][1] - processing instructions are annotations for a program to read
[[2] - information controlling the processing of the instance
]]
5.2.7 W3C Schema model fragments
[> 5.2.8][> 6.][< 5.2.6][^][^^][^^^]
XSD fragments are, themselves, XML files
[[1] - elements and attributes in the http://www.w3.org/2001/XMLSchema namespace
[1] - fragment annotations are included as XML comments
[[2] - copyright statement, creation information, etc.
]]
XSD model annotations are formalisms expressed in elements
[[1] - these annotations are not the same as XML annotations
[1] - XSD models are XML documents so XML annotations may be included in addition to XSD annotations
[1] - XSD semantics include formal documentation constructs with which to make annotations richly-defined machine-processed
]
The reference to AdditionalStreetName BBIE in the Address ABIE has the following XSD annotations:
[Example 5-8: Sample documentation constructs01 <xsd:element ref="cbc:AdditionalStreetName"
02 minOccurs="0" maxOccurs="1">
03 <xsd:annotation>
04 <xsd:documentation>
05 <ccts:Component>
06 <ccts:ComponentType>BBIE</ccts:ComponentType>
07 <ccts:DictionaryEntryName>Address. Additional_ Street Name.
08 Name</ccts:DictionaryEntryName>
09 <ccts:Version></ccts:Version>
10 <ccts:Definition>An additional name of a street used to
11 further specify the Street Name</ccts:Definition>
12 <ccts:Cardinality>0..1</ccts:Cardinality>
13 <ccts:ObjectClass>Address</ccts:ObjectClass>
14 <ccts:PropertyTermQualifier>Additional</ccts:PropertyTermQualifier>
15 <ccts:PropertyTerm>Street Name</ccts:PropertyTerm>
16 <ccts:RepresentationTerm>Name</ccts:RepresentationTerm>
17 <ccts:DataType>Name. Type</ccts:DataType>
18 ...
]
http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/ directory
[[1] - the full schema expressions complete with all documentary annotation constructs
[1] - these are the only normative formal expressions of the UBL 2.0 specification
]
http://docs.oasis-open.org/ubl/os-UBL-2.0/xsdrt/ directory
[[1] - the compact schema expressions without any documentary XSD annotation constructs
[1] - some schema validation tools run faster without having to process the documentary XSD annotations
]
http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/maindoc/ directory:
[[1] - one schema fragment for each document type (recall [Figure 4.1])
[[2] - corresponds to the document model for each document type
[2] - used as the invocation schema fragment for the validation task
][1] - UBL-ApplicationResponse-2.xsd
[1] - UBL-AttachedDocument-2.xsd
[1] - UBL-BillOfLading-2.xsd
[1] - UBL-Catalogue-2.xsd
[1] - UBL-CatalogueDeletion-2.xsd
[1] - UBL-CatalogueItemSpecificationUpdate-2.xsd
[1] - UBL-CataloguePricingUpdate-2.xsd
[1] - UBL-CatalogueRequest-2.xsd
[1] - UBL-CertificateOfOrigin-2.xsd
[1] - UBL-CreditNote-2.xsd
[1] - UBL-DebitNote-2.xsd
[1] - UBL-DespatchAdvice-2.xsd
[1] - UBL-ForwardingInstructions-2.xsd
[1] - UBL-FreightInvoice-2.xsd
[1] - UBL-Invoice-2.xsd
[1] - UBL-Order-2.xsd
[1] - UBL-OrderCancellation-2.xsd
[1] - UBL-OrderChange-2.xsd
[1] - UBL-OrderResponse-2.xsd
[1] - UBL-OrderResponseSimple-2.xsd
[1] - UBL-PackingList-2.xsd
[1] - UBL-Quotation-2.xsd
[1] - UBL-ReceiptAdvice-2.xsd
[1] - UBL-Reminder-2.xsd
[1] - UBL-RemittanceAdvice-2.xsd
[1] - UBL-RequestForQuotation-2.xsd
[1] - UBL-SelfBilledCreditNote-2.xsd
[1] - UBL-SelfBilledInvoice-2.xsd
[1] - UBL-Statement-2.xsd
[1] - UBL-TransportationStatus-2.xsd
[1] - UBL-Waybill-2.xsd
]
http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/common/ directory:
[[1] - the arrangement of schema fragments does not correspond to library model files
[[2] - the partitioning is by role of the contained information items, definitions (types) and declarations (elements)
][1] - CCTS definitions used by the UBL schemas:
[[2] - CodeList_CurrencyCode_ISO_7_04.xsd
[[3] - fixed set of enumerations for currencies of the world
][2] - CodeList_MIMEMediaTypeCode_IANA_7_04.xsd
[[3] - fixed set of enumerations for MIME types of the Internet
][2] - CodeList_UnitCode_UNECE_7_04.xsd
[[3] - fixed set of enumerations for units of measure for UN/CEFACT
][2] - UnqualifiedDataTypeSchemaModule-2.xsd
[[3] - corresponding to the "udt" module in the schema dependency diagram on [Figure 4.1]
[[4] - urn:un:unece:uncefact:data:specification:UnqualifiedDataTypesSchemaModule:2
[4] - imports all the CCTS fragments in use
][3] - definition of unqualified core component data types
[[4] - included definitions used by UBL
[[5] - AmountType, BinaryObjectType, CodeType, DateType, IdentifierType, IndicatorType, MeasureType, NameType, NumericType, PercentType, QuantityType, RateType, TextType, and TimeType
][4] - included definitions not used by UBL
[[5] - GraphicType, PictureType, SoundType, VideoType, DateTimeType, and ValueType
]][3] - defines the structure of core components and supplementary components
[[4] - uses the CCTS code lists for the supplementary components
]]][1] - CCTS definitions not used by the UBL schemas (but included in the package):
[[2] - CCTS_CCT_SchemaModule-2.xsd
[[3] - definition of core component types corresponding to UN/CEFACT concepts
[3] - provided only for documentation of UN/CEFACT constructs
][2] - CodeList_LanguageCode_ISO_7_04.xsd
[[3] - fixed set of enumerations for languages of the world
]]]
[[1] - UBL definitions:
[[2] - corresponding to the fragments depicted on [Figure 4.1]
[[3] - the cited three-letter prefixes are only documentary and are not mandatory
][2] - UBL-CommonAggregateComponents-2.xsd ("cac")
[[3] - urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2
[3] - declaration of ABIE elements and definition of associated type for each
][2] - UBL-CommonBasicComponents-2.xsd ("cbc")
[[3] - urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2
[3] - declaration of BBIE elements and definition of associated type for each
][2] - UBL-CommonExtensionComponents-2.0.xsd ("ext")
[[3] - urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2
[3] - definition of extension meta data types
][2] - UBL-ExtensionContentDatatype-2.0.xsd ("ext")
[[3] - urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2
[3] - definition of extension content
[3] - this module is replaced for customization schemas with an equivalent module that imports the extension constructs in the customization
namespace
][2] - urn:oasis:names:specification:ubl:schema:xsd:QualifiedDatatypes-2
[2] - UBL-QualifiedDatatypes-2.xsd ("qdt")
[[3] - definition of meta data for non-ATG2-based coded-value data types
]][1] - UBL housekeeping:
[[2] - housekeeping declaration of a namespace URI for documenting core component parameters of the information elements
[2] - UBL-CoreComponentParameters-2.xsd ("ccts")
[2] - urn:un:unece:uncefact:documentation:2
[2] - module contains no information item declarations or type definitions
[2] - module is not imported by any fragment
]]
Recall the schema structures at [Figure 4.1]
[[1] - note the use of <xsd:include> rather than <xsd:import>
[[2] - xsd:include is obliged to be used when the included fragment defines constructs in the same namespace as the including fragment
[2] - xsd:import is obliged to be used when the imported fragment defines constructs in a different namespace as the importing fragment
]]
Document validation is done only starting with the document schema
[[1] - the document is not imported or included by any other schema fragment
]
Note how the extension namespace construct declarations are split between those that are common and the single construct that
defines the extension point
[[1] - when defining a customization with extensions in a customization namespace, the content data type fragment is replaced with
a fragment importing the customization constructs
[1] - this fragmentation prevents the common meta data extension constructs from being potentially disturbed
]
5.2.8 UBL document validation
[> 5.2.9][> 6.][< 5.2.7][^][^^][^^^]
XML document validation relieves an application only of the responsibility of checking UBL vocabulary constraints
[[1] - the documented processing model is only a candidate for consideration and is not mandatory
[1] - an application can be implemented without structure and value validation when other processes are responsible for reporting
violations of the document constraints
[1] - a set of applications reflect the same structure and value validation when all are using the same outboard processing model
]
Structure constraint checking
[[1] - confirms the nesting of elements within other elements
[[2] - cardinality of labeled constructs
[2] - ordering of labeled constructs
][1] - confirms the lexical limitations on the structure of strings of XML text
[[2] - some lexical limitations are non-existent
[[3] - e.g. names and address
[[4] - an arbitrary string
]][2] - some lexical limitations are simple
[[3] - e.g. normalized string values
[[4] - a normalized string has a set of white-space-separated values
]][2] - some lexical limitations are stringent
[[3] - e.g. numeric values
[[4] - a number can only have a sign, digits, and "." for the decimal separator
]][2] - note there are still XML syntax rules governing the escaping of sensitive markup characters in text
[[3] - lexical validation performed on the interpreted marked up XML text
]][1] - no constraints on the length of the text string for any value
]
Value constraint checking
[[1] - can only be performed when information items are where they belong
[1] - if the document structure is incorrect then assertions about content cannot be verified
[1] - UBL is shipped with constrained values for coded-value information items for which the technical committee has supplied values
[1] - item length is considered a value constraint, not a lexical constraint
[[2] - the UBL schemas do not impose any constraints on the lengths of values
]]
Semantic (business) interpretation
[[1] - a UBL application is still responsible for checking semantic content violations
[1] - no amount of document structure and value checking can replace the application's need to implement the application's logic
[1] - e.g. appropriate taxation application
[1] - e.g. checking of inventory against ordered parts
]
The UBL 2.0 published document validation process involves only two distinct steps:
[[1] - first-pass structure (well-formed, structural and lexical) validation using XSD (1)
[[2] - ensures that all information items are correctly labeled and correctly positioned
[2] - e.g. for an invoice the document schema is:
[2] - http://docs.oasis-open.org/ubl/os-UBL-2.0/xsd/maindoc/UBL-Invoice-2.0.xsd
][1] - second-pass coded-value validation using XSLT (2)
[[2] - ensures the values used for coded-value information items are as expected
[2] - http://docs.oasis-open.org/ubl/os-UBL-2.0/val/defaultCodeList.xsl
[2] - the XSLT is an implementation of ISO/IEC 19757-3 Schematron
[[3] - the specification of the constraints is described in [Chapter 8.]
[3] - the specification is translated into Schematron
[3] - the Schematron is translated into XSLT
]]]
[Figure 5.1: Two-step validation
The diagram is split with a horizontal line indicating runtime process above the line and advance preparation process below
the line.
Above the line and at the left is an incoming UBL instance depicted as a triangle labeled "XML". This is connected by an arrow
to the box at the right labeled "Application Code" under the column "Semantic Interpretation". Two arrows lead down from this
horizontal arrow, one under the column "Structure Validation" to a box labeled "W3C Schema", and the other under the column
"Value Validation" to a box labeled "XSLT".
Below the line and under the column "Structure Validation" an "XSD" labeled triangle titled "Structure Constraints" and identified
with a circled "1" has an arrow leading into the "W3C Schema" box. Below the line and under the column "Value Validation"
an "XSLT" labeled triangle titled "Value Constraints" and identified with a circled "2" has an arrow leading into the "XSLT"
box.
]
Demonstrated using http://docs.oasis-open.org/ubl/os-UBL-2.0/val/validate.bat (.sh)
[[1] - invoked by test.bat and test.sh in the val/ directory
]
Recall [UBL information item constraints - Section 3.1.5]
[[1] - an initial set of coded values is defined by the TC for some elements and attributes
]
Not all UBL users may be using the same version of the schema
[[1] - different communities or different members of any one community may not be in sync
[1] - in a heterogeneous network of users, there will be "older" systems needing to interact with "newer" systems because of differing
product cycles
]
To support forward and subset compatibility, the processing model is modified:
[[1] - e.g. supporting UBL 2.x when receiving UBL 2.y instances where y > x
[[2] - i.e. 2.y is published after 2.x
][1] - e.g. supporting a subset of UBL when using complete UBL instances
[1] - to support a given schema, filter (F) removes unexpected items from the instance
[[2] - but only bother filtering if the instance as given has unexpected items
][1] - the same schema is again used to check both unfiltered and filtered content
[[2] - a failure after both means the filtered instance is also unacceptable
[2] - success proceeds as if the unfiltered instance was acceptable
][1] - the application is informed of initial pass/fail indication
[[2] - can use automated or out-of-band decision making regarding the fact that the filtered instance is being used instead of the
original instance
]]
[Figure 5.2: Three-step validation
The diagram is split with a horizontal line indicating runtime process above the line and advance preparation process below
the line.
Above the line and at the left is an incoming UBL instance depicted as a triangle labeled "XML". This is connected by an arrow
to the box at the right labeled "Application Code" under the column "Semantic Interpretation". Two arrows lead down from this
horizontal arrow, one under the column "Structure Validation" to a box labeled "W3C Schema", and the other under the column
"Value Validation" to a box labeled "XSLT".
Below the line and under the column "Structure Validation" an "XSD" labeled triangle titled "Structure Constraints" and identified
with a circled "1" has an arrow leading into the "W3C Schema" box. Below the line and under the column "Value Validation"
an "XSLT" labeled triangle titled "Value Constraints" and identified with a circled "2" has an arrow leading into the "XSLT"
box.
]
5.2.9 UBL validation errors
[> 6.][< 5.2.8][^][^^][^^^]
XML well-formedness error
[[1] - the document is not XML because it does not pass all the productions in the XML Recommendation
[1] - e.g. missing a right angle bracket from a tag
[1] - checked by an XML processor without the need for a document model
]
XSD structural or lexical error
[[1] - the XML document is well-formed but the use of element and attribute labels violates the constraints expressed in the XSD
schemata
[1] - e.g. cardinality
[[2] - e.g. a mandatory element is missing
][1] - e.g. sequence
[[2] - e.g. elements are not in the correct order
][1] - e.g. recognition
[[2] - i.e. an information item being used is not defined by the schema
[2] - e.g. a typographical error in the spelling of an element or attribute name
][1] - e.g. lexical values
[[2] - i.e. an element's content is not allowed for the element's data type
[2] - e.g. having alphabetic letters in a numeric data type
][1] - checked by an XSD validating processor according to the constraints of a document model
]
Controlled vocabulary error
[[1] - an error in the information item valued from expected sets of code lists and identifiers
[1] - a test of a value being used violates the set of allowed values for that item
[1] - checked by an XSLT processor using a synthesized stylesheet that checks the values expected for controlled value items
]
UBL semantic (business) error
[[1] - e.g. the item ordered is out of stock
[1] - e.g. the sum of all of the line item amounts does not equal the total amount
[1] - e.g. an incorrect tax rate is being applied based on the tax status of the customer
[1] - checked by an application acting on the UBL instance
]
This is an accessible version of Crane's commercial training material.
The content has been specifically designed to assist screen reader software
in viewing the entire textual content. Figures are replaced with text
narratives.
Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome:
[info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect
this accessible version from plagiarism, please do not make any
commercial edition available to others.
+//ISBN 1-894049::CSL::Presentation::UBL//DOCUMENT Practical Universal Business Language Deployment 2009-02-12 13:50UTC//EN
Practical Universal Business Language Deployment
Third Edition - 2009-02-12
ISBN 978-1-894049-23-8
Copyright © Crane Softwrights Ltd.