[Accessibility conventions are described at the bottom of the page]
5. Associating controlled vocabularies in XML documents
[> 6.][< 4.2.1][^^^]
5.0 Constraining information items using controlled vocabularies
[> 5.0.1][> 5.1][> 6.][< 5.][^^][^^^]
Three kinds of constraints to be validated for an XML document
[[1] - structural constraints ensure information items are correctly found
[1] - lexical constrains ensure information items are correctly formed
[1] - value constraints ensure information items are correctly understood
]
Constraining the document structure and lexical patterns is independent of business/value rules
[[1] - a community of users can publish an agreed upon schema to validate information items are correctly found and formed
]
Constraining information item use of controlled vocabularies is very dependent on business/value rules
[[1] - business/value rules implied by the nature of the information item
[[2] - e.g. points of a compass will never change
][1] - business/value rules imposed by a community of users
[[2] - e.g. the document status codes for the condition of a document in a transaction
][1] - business/value rules agreed upon between trading partners
[[2] - e.g. identification of account numbers for particular purposes
]]
Typical use of W3C Schema conflates structural and value constraints inflexibly
[[1] - one gets more flexibility by separating value constraints from structural constraints
[1] - only structural constraints should be imposed across a community of users
[[2] - standard should constrain how the information is found and how it is formed, not how it is valued
[2] - very infrequent changes to the structure of information being interchanged
[2] - changes imply big impacts on applications and processing
][1] - value constraints should be selectively imposed
[[2] - changes in trading partners
[2] - changes in business practices over time
[2] - possibly frequent changes to the values allowed by different parties
[2] - once programs accommodate a given set of values, changing the subsets of values in use doesn't change the applications
][1] - business rules should be selectively added
[[2] - private requirements could never be anticipated by standards committees
]]
5.0.1 Context/value association
[> 5.0.2][> 5.1][> 6.][< 5.0][^][^^][^^^]
Context/value association files
[[1] - [http://www.oasis-open.org/committees/document.php?document_id=29990]
[1] - an XML vocabulary for associating document contexts with specified values
[1] - suitable for constraining document entry in a user interface
[1] - suitable for document validation before application processing
[1] - techniques for specifying, restricting and extending lists for the purposes of validation
]
Masquerading meta data when restricting a large list to a subset of values
[[1] - the validation needs to match an instance's use of large list meta data to a declaration of a subset list using subset list
list-level meta data
[1] - the subset list list-level meta data necessarily is different than the list-level meta data of the list from which it is derived
[1] - the subset list masquerades as the list from which it is derived so that instance-level meta data doesn't use the custom subset
list list-level meta data
]
ISO/IEC 19757-3 Schematron deployment
[[1] - as supplied, the methodology reports context/value constraint violations in simple text
[1] - Schematron can alternatively be deployed with different available reporting techniques
]
The principles of context/value association are as follows:
[[1] - XML documents have information items that need to be validated
[[2] - the locations (contexts) of those items can be addressed using XPath addresses
][1] - genericode files have values and list meta data to use for validation
[[2] - the locations of those files can be declared with URL addresses
[2] - the identity of each list is uniquely specified in order to be referenced multiple times
][1] - an association marries a document context with a set of genericode files
[[2] - each XPath document context is specified with the identities of the genericode declarations
][1] - validation checks values found in document contexts against genericode files linked by the association for the document context
[[2] - any present meta data in the document context is checked with the available genericode meta data
]]
[Figure 5.1: Context/value association
Three groups of triangles are shown, one triangle labeled "Document Instance Being Validated", a set of triangles labeled
"External Value List Expressions", and one triangle labeled "Context/Value Associations".
In the triangle labeled "Context/Value Associations" are a number of drawn areas with arrows pointing to other triangles.
The areas are labeled "An association ties a document context to one or more lists of valid values".
All areas each have one arrow to the "Document Instance Being Validated" triangle, with the arrow labeled "Document context
specifies information items being validated". All areas have one or more arrows pointing to the "External Value List Expressions"
triangles, with the arrow labeled "Lists of valid values are referenced by file location".
]
Appropriate for constraining data entry application user interfaces
[[1] - used as a front end to a user preventing the data entry of different values
[[2] - drop-down lists
[2] - radio buttons
[2] - check boxes
][1] - the end result of editing an instance is that the values are all from the associated lists
[1] - the value-level meta data can be presented to the user
[[2] - assists the user in choosing which value or values to use
][1] - the options to include instance-level meta data should be offered
[[2] - reflects the list-level meta data for the list from where the values are taken
]]
Appropriate for constraining data validation
[[1] - used as a front end to an application that implements the logic for all possible values
[1] - selective association for business scenarios prevents the application from acting on inappropriate values for a given transaction
[[2] - relationships between specific partners may be different
[2] - different profiles of using documents may constrain particular values
]]
Only the CVA vocabulary is standardized by OASIS, not how it is used
[[1] - the file format and the semantics represented by the elements and attributes are being standardized by OASIS
[1] - any implementation is considered out of scope of the committee work
]
5.0.2 Using context/value association for validation
[> 5.1][> 6.][< 5.0.1][^][^^][^^^]
Separates structural/lexical validation from value validation
[[1] - an XML document is checked using a two-step process
[1] - the first pass for structural and lexical validation passes
[1] - the second pass reports that a coded value used for a currency is unexpected
[1] - the document structure and lexical content can be constrained by standardization
[[2] - e.g. the UBL technical committee publishes normative W3C schemas
][1] - the document controlled-value content is constrained by business requirements between trading partners
[[2] - e.g. the UBL committee publishes default coded value checks
[[3] - defaultCodeList.xsl
][2] - trading partners can use this value validation methodology to create their own value checking second-pass process
]]
[Figure 5.2: 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 XML instance depicted as a triangle. 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.
]
Document arrives at application unchanged
[[1] - validation only confirms the use of structure and content, without modifying it
]
Second pass results meaningless without first pass being successful
[[1] - the values must be correctly found and correctly formed before checking the actual values produces an accurate result
]
Crane-CVA2sch package from Crane Softwrights Ltd. web site
[[1] - historically developed in the OASIS UBL Technical Committee
[1] - moved into the OASIS Code List Representation Technical Committee
[1] - moved out of the OASIS Code List Representation Technical Committee
[[2] - the committee decided to focus on file formats and not methodologies
[2] - intellectual property returned to Crane Softwrights Ltd.
][1] - Crane is donating CVA2sch to an Apache Schematron project
]
A methodology for code list and value validation based on ISO/IEC 19757-3 Schematron
[[1] - an information item is asserted to have one of an allowed set of predetermined values
[[2] - a failed assertion is a value validation error
][1] - assertions are derived from context/value associations
]
Schematron is usually implemented using the Extensible Stylesheet Language (XSLT)
[[1] - the supplied Schematron stylesheet for stylesheets is a copy of the publicly-available reference XSLT implementation
[[2] - [http://www.schematron.com]
[2] - the methodology supplies a wrapper stylesheet for the reference skeleton
][1] - other non-XSLT implementations of Schematron exist
[[2] - e.g. Amara/Scimitar implements ISO Schematron in Python
[[3] - [http://uche.ogbuji.net:8080/uche.ogbuji.net/tech/4Suite/amara/]
[3] - same architecture as reference XSLT implementation in that Scimitar is a Python program that writes a Python program that
performs the validation
]]]
The XSLT generated to implement the Schematron assertions is used as the second pass of validation to test XML instances for
having correct controlled-vocabulary values
[[1] - the testing relies on the first-pass structural validation, having already confirmed the structure and lexical values used
in the instance
[1] - without the first pass confirming the accurate presence of information items, the second pass is meaningless
]
The methodology supports the incorporation of any number of sets of Schematron assertions
[[1] - ISO Schematron supports the inclusion of multiple schema fragments into a single schema expression
[1] - business rules related or unrelated to code lists may be expressed as Schematron assertions
[[2] - the trading partner schema can then include business rules in addition to coded value rules
]]
Overview of the process to prepare the second pass value validation XSLT stylesheet:
[Figure 5.3: Second-pass value-validation artefact creation
The diagram shows triangles and boxes in three different areas.
The area labeled "Definition" shows the "XML" labeled triangle titled "Code List Context Associations" and identified with
a circled "3", a set of "GC" labeled triangles titled "External Code List Expressions" and identified with a circled "4",
and a setoff "SCH" labeled triangles titled "Business Rules" and identified with a circled "6". Each of these has an arrow
directed to a box labeled "Schematron implementation of OASIS context/value association files for validation" in the area
labeled "Preparation".
One arrow leaves this box to the "XSLT" labeled triangle titled "Assertion Validation Stylesheet" and identified with a circled
"2".
One arrow leaves this box to the "XSLT Process" labeled box in the area labeled "Processing". The other input to this box
is a set of "XML" labeled triangles titled "Document Instances Being Validated". The one output from this box is a set of
"Report" labeled parallelograms titled "Validation Reports".
]
[[1] - the circled labels in the diagram are indicated by the parenthesized numbers
[1] - the inputs:
[[2] - (3) the specification of contexts uses the context/value association XML vocabulary defined by the OASIS Code List Representation
TC
[2] - (4) the specification of coded values uses the genericode vocabulary defined by the OASIS Code List Representation TC
[2] - (5) supplemental business rules are specified using ISO/IEC 19757-3 Schematron
][1] - the output:
[[2] - (2) an XSLT stylesheet (or some other implementation of Schematron assertion checking)
]]
Recall [Figure 1.4]
[[1] - the XSLT created here (2) plugs in to the two-step validation process
]
Recall [Figure 5.1]
[[1] - all three documents on that diagram are shown here as instances being validated, the context value association files and the
external value list expressions
]
5.1 CVA for validation using Schematron
[> 5.2][< 5.0.2][^^][^^^]
5.1.1 CVA for validation using Schematron
[> 5.1.2][> 5.2][> 6.][< 5.0.2][^^][^^^]
The document structure and lexical constraints are already formalized as usable artefacts
[[1] - document schemas are the artefacts published by committees and communities to be used in the structure/lexical validation
process
[1] - a UBL customization is the published set of W3C schemas for a user community
[[2] - subsets the standardized business objects to requirements included in UBL
[2] - extends the standardized business objects for requirements not included in UBL
]]
The objective is to formalize the implementation guide between trading partners as usable artefacts
[[1] - "context/value association files" are the artefacts published by committees, communities and trading partners to be used in
the business/value validation process
[1] - an XML document expresses the association between document contexts and their associated controlled values
[1] - the files of declared agreed-upon requirements form part of the trading partner agreement
]
The formalized artefacts are exchanged and transformed into a programmatic script
[[1] - the requirements for business/value validation found in the context/value association file XML vocabulary are converted into
an executable Schematron schema
[1] - the Schematron schema implements the business/value validation as an executable process
[[2] - each trading partner may have a different implementation of Schematron based on their own system criteria
[[3] - e.g. XSLT 1 or XSLT 2 stylesheets
[3] - e.g. Python programming language
]]]
Stylesheets can make the information in the formalized artefacts presentable
[[1] - the context/value association file XML can be transformed into HTML for rendering purposes
]
Two or three inputs into the methodology's processes (shown on [Figure 1.5])
[[1] - expressing the association of document contexts and coded values ("3")
[[2] - using both absolute and relative XPath expressions, one can specify information items in many or in individual contexts
[2] - e.g. all contextual uses of <cbc:DocumentCurrencyCode> will use a limited set of currency values
[2] - the values used in UBL 2.0 are enumerated in the support package
[[3] - not included in the UBL 2.0 specification package
]][1] - expressing the coded values allowed to be used in possible contexts ("4")
[[2] - using genericode, one can specify sets of predetermined values and their meta data
[[3] - e.g. the set of currencies for countries engaged in cross-border transactions is limited to only the values "CAD" (Canadian Dollar) and "USD" (United States Dollar)
][2] - the UBL TC supplies the values used in UBL 2.0 for default validation for conformance to an arbitrary set of code lists
[[3] - found in the [http://docs.oasis-open.org/ubl/os-UBL-2.0/cl/] directory
]][1] - optionally expressing business rules related or unrelated to predetermined values ("5")
[[2] - using Schematron, one can specify arbitrary business rules about the content found in information items
[[3] - e.g. "the total value of the invoice cannot exceed $10,000 in the currency of the transaction"
][2] - the UBL TC has not yet published any business rules for UBL documents
[[3] - business rules are typically the purview of trading partners
[3] - customization designers may choose to specify business rules for arbitrary constraints
[[4] - e.g. absence of empty elements
[4] - e.g. string length of particular values
]]]]
One output of the methodology's processes
[[1] - the second-pass Schematron value validation (e.g. XSLT stylesheet) ("2")
[[2] - the UBL TC supplies a stylesheet used for UBL 2.0 default values:
[[3] - delivered as [http://docs.oasis-open.org/ubl/os-UBL-2.0/val/defaultCodeList.xsl]
]]]
5.1.2 Document context representation
[> 5.1.3][> 5.2][> 6.][< 5.1.1][^][^^][^^^]
XPath expressions are used to specify the context of information items in an XML document
[[1] - @attribute-name or rarely @namespace-prefix:attribute-name
[[2] - note that no attribute names in UBL are namespace-qualified
][1] - namespace-prefix:element-name or simply element-name
[[2] - note that all element names in UBL are namespace-qualified
][1] - parent/child or parent/@attribute
[[2] - used when the child is an immediate descendant of the parent
][1] - ancestor//descendant or ancestor//@attribute
[[2] - used when the descendant is at any depth below the ancestor
][1] - /document-element absolute address
[[2] - used to indicate the top of the XML document tree, starting a fully-qualified path to the item being addressed
][1] - one cannot readily determine available contexts just by looking at schemata
[[2] - a schema declaration shows only one level of children when following the UBL NDR
]]
Absolute (anchored) XPath address:
[[1] - the following are addressed completely from the document element to the target document context
]
[Example 5-1: 01 /po:Order/cac:TaxTotal/cbc:TaxAmount/@currencyID
02 /po:Order/cbc:DocumentCurrencyCode
03 /po:Order/cac:BuyerCustomerParty/cac:Party/cac:Address/
04 cbc:CountrySubentityCode
05 /po:Order/cac:SellerSupplierParty/cac:Party/cac:Address/
06 cbc:CountrySubentityCode
]
Relative (unanchored) XPath address without context:
[[1] - the following information items can occur in any context in the document
]
[Example 5-2: 01 @currencyID
02 cbc:DocumentCurrencyCode
03 cbc:CountrySubentityCode
]
Relative (unanchored) XPath address with "narrow" context:
[[1] - the following are addressing particular document contexts below an apex
]
[Example 5-3: 01 cac:BuyerCustomerParty/cac:Party/cac:Address/cbc:CountrySubentityCode
02 cac:SellerSupplierParty/cac:Party/cac:Address/cbc:CountrySubentityCode
]
Relative (unanchored) XPath address with "wide" context:
[[1] - the following are addressing all document contexts below an apex
]
[Example 5-4: 01 cac:BuyerCustomerParty//cbc:CountrySubentityCode
02 cac:SellerSupplierParty//cbc:CountrySubentityCode
]
Summary of contexts for UBL documents, distilled from UBL document models:
[[1] - delivered as part of the future UBL support package
[1] - contexts are minimally unique
[[2] - the indicates paths are as short as they can be while still being unique contexts
[2] - the XPath addresses in the context files have no injected white-space
]]
[Example 5-5: 01 Invoice: (58 uses of code list data types; 58 unique parents;
02 4580 unique contexts)
03
04 cbc:AccountTypeCodeType: (1 unique parent; 20 contexts;
05 extends udt:CodeType)
06 cbc:AccountTypeCode (20 contexts)
07 cac:InvoiceLine/cac:Price/cac:AllowanceCharge/cac:PaymentMeans/
08 cac:PayeeFinancialAccount/cbc:AccountTypeCode
09 cac:InvoiceLine/cac:Price/cac:AllowanceCharge/cac:PaymentMeans/
10 cac:PayerFinancialAccount/cbc:AccountTypeCode
11 ...
12 in:Invoice/cac:AllowanceCharge/cac:PaymentMeans/
13 cac:PayeeFinancialAccount/cbc:AccountTypeCode
14 in:Invoice/cac:AllowanceCharge/cac:PaymentMeans/
15 cac:PayerFinancialAccount/cbc:AccountTypeCode
16 ...
17
18 cbc:CountrySubentityCodeType: (1 unique parent; 370 contexts;
19 extends udt:CodeType)
20 cbc:CountrySubentityCode (370 contexts)
21 ...
22 cac:BuyerCustomerParty/cac:Party/cac:AgentParty/
23 cac:PhysicalLocation/cbc:CountrySubentityCode
24 cac:BuyerCustomerParty/cac:Party/
25 cac:PhysicalLocation/cbc:CountrySubentityCode
26 ...
27 cac:SellerSupplierParty/cac:Party/cac:AgentParty/
28 cac:PhysicalLocation/cbc:CountrySubentityCode
29 cac:SellerSupplierParty/cac:Party/
30 cac:PhysicalLocation/cbc:CountrySubentityCode
31 ...
]
In the above the report shows:
[[1] - in all of UBL there is only one parent of cbc:AccountTypeCodeType, that being cbc:AccountTypeCode and that there are 20 unique contexts in which cbc:AccountTypeCode is being used
[1] - there is only one parent of cbc:CountrySubentityCodeType, that being cbc:CountrySubentityCode and that there are 370 unique contexts in which cbc:CountrySubentityCode is being used
]
5.1.3 Context/value association specification
[> 5.1.4][> 5.2][> 6.][< 5.1.2][^][^^][^^^]
A code list context association file associates values with document contexts
[[1] - the methodology transforms an association file into a Schematron pattern
[[2] - suitable to be included into a master Schematron schema using <sch:include>
[2] - the Schematron pattern needs to be identified by a pattern name
][1] - the version= attribute, and <Annotation>/<Description> and <Title> elements are used only for documentary purposes
[1] - an association file may include other association files when generating the pattern
[[2] - the <Include> directive brings in other contexts and code lists
][1] - value lists are identified within an association file by an identifier using <ValueList>
[[2] - the uri= points to the actual code list enumeration genericode file
][1] - contexts refer to document information items by their XPath addressees using <Context>
[[2] - the values= points to one or more value lists by their internal identifiers
]]
[Figure 5.4: CVA file component relationships
A box titled "association.xml" has a pro-forma context/value association file as content as follows:
[Example 5-6: 01 <ValueListConstraints id="..." name="..."
02 version="...">
03 <Annotation>
04 <Description>...</Description>
05 <Title>...</Title>
06 <Include uri="..."/>
07
08 <ValueLists>
09 <ValueList xml:id="..." uri="...gc">
10 <Identification>...</Identification>
11 </ValueList>
12 <ValueList xml:id="..." uri="...gc"/>
13 </ValueLists>
14
15 <Contexts>
16 <Context values="..." scope="..." item="...">
17 <Message>...</Message>
18 </Context>
19 <Context values="..." address="..." item="..."/>
20 </Contexts>
21 </ValueListConstraints>
]
From the id="..." attribute is an arrow to the start of the association file.
From a "SCH" labeled triangle titled "Master Schematron schema", an arrow labeled "sch:include pattern name" points to the name="..." attribute.
From the uri="..." attribute an arrow points to an "XML" labeled triangle titled "Another association file".
From the values="..." attribute is an arrow to the xml:id="..." attribute.
From the uri="...gc" attribute is an arrow to a "GC" labeled triangle titled "Value list enumerations".
From the address="..." attribute is an arrow labeled "XPath addresses" to a "XML" labeled triangle titled "Instances being validated".
]
These files can be used as part of a formal trading partner agreement
[[1] - unambiguous specification of value constraints
]
5.1.4 Association specification, extension and restriction
[> 5.1.5][> 5.2][> 6.][< 5.1.3][^][^^][^^^]
The association implements simple, extended or restricted value lists
[[1] - the diagram illustrates three associations, one of each kind
[1] - simple enumeration association: A
[[2] - the one association points to a single external value list
][1] - extending enumeration association: B extended by C
[[2] - the one association simultaneously points to both B and C value lists
[2] - similarly, one association can point to the union of multiple unrelated lists if the combined set of values is required
][1] - restricting enumeration association: D' restriction of D
[[2] - the one association points to the reduced value list D'
[2] - the reduced list is treated as the complete list by masquerading D' as the complete list D
[2] - the meta data of D is embedded inside of the value list declaration for D'
]]
[Figure 5.5: Extension and restriction using context/value association
The diagram reflects the relationships described in the prose.
]
Consider the situation where one wishes to associate for a given document context the combination of a restriction of another
published list plus a set of extra codes not included in the published list:
[[1] - the diagram illustrates extending a restricted list
[1] - restricting enumeration association: D' restriction of D
[[2] - the one association points to the reduced value list D'
[2] - the reduced list is treated as the complete list by masquerading D' as the complete list D
[2] - the meta data of D is embedded inside of the value list declaration for D'
][1] - extending enumeration association: D' extended by C
[[2] - the one association simultaneously points to both D' and C value lists
]]
As a real-world example, consider transportation status codes:
[[1] - UBL has published a set of transportation status codes
[[2] - (in the drawing this would be list D)
][1] - a user doesn't want to use all of the published codes, so they create their own restricted list
[[2] - (in the drawing this would be list D')
][1] - the user has a set of additional status codes not published by UBL
[[2] - (in the drawing this would be list C)
][1] - the association combines the subset list D' of published codes plus the extended list C of additional codes
]
[Figure 5.6: Example context/value association
The diagram reflects the relationships described in the prose.
]
5.1.5 Context/value pro forma associations
[> 5.1.6][> 5.2][> 6.][< 5.1.4][^][^^][^^^]
Pro forma example of context associations specified across all documents:
[[1] - recall the diagram illustrating the relationships on [Figure 5.4]
[1] - note how all of the contexts are specified with relative XPath addresses
]
[Example 5-7: 01 <?xml version="1.0" encoding="US-ASCII"?>
02 <ValueListConstraints ... namespaces for XPath addresses ...
03 xmlns="http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/
04 cd2-1.0/"
05 id="urn:x-optional-unique-identifier-for-external-referencing"
06 name="required-unique-name-token-for-internal-referencing"
07 version="Revision: 27b - 2006-11-23 15:00z">
08 <Annotation>
09 <Description>
10 This is included for illustrative purposes.
11 </Description>
12 </Annotation>
13
14 <Title>
15 This is the main context/value association file for project X.
16 </Title>
17
18 <Include uri="other-assoc-file-1.cva">
19 <Annotation>
20 <Description>
21 Incorporating information from another file.
22 </Description>
23 </Annotation>
24 </Include>
25 <Include uri="other-assoc-file-2.cva">
26 <Annotation>
27 <Description>
28 Incorporating information from yet another file.
29 </Description>
30 </Annotation>
31 </Include>
]
(pro forma example continued on the next page)
The above identifies the context/value association file itself and the component pieces that are included
[[1] - the optional id= is used for identifying this file from outside of this file
[[2] - perhaps in cataloguing artefacts used in a transaction
][1] - the mandatory name= is used to name the Schematron pattern that is included into the master Schematron schema used for validation
[1] - the version=, <Description> and <Title> are documentary
]
[Example 5-8: 01 <ValueLists>
02 <Annotation>
03 <Description>
04 All the lists available to be used.
05 </Description>
06 </Annotation>
07 <ValueList xml:id="a1" uri="enumeration1.gc">
08 <Annotation>
09 <Description>
10 A set of external values with no masquerading meta data.
11 </Description>
12 </Annotation>
13 </ValueList>
14 <ValueList xml:id="a2" uri="enumeration2.gc">
15 <Annotation>
16 <Description>
17 A set of external values with masquerading version meta data.
18 </Description>
19 </Annotation>
20 <Identification>
21 <Version>1.4</Version>
22 </Identification>
23 </ValueList>
24 <ValueList xml:id="a3" uri="enumeration3.gc">
25 <Annotation>
26 <Description>
27 Another set of external values with no masquerading meta data.
28 </Description>
29 </Annotation>
30 </ValueList>
31 </ValueLists>
]
[Example 5-9: 01 <Contexts>
02 <Annotation>
03 <Description>
04 All the contexts using lists.
05 </Description>
06 </Annotation>
07 <Context item="@item-a" values="a2">
08 <Annotation>
09 <Description>
10 Associating a set of values with all item-a= attributes.
11 </Description>
12 </Annotation>
13 </Context>
14 <Context item="item-b" scope="context-b1" values="a1 a3">
15 <Annotation>
16 <Description>
17 Associating two sets of values with all item-b descendants
18 of the context-b1 element.
19 </Description>
20 </Annotation>
21 </Context>
22 <Context item="item-b" address="context-b2/item-b"
23 values="a3" mark="characteristic-1">
24 <Annotation>
25 <Description>
26 Associating a set of values with item-b children of the
27 context-b2 element.
28 </Description>
29 </Annotation>
30 </Context>
31 </Contexts>
]
This example checks all item-a attributes regardless of document context
[[1] - also regardless of document type
[1] - no use of scope= or address= attributes
]
Two different ways in this example to handle item-b attributes
[[1] - when a child of the context-b2 element, the values of list enumeration3.gc apply
[[2] - the use of address= is important if the item-b element has more descendent contexts of context-b2 than just being a child
[2] - note the inclusion of the item-b name in the address
][1] - when a descendant or child of the context-b1 element, the values of both lists enumeration1.gc and enumeration3.gc apply
[[2] - the use of scope= specifies all item-b elements in descendent contexts of context-b1
[2] - note the exclusion of the item-b name in the address
][1] - the prioritized order of the last two implies that the item-b child of context-b2 that is also a descendant of context-b1 will be treated as a child of context-b2 and not as a descendant of context-b1
]
Pro forma example of context associations specified for different documents:
[[1] - recall the diagram illustrating the relationships on [Figure 5.4]
[1] - note the use of the absolute XPath addresses "/po:Order" and "/in:Invoice" in the contexts
]
[Example 5-10: 01 <?xml version="1.0" encoding="US-ASCII"?>
02 <ValueListConstraints xmlns="http://docs.oasis-open.org/codelist/ns/
03 ContextValueAssociation/cd2-1.0/"
04 xmlns:in="urn:oasis:names:specification:ubl:schema:xsd:Invoice-1.0"
05 xmlns:po="urn:oasis:names:specification:ubl:schema:xsd:Order-1.0"
06 name="code-list-rules">
07 <ValueLists>
08 <ValueList xml:id="a1" uri="enumeration1.gc"/>
09 <ValueList xml:id="a2" uri="enumeration2.gc"/>
10 <ValueList xml:id="a3" uri="enumeration3.gc"/>
11 </ValueLists>
12 <Contexts>
13 <Context item="@item-a" values="a2"/>
14 <Context item="@item-b" scope="/po:Order//context-b1"
15 values="a1 a3"/>
16 <Context item="@item-b" scope="/in:Invoice//context-b1"
17 values="a3" mark="characteristic-1"/>
18 </Contexts>
19 </ValueListConstraints>
]
Two different ways in the example above to handle item-b elements:
[[1] - when a descendant of a context-b1 element in a purchase order document two value lists apply
[1] - when a descendant of a context-b1 element in an invoice document only one value list applies
]
5.1.6 Context/value validation implementation
[> 5.2][> 6.][< 5.1.5][^][^^][^^^]
Two separate implementations of running code are used to effect the result:
[[1] - the "Methodology Stylesheets" box represents the CVA XSLT stylesheets supplied with this methodology to transform context/value
association files into a Schematron pattern
[1] - the "Schematron" box represents the particular implementation of Schematron being deployed by a user of this methodology
[[2] - the methodology package supplies an XSLT implementation of Schematron that exits with a non-zero return code when it reports
violations to the standard error port in a simple text format
[2] - alternative implementations of Schematron are publicly-available from [http://www.Schematron.com] including versions that report violations in a rich XML vocabulary for subsequent downstream processing
]]
[Figure 5.7: CVA implementation in Schematron
Three sets of triangles feed a box labeled "XSLT Process" at the left of a large diagram. The single "XML" labeled triangle
titled Code List Context Associations" and identified with a circled "3" is one of the three sets. A set of "GC" labeled triangles
titled "External Code List Expressions" and identified with a circled "4" is another. A set of "XSLT" labeled triangle titled
"Association Stylesheet and Imported Fragments" is the third. This third one lists the following fragments, with the first
fragment in boldface font:
]
Recall [Figure 1.5]
Recall [Figure 1.4]
Context/value associations and external code list expressions are converted to Schematron
[[1] - Crane-UBL-genericode2Schematron.xsl (UBL elements and meta data)
[1] - Crane-NM-genericode2Schematron.xsl (no meta data)
]
Schematron patterns assembled into a complete Schematron schema
[[1] - schematron-ISO-assembly.xsl
]
Schematron schema translated into an XSLT stylesheet
[[1] - Message-Schematron-terminator.xsl
[[2] - a wrapper of the iso_schematron_skeleton.xsl implementation
]]
[Figure 5.8: CVA implementation in Schematron and XSLT
Three sets of triangles feed a box labeled "XSLT Process" at the left of a large diagram. The single "XML" labeled triangle
titled Code List Context Associations" and identified with a circled "3" is one of the three sets. A set of "GC" labeled triangles
titled "External Code List Expressions" and identified with a circled "4" is another. A set of "XSLT" labeled triangle titled
"Association Stylesheet and Imported Fragments" is the third. This third one lists the following fragments, with the first
fragment in boldface font:
[[1] - UBL-genericode2Schematron.xsl
[1] - {documentModel}-{externalFormat}2Schematron.xsl
[1] - {documentModel}-Metadata.xsl
[1] - {externalFormat}-CodeList.xsl
[1] - Constraints2Schematron.xsl
]
The output from the XSLT process is an "SCH" labeled triangle titled "Code List Pattern". This is input to a set of "SCH"
labeled triangles titled "Business Rules" and identified with a circled "5". These are input to another box labeled "XSLT
Process".
The other input to this box is an "XSLT" labeled triangle titled "Schematron-ISO-assembly.xsl", and the output is an "SCH" labeled triangle titled "Validation Rules". This is input to yet another box labeled "XSLT Process".
The other input to this box is an "XSLT" labeled triangle titled "Schematron-ISO-incomplete-text.xsl".
All of the shapes to this point are above a bracket titled "Preparation". The remaining shapes are all above a bracket titled
"Processing".
The output from the last process is an "XSLT" labeled triangle titled "Assertion Validation Stylesheet" and identified with
a circled "2". This is input to still yet another box labeled "XSLT Process".
The remaining inputs to this last XSLT process is a set of "XML" labeled triangles titled "Document Instances Being Validated".
The outputs from this last XSLT process is a set of "Report" labeled parallelograms titled "Validation Reports".
]
Recall [Figure 1.5]
Recall [Figure 1.4]
5.2 Code list methodology example
[> 5.3][< 5.1.6][^^][^^^]
5.2.1 Example code list validation scenarios
[> 5.2.2][> 5.3][> 6.][< 5.1.6][^^][^^^]
Recall the example scenario where two trading partners agree to exchange an order
[[1] - one is in Canada and the other is in the US
[1] - currency codes must be limited to either US dollars or Canadian dollars
[1] - the buyer may be either Canadian- or US-based
[[2] - this limits the country sub-entity code of the buyer to be either provinces or states
][1] - the seller can only be US-based
[[2] - this limits the country sub-entity code of the seller to be only states
][1] - the payment means supplements the available UBL values for payment means
[[2] - all of the UBL-standardized values can be used
[2] - the value "SHP" can be used to represent "payment by the exchange of sheep"
]]
A second (related) scenario includes a business rule
[[1] - same code list constraints, but the total value of the order must be less than $10,000 of the order's currency
[[2] - the cbc:toBePaidAmount for the order must be less than 10000.
]]
The scenario/ directory included with the methodology documentation has the files illustrating the two scenarios
[[1] - instances of the UBL Order document to be validated for the use of coded values:
[[2] - order-test-good*.xml and order-test-bad*.xml
][1] - codes-only-constraints.sch
[[2] - a Schematron schema that only checks for the coded values
][1] - total-constraints.sch
[[2] - a Schematron schema that checks for both the coded values and the business rule
][1] - both Schematron schemas rely on an external Schematron pattern that isn't included
[[2] - order-constraints.sch needs to be synthesized to test the coded value limitations
]]
5.2.2 Code list methodology example
[> 5.2.3][> 5.3][> 6.][< 5.2.1][^][^^][^^^]
Complete code list association file for the example scenario
[[1] - this associates the limited currency list and the province and state lists according to the requirements in the illustrative
scenario
]
[Example 5-11: 01 <?xml version="1.0" encoding="US-ASCII"?>
02 <ValueListConstraints xmlns="http://docs.oasis-open.org/codelist/ns/
03 ContextValueAssociation/cd2-1.0/"
04 xmlns:cbc="urn:oasis:...:CommonBasicComponents-2"
05 xmlns:cac="urn:oasis:...:CommonAggregateComponents-2"
06 xmlns:sch="http://purl.oclc.org/dsdl/schematron"
07 id="urn:x-illustration"
08 name="code-list-rules"
09 version="$Id: order-constraints.cva,v 1.8 2008/11/11 ...">
10
11 <Annotation>
12 <Description>
13 This is an illustrative example of all of the features of specifying the
14 context/value constraints that one can express for XML documents.
15
16 The validation requirements for this contrived scenario are as follows:
17 - the UN/CEFACT currency code list is restricted to be
18 only Canadian and US dollars
19 - the seller must be in the US
20 - the buyer may be in either Canada or the US
21 - the definition for Payment Means is extended to include
22 both UBL definitions and additional definitions
23 </Description>
24 </Annotation>
25
26 <Title>
27 Illustration of code list constraints - order-constraints.cva
28 </Title>
]
(association file continued on next page)
Of note above:
[[1] - the name of the pattern generated is "code-list-rules"
[1] - the title information is meant to be terse
[1] - the identification is meant to be simple text and terse
[1] - the description information may be detailed and include rich markup (not shown in this example)
]
[Example 5-12: 01 <!--list all of the genericode expressions of agreed-upon code list
02 value enumerations-->
03 <ValueLists>
04 <ValueList xml:id="currency" uri="CAUS_CurrencyCode.gc">
05 <Annotation>
06 <Description>
07 Restricted to only Canadian and US dollars.
08 </Description>
09 </Annotation>
10 <Identification>
11 <ShortName>CurrencyCode</ShortName>
12 <LongName>Currency</LongName>
13 <LongName Identifier='listID'>ISO 4217 Alpha</LongName>
14 <Version>2001</Version>
15 <CanonicalUri>urn:un:unece:uncefact:codelist:specification:
16 54217</CanonicalUri>
17 <CanonicalVersionUri>urn:un:unece:uncefact:codelist:
18 specification:54217:2001</CanonicalVersionUri>
19 <Agency>
20 <LongName>United Nations Economic Commission for
21 Europe</LongName>
22 <Identifier>6</Identifier>
23 </Agency>
24 </Identification>
25 </ValueList>
26 <ValueList xml:id="states" uri="US_CountrySubentityCode.gc">
27 <Annotation>
28 <Description>
29 List of US states
30 </Description>
31 </Annotation>
32 </ValueList>
33 <ValueList xml:id="provinces" uri="CA_CountrySubentityCode.gc">
34 <Annotation>
35 <Description>
36 List of Canadian provinces
37 </Description>
38 </Annotation>
39 </ValueList>
]
(association file continued on next page)
Of note above:
[[1] - the declaration for the external restricted currency code list uses the masquerading meta data of the complete code list
]
[Example 5-13: 01 <ValueList xml:id="tax-ids" uri="TaxIdentifier.gc" key="codeKey">
02 <Annotation>
03 <Description>
04 List of tax type identifiers
05 </Description>
06 </Annotation>
07 </ValueList>
08 <ValueList xml:id="payments" uri="UBL_PaymentMeansCode-2.0.gc">
09 <Annotation>
10 <Description>
11 Copied from the UBL 2.0 suite:
12 http://docs.oasis-open.org/ubl/cs-UBL-2.0/
13 </Description>
14 </Annotation>
15 </ValueList>
16 <ValueList xml:id="additional_payments"
17 uri="Additional_PaymentMeansCode.gc">
18 <Annotation>
19 <Description>
20 An extra set of possible payment means.
21 </Description>
22 </Annotation>
23 </ValueList>
24 </ValueLists>
]
(association file continued on next page)
Of note above:
[[1] - the UBL payment means code list is unchanged and used in its entirety
[1] - an extended list of payment means codes is also declared ready to be used in the association declaration
]
[Example 5-14: 01 <!--list all of the contexts in which the value enumerations are used;
02 where two or more contexts might match a given node in the input,
03 list them here in order of most-important to least important match-->
04 <Contexts>
05 <Context item="@currencyID" values="currency">
06 <Annotation>
07 <Description>
08 All currencies are restricted to only Canadian and US dollars.
09 </Description>
10 </Annotation>
11 </Context>
12 <Context item="cbc:CountrySubentityCode"
13 scope="cac:BuyerCustomerParty"
14 values="provinces states">
15 <Annotation>
16 <Description>
17 The buyer can be in either Canada or the US.
18 </Description>
19 </Annotation>
20 <Message>Invalid province or state '<sch:value-of select="."/>'
21 for buyer "<sch:value-of select="ancestor::cac:BuyerCustomerParty/
22 cac:Party/cac:PartyName/cbc:Name"/>"</Message>
23 </Context>
24 <Context item="cbc:CountrySubentityCode"
25 scope="cac:SellerSupplierParty"
26 values="states">
27 <Annotation>
28 <Description>
29 The seller can only be in the US.
30 </Description>
31 </Annotation>
32 <Message>Invalid state '<sch:value-of select="."/>' for seller
33 "<sch:value-of select="ancestor::cac:SellerSupplierParty/cac:Party/
34 cac:PartyName/cbc:Name"/>"</Message>
35 </Context>
]
(association file continued on next page)
Of note above:
[[1] - the first context utilizes default violation reporting
[1] - the second and third contexts specify a custom Schematron error message used in the reporting of the value violation
]
[Example 5-15: 01 <Context item="cbc:ID" address="cac:TaxCategory/cbc:ID"
02 values="tax-ids">
03 <Annotation>
04 <Description>
05 Limit the recognized tax identifiers
06 </Description>
07 </Annotation>
08 </Context>
09 <Context item="cbc:PaymentMeansCode" mark="money"
10 values="payments additional_payments">
11 <Annotation>
12 <Description>
13 The payments can be by either standard or supplemental means.
14 </Description>
15 </Annotation>
16 </Context>
17 </Contexts>
18 </ValueListConstraints>
]
Of note above:
[[1] - the fourth and fifth contexts utilize default violation reporting
[1] - the last association shows how the UBL payment means is extended by the additional payment means
[1] - the last association is marked as being related to a money issue, perhaps distinguishing this in downstream processing as
being a more or less important issue
]
Sample master referencing only the validation of select code lists
[[1] - codes-only-constraints.sch
[1] - used to pull in code lists
[1] - no reference to other business rules
[1] - note the need in this master schema to use Schematron declarations for the namespaces that are used within the included Schematron
pattern
[[2] - the methodology stylesheets that create the included pattern file incorporate a copy of these namespace declarations in the
comments of the included file for ease of copy/paste into the master schema
]]
[Example 5-16: 01 <schema xmlns="http://purl.oclc.org/dsdl/schematron">
02 <title>Code list value assertions</title>
03 <ns prefix="cbc" uri="urn:oasis:...:CommonBasicComponents-2"/>
04 <ns prefix="cac" uri="urn:oasis:...:CommonAggregateComponents-2"/>
05 <include href="order-constraints.sch"/>
06 </schema>
]
When no pattern is explicitly engaged, all patterns are engaged
[[1] - from all embedded patterns and included patterns
]
Sample master that includes trading partner business rules with the select code lists
[[1] - total-constraints.sch
[1] - used to pull in code lists
[1] - includes reference to other business rules
]
[Example 5-17: 01 <?xml version="1.0" encoding="UTF-8"?>
02 <schema xmlns="http://purl.oclc.org/dsdl/schematron"
03 defaultPhase="only-phase">
04 <title>Business rules for maximum total value</title>
05 <ns prefix="cbc" uri="urn:oasis:...:CommonBasicComponents-2"/>
06 <ns prefix="cac" uri="urn:oasis:...:CommonAggregateComponents-2"/>
07 <phase id="only-phase">
08 <active pattern="code-list-rules"/>
09 <active pattern="total-limit"/>
10 </phase>
11 <include href="total-limit-constraint.sch"/>
12 <include href="order-constraints.sch"/>
13 </schema>
]
Schematron provides for invocation-time specification of phase to run
[[1] - each phase points to the active patterns to be engaged
[1] - phases are not needed if all patterns are to be engaged
]
Sample trading partner business rules
[[1] - total-limit-constraints.sch
[1] - expresses arbitrary constraints on the information
]
[Example 5-18: 01 <?xml version="1.0" encoding="UTF-8"?>
02 <pattern xmlns="http://purl.oclc.org/dsdl/schematron" id="total-limit">
03 <rule context="cbc:ToBePaidAmount">
04 <assert test=". < 10000">Total amount '<value-of select="."/>'
05 cannot be $10,000 or more</assert>
06 </rule>
07 </pattern>
]
Example business rule limits the total to be "10,000" or less
[[1] - note there is no indication of currency, though that could be added as a co-constraint
]
Transcript of test run of second pass validation using the created pattern in both scenarios
[Example 5-19: 01 Precondition validation...
02
03 Validating partner-agreed constraints...
04 w3cschema ContextValueAssociation.xsd order-constraints.cva
05 Attempting validating, namespace-aware parse
06 Parse succeeded (0.521) with no errors and no warnings.
07
08 Validating code lists...
09 w3cschema genericode.xsd CA_CountrySubentityCode.gc
10 Attempting validating, namespace-aware parse
11 Parse succeeded (0.270) with no errors and no warnings.
12 w3cschema genericode.xsd US_CountrySubentityCode.gc
13 Attempting validating, namespace-aware parse
14 Parse succeeded (0.330) with no errors and no warnings.
15 w3cschema genericode.xsd CAUS_CurrencyCode.gc
16 Attempting validating, namespace-aware parse
17 Parse succeeded (0.260) with no errors and no warnings.
18 w3cschema genericode.xsd TaxIdentifier.gc
19 Attempting validating, namespace-aware parse
20 Parse succeeded (0.260) with no errors and no warnings.
21 w3cschema genericode.xsd Additional_PaymentMeansCode.gc
22 Attempting validating, namespace-aware parse
23 Parse succeeded (0.270) with no errors and no warnings.
24
25 Preparing code list rules...
26
27 Translating partner-agreed constraints into Schematron rules...
28 xslt order-constraints.cva ..\utility\Crane-UBL-genericode2Schematron.xsl
29 order-constraints.sch
]
Of note above:
[[1] - note that the first pass schema structure validation is not included in this test script or transcript
[1] - without first pass schema structure validation it is possible to get a "false positive" when information items are not in
their correct places as expected for the contexts
[1] - the order-constraints.cva file is translated into the order-constraints.sch file
]
[Example 5-20: 01 Test 1 - standalone code list rules
02
03 Assembling rules into a Schematron schema...
04 xslt codes-only-constraints.sch ..\utility\iso_schematron_assembly.xsl
05 order-codes-only.sch
06
07 Translating Schematron into validation stylesheet...
08 xslt order-codes-only.sch ..\utility\Message-Schematron-terminator.xsl
09 order-codes-only.xsl
10
11 Document validation...
12
13 Testing order-test-good1.xml...
14 xslt order-test-good1.xml order-codes-only.xsl nul "2>test-constraints.txt"
15 Result: 0
16
17
18 Testing order-test-good2.xml...
19 xslt order-test-good2.xml order-codes-only.xsl nul "2>test-constraints.txt"
20 Result: 0
]
Of note above:
[[1] - the "codes-only-constraints.sch" Schematron schema is assembled into the "order-codes-only.sch" Schematron schema, which in turn is translate into the "order-codes-only.xsl" XSLT 1 stylesheet
[1] - the two XML instances "order-test-good1.xml" and "order-test-good2.xml" both have no violations of the context/value associations, so each validation process returns a zero return code
]
[Example 5-21: 01 Testing order-test-bad1.xml...
02 xslt order-test-bad1.xml order-codes-only.xsl nul "2>test-constraints.txt"
03 Result: 1
04 Value supplied 'UYU' is unacceptable for values identified
05 by 'currency' in the context '@currencyID':
06 /Order/cac:TaxTotal[1]/cbc:TaxAmount[1]/@currencyID
07
08 Processing terminated by xsl:message at line 143
]
Sample value violation 1: a bad currency value
[[1] - note the error message is the built-in wording
[[2] - coded in the preparation stylesheets
][1] - the currency code "UYU" for "Uruguayan Peso" is adjacent to USD in the currency code list
[1] - in this scenario, perhaps the author of the document missed the choice for US dollars by accidentally picking the peso indicator
[1] - a non-zero return code indicates that there is a context/value association violation
[1] - the portion of the example instance with the error is below
]
[Example 5-22: 01 ...
02 <cac:TaxTotal>
03 <cbc:TaxAmount currencyID="UYU">15.00</cbc:TaxAmount>
04 <cbc:TaxEvidenceIndicator>false</cbc:TaxEvidenceIndicator>
05 <cac:TaxSubTotal>
06 <cbc:TaxableAmount currencyID="USD">100.00</cbc:TaxableAmount>
07 <cbc:TaxAmount currencyID="USD">15.00</cbc:TaxAmount>
08 <cac:TaxCategory>
09 <cbc:ID>Z</cbc:ID>
10 <cbc:Percent>15</cbc:Percent>
11 <cac:TaxScheme>
12 <cbc:ID>Provincial Tax</cbc:ID>
13 </cac:TaxScheme>
14 </cac:TaxCategory>
15 </cac:TaxSubTotal>
16 </cac:TaxTotal>
17 ...
]
[Example 5-23: 01 Testing order-test-bad2.xml...
02 xslt order-test-bad2.xml order-codes-only.xsl nul "2>test-constraints.txt"
03 Result: 1
04 Invalid province or state 'ON' for buyer "Elliot's Electronics":
05 /Order/cac:BuyerCustomerParty[1]/cac:Party[1]/cac:Address[1]/
06 cbc:CountrySubentityCode[1]
07
08 Processing terminated by xsl:message at line 143
]
Sample value violation 2: unexpected version of province code list
[[1] - note the error message is custom wording supplied in the CVA file ([Example 5-14])
[[2] - message includes cited content
][1] - the country sub-entity code "ON" for "Ontario" is correct, but the instance states the value "ON" is from the list version "1"
[1] - the code list against which coded values are being checked is version "2"
[[2] - see [Example 3-3] for the genericode file for provinces
][1] - one cannot assume that the code for a particular version of a list has the same semantic for that code in a different version
of the list
[1] - the portion of the example instance with the error is below
]
[Example 5-24: 01 <cac:BuyerCustomerParty>
02 ...
03 <cac:Party>
04 <cac:PartyName>
05 <cbc:Name>Elliot's Electronics</cbc:Name>
06 </cac:PartyName>
07 <cac:Address>
08 <cbc:StreetName>Yonge St</cbc:StreetName>
09 <cbc:BuildingNumber>100</cbc:BuildingNumber>
10 <cbc:CityName>Toronto</cbc:CityName>
11 <cbc:PostalZone>M0H-0M0</cbc:PostalZone>
12 <cbc:CountrySubentityCode
13 listVersionID="1">ON</cbc:CountrySubentityCode>
14 </cac:Address>
15 <cac:Contact>
16 <cbc:Name>George Tirebiter</cbc:Name>
17 </cac:Contact>
18 </cac:Party>
19 ...
]
[Example 5-25: 01 Testing order-test-bad3.xml...
02 xslt order-test-bad3.xml order-codes-only.xsl nul "2>test-constraints.txt"
03 Result: 1
04 Invalid state 'ON' for seller "Elliot's Electronics":
05 /Order/cac:SellerSupplierParty[1]/cac:Party[1]/
06 cac:Address[1]/cbc:CountrySubentityCode[1]
07
08 Processing terminated by xsl:message at line 143
]
Sample value violation 3: bad country sub-entity code for seller
[[1] - note all error messages citing XPath addresses use the authored prefixes
[[2] - in this instance the element Order is using the default namespace, so has no prefix
][1] - the seller's country sub-entity code cannot be a Canadian province, even if the version of the code is correct according to
the genericode file, because the genericode file is not referenced for this context
[1] - cbc:ToBePaidAmount is in error missing the ".", thus it is too large
[1] - the portion of the example instance with the error is below
]
[Example 5-26: 01 ...
02 <cac:SellerSupplierParty>
03 ...
04 <cac:Address>
05 <cbc:StreetName>Yonge St</cbc:StreetName>
06 <cbc:BuildingNumber>100</cbc:BuildingNumber>
07 <cbc:CityName>Toronto</cbc:CityName>
08 <cbc:PostalZone>M0H-0M0</cbc:PostalZone>
09 <cbc:CountrySubentityCode listVersionID="2">ON
10 </cbc:CountrySubentityCode>
11 </cac:Address>
12 ...
13 </cac:Party>
14 </cac:SellerSupplierParty>
15 ...
16 <cac:LegalTotal>
17 <cbc:LineExtensionAmount
18 currencyID="USD">100.00</cbc:LineExtensionAmount>
19 <cbc:TaxExclusiveAmount
20 currencyID="USD">100.00</cbc:TaxExclusiveAmount>
21 <cbc:TaxInclusiveAmount
22 currencyID="USD">115.00</cbc:TaxInclusiveAmount>
23 <cbc:ToBePaidAmount
24 currencyID="USD">11500</cbc:ToBePaidAmount>
25 </cac:LegalTotal>
]
[Example 5-27: 01 Test 2 - with business rules
02
03 Assembling rules into a Schematron schema...
04 xslt total-constraints.sch ..\utility\iso_schematron_assembly.xsl
05 order-codes-total.sch
06
07 Translating Schematron into validation stylesheet...
08 xslt order-codes-total.sch ..\utility\Message-Schematron-terminator.xsl
09 order-codes-total.xsl
10
11 Document validation...
12
13 Testing order-test-bad3.xml...
14 xslt order-test-bad3.xml order-codes-total.xsl nul "2>test-constraints.txt"
15 Result: 1
16 Total amount '11500' cannot be $10,000 or more:
17 /Order/cac:LegalTotal[1]/cbc:ToBePaidAmount[1]
18 Invalid state 'ON' for seller "Elliot's Electronics": /Order/
19 cac:SellerSupplierParty[1]/cac:Party[1]/cac:Address[1]/
20 cbc:CountrySubentityCode[1]
21
22 Processing terminated by xsl:message at line 144
]
Of note above:
[[1] - the "total-constraints.sch" Schematron schema is assembled into the "order-codes-total.sch" Schematron schema, which in turn is translate into the "order-codes-total.xsl" XSLT 1 stylesheet
]
Sample value violations 4: bad country sub-entity code for seller and bad business rule for total
[[1] - the XML instance tested has two violations, one a value list violation and the other a business rule violation, and the stylesheet
returns a non-zero return code to indicate there is a problem
]
5.2.3 Example combination of restriction and extension
[> 5.3][> 6.][< 5.2.2][^][^^][^^^]
Consider the scenario of needing to extend a restricted subset of UBL transportation status codes
[[1] - UBL lists 329 different transportation codes from UN/ECE Recommendation 24
[1] - typically only a subset of standardized values are needed
[[2] - requires the UBL code list to be subset into a custom restricted list
][1] - in this scenario some non-standardized values are needed
[[2] - requires the additional codes to be put into an extension list
]]
For interoperability, whenever a UBL standardized code is used, UBL meta data is used
[[1] - this ensures that all applications geared for standardized UBL support will support a value specified with the proper UBL
meta data
]
For proper identification additional codes should have non-UBL meta data
[[1] - this ensures there is no ambiguity between a future version of the UBL list and an additional code specified by trading partners
[1] - if the value doesn't specify meta data then the an application would probably interpret the value as being a UBL-standardized
value
]
Scenario files found in the samp/transport/ subdirectory
Step 1: work from original complete list in UBL-TransportationStatusCode-2.0.gc
[[1] - obtain the standardized UBL TransportationStatusCode genericode file containing the complete suite of status codes
]
[Example 5-28: 01 <gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
02 <Identification>
03 <ShortName>TransportationStatusCode</ShortName>
04 <LongName xml:lang="en">Transportation Status</LongName>
05 <LongName Identifier="listID">UN/ECE rec 24</LongName>
06 <Version>Third Revision</Version>
07 <CanonicalUri>urn:oasis:names:specification:ubl:codelist:gc:
08 TransportationStatusCode</CanonicalUri>
09 <CanonicalVersionUri>urn:oasis:names:specification:ubl:codelist:gc:
10 TransportationStatusCode-2.0</CanonicalVersionUri>
11 <LocationUri>http://docs.oasis-open.org/ubl/os-ubl-2.0/cl/gc/
12 default/TransportationStatusCode-2.0.gc</LocationUri>
13 <Agency>
14 <LongName xml:lang="en">United Nations Economic Commission for
15 Europe</LongName>
16 <Identifier>6</Identifier>
17 </Agency>
18 </Identification>
19 ...
20 <SimpleCodeList>
21 <Row>
22 <Value ColumnRef="code">
23 <SimpleValue>1</SimpleValue>
24 </Value>
25 <Value ColumnRef="name">
26 <SimpleValue>Arrival, completed</SimpleValue>
27 </Value>
28 </Row>
29 <Row>
30 <Value ColumnRef="code">
31 <SimpleValue>2</SimpleValue>
32 </Value>
33 <Value ColumnRef="name">
34 <SimpleValue>Loading, authorized</SimpleValue>
35 </Value>
36 </Row>
37 ...
38 </SimpleCodeList>
39 </gc:CodeList>
]
Step 2: create reduced list My_TransportationStatusCodes.gc
[[1] - create a reduced list with only the standardized codes desired from the full list
[1] - use meta data that is different from the standardized meta data because this new list is, in fact, not the original complete
list, and so should not be identified as the complete list
]
[Example 5-29: 01 <gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
02 <Identification>
03 <ShortName>My_TransportationStatusCode</ShortName>
04 <LongName xml:lang="en">Abbreviated Transportation Status</LongName>
05 <Version>1</Version>
06 <CanonicalUri>urn:x-company:codes:gc:status</CanonicalUri>
07 <CanonicalVersionUri>urn:x-company:codes:gc:status-1
08 </CanonicalVersionUri>
09 </Identification>
10 ...
11 <SimpleCodeList>
12 <Row>
13 <Value ColumnRef="code">
14 <SimpleValue>1</SimpleValue>
15 </Value>
16 <Value ColumnRef="name">
17 <SimpleValue>Arrival, completed</SimpleValue>
18 </Value>
19 </Row>
20 <Row>
21 <Value ColumnRef="code">
22 <SimpleValue>5</SimpleValue>
23 </Value>
24 <Value ColumnRef="name">
25 <SimpleValue>Process, begun</SimpleValue>
26 </Value>
27 </Row>
28 <Row>
29 <Value ColumnRef="code">
30 <SimpleValue>49</SimpleValue>
31 </Value>
32 <Value ColumnRef="name">
33 <SimpleValue>Lost</SimpleValue>
34 </Value>
35 </Row>
36 </SimpleCodeList>
37 </gc:CodeList>
]
Step 3: create extension to values as standalone list Additional_TransportationStatusCodes.gc
[[1] - create a list of the additional codes that are not standardized
[1] - use meta data that identifies this new list
]
[Example 5-30: 01 <gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
02 <Identification>
03 <ShortName>Additional_TransportationStatusCode</ShortName>
04 <LongName xml:lang="en">Additional Transportation Status</LongName>
05 <Version>1</Version>
06 <CanonicalUri>urn:x-company:codes:gc:addstatus</CanonicalUri>
07 <CanonicalVersionUri>urn:x-company:codes:gc:addstatus-1
08 </CanonicalVersionUri>
09 </Identification>
10 ...
11 <SimpleCodeList>
12 <Row>
13 <Value ColumnRef="code">
14 <SimpleValue>998</SimpleValue>
15 </Value>
16 <Value ColumnRef="name">
17 <SimpleValue>Evaporated</SimpleValue>
18 </Value>
19 </Row>
20 <Row>
21 <Value ColumnRef="code">
22 <SimpleValue>999</SimpleValue>
23 </Value>
24 <Value ColumnRef="name">
25 <SimpleValue>Eaten</SimpleValue>
26 </Value>
27 </Row>
28 </SimpleCodeList>
29 </gc:CodeList>
]
Step 4: validate with reduced list and extension list status-constraints.cva
[[1] - declare the two lists using <ValueList> elements
[[2] - union the two lists using the <Context> element
][1] - the restricted list needs to masquerade the restricted list's meta data with the UBL list's meta data
[[2] - this allows an instance to be validated with either the full UBL list or the reduced list, but any values not in the reduced
list will be rejected during validation
]]
[Example 5-31: 01 <ValueListConstraints xmlns="http://docs.oasis-open.org/codelist/..."
02 xmlns:cbc="urn:oasis:...:CommonBasicComponents-2"
03 id="urn:x-exercise"
04 name="code-list-rules">
05
06 ... Annotation/Description/Title information ...
07
08 <!--list all of the genericode expressions of agreed-upon
09 code list value enumerations-->
10 <ValueLists>
11 <ValueList xml:id="UBLcodes-restricted"
12 uri="My_TransportationStatusCodes.gc">
13 <!--masquerade the UBL meta data while pointing to reduced list-->
14 <Identification>
15 <ShortName>TransportationStatusCode</ShortName>
16 <LongName>Transportation Status</LongName>
17 <LongName Identifier="listID">UN/ECE rec 24</LongName>
18 <Version>Third Revision</Version>
19 <CanonicalUri>urn:oasis:names:specification:ubl:codelist:gc:
20 TransportationStatusCode</CanonicalUri>
21 <CanonicalVersionUri>urn:oasis:names:specification:ubl:codelist:gc:
22 TransportationStatusCode-2.0</CanonicalVersionUri>
23 <Agency>
24 <Name>United Nations Economic Commission for Europe</Name>
25 <AgencyID>6</AgencyID>
26 </Agency>
27 </Identification>
28 </ValueList>
29 <ValueList xml:id="extra-codes"
30 uri="Additional_TransportationStatusCodes.gc"/>
31 </ValueLists>
32 <!--list all of the contexts in which value enumerations are used-->
33 <Contexts>
34 <Context item="cbc:ConditionCode"
35 values="UBLcodes-restricted extra-codes"/>
36 </Contexts>
37 </ValueListConstraints>
]
Step 5: create master schema status-codes.sch to incorporate list constraints
[[1] - create a schema fragment to include the constraints expressed by the context/value associations
[1] - this modularity would allow other Schematron-expressed constraints to be included into the including fragment
]
[Example 5-32: 01 <schema xmlns="http://purl.oclc.org/dsdl/schematron">
02 <title>Code list value assertions</title>
03 <ns prefix="cbc" uri="urn:oasis:...:CommonBasicComponents-2"/>
04
05 <include href="status-constraints.sch"/>
06 </schema>
]
Step 6:
[[1] - each section below is marked with "==============" at the right edge of the transcript
]
Validate the constraints against the CVA document model
[[1] - this ensures that the expression of document context constraints is syntactically correct
]
Convert the constraints into a Schematron component
[[1] - this interprets the XPath addresses of the document contexts and genericode expressions of codes and meta data
[1] - masquerading meta data overrides any external genericode meta data
]
Assemble Schematron components into a complete schema
[[1] - this creates a single Schematron schema from the including fragment and all included fragments
]
Convert Schematron schema into XSLT
[[1] - using the CVA wrapper and the publicly-available Schematron skeleton, this creates an XSLT stylesheet suitable for running
against XML instances for value validation
]
[Example 5-33: 01 :: Validate constraints against the CVAUG document model:============
02 :: w3cschema ContextValueAssociation.xsd status-constraints.cva
03 :: Return: 0
04 Attempting validating, namespace-aware parse
05 Parse succeeded (0.270) with no errors and no warnings.
06 :: Convert constraints into a Schematron component:===================
07 :: xslt status-constraints.cva Crane-UBL-genericode2Schematron.xsl
08 status-constraints.sch
09 :: Return: 0
10 :: Assemble Schematron components into a complete schema:=============
11 :: xslt status-codes.sch iso_schematron_assembly.xsl
12 status-codes-runtime.sch
13 :: Return: 0
14 :: Convert Schematron schema into XSLT:===============================
15 :: xslt status-codes-runtime.sch Message-Schematron-terminator.xsl
16 status-codes-runtime.xsl
17 :: Return: 0
]
Step 7:
[[1] - each section below is marked with "==============" at the right edge of the transcript
]
Validate and check value constraints on message-good1.xml
[[1] - this instance validly uses a code from the standard UBL code list
[1] - <cbc:ConditionCode listID="UN/ECE rec 24">5</cbc:ConditionCode>
]
Validate and check value constraints on message-good2.xml
[[1] - this instance validly uses a code from the extended code list with additional values
[1] - note that while no meta data is given here, one could choose to add meta data provided it is the meta data of the extended
list
[1] - <cbc:ConditionCode>999</cbc:ConditionCode>
]
Validate and check value constraints on message-bad.xml
[[1] - this instance improperly uses a code from the extended code list with additional values while using meta data from the standard
UBL code list
[1] - <cbc:ConditionCode listID="UN/ECE rec 24">999</cbc:ConditionCode>
]
[Example 5-34: 01 :: Validate and check constraints on message-good1.xml:===============
02 :: w3cschema UBL-TransportationStatus-2.0.xsd message-good1.xml
03 :: Return: 0
04 Attempting validating, namespace-aware parse
05 Parse succeeded (0.911) with no errors and no warnings.
06 :: xslt message-good1.xml status-codes-runtime.xsl nul
07 :: Return: 0
08 :: Validate and check constraints on message-good2.xml:===============
09 :: w3cschema UBL-TransportationStatus-2.0.xsd message-good2.xml
10 :: Return: 0
11 Attempting validating, namespace-aware parse
12 Parse succeeded (0.891) with no errors and no warnings.
13 :: xslt message-good2.xml status-codes-runtime.xsl nul
14 :: Return: 0
15 :: Validate and check constraints on message-bad.xml:=================
16 :: w3cschema UBL-TransportationStatus-2.0.xsd message-bad.xml
17 :: Return: 0
18 Attempting validating, namespace-aware parse
19 Parse succeeded (0.891) with no errors and no warnings.
20 :: xslt message-bad.xml status-codes-runtime.xsl nul
21 Value supplied '999' is unacceptable for values identified by
22 'UBLcodes-restricted extra-codes' in the context 'cbc:ConditionCode':
23 /TransportationStatus/cac:TransportEvent[2]/cac:CurrentStatus[1]/
24 cbc:ConditionCode[1]
25
26 Processing terminated by xsl:message at line 143
27 :: Return: 1
]
5.3 Rendering context/value association files
[> 6.][< 5.2.3][^^][^^^]
5.3.1 Rendering context/value association files
[> 5.3.2][> 6.][< 5.2.3][^^][^^^]
Some audiences do not appreciate having to read raw XML to interpret the contents
[[1] - angle brackets are distracting
[1] - the volume of XML markup overwhelms the information content of the instance
]
Crane Softwrights Ltd. has published free developer resources with which to render a context/value association file to HTML
[[1] - XSLT 1.0 stylesheet: Crane-assoc2html.xsl
[1] - standalone production of HTML from context/value association file
[1] - browser-based viewing of HTML from context/value association file
]
The rendering of the context/value association file includes the rendering of the referenced genericode files
[[1] - the stylesheet for the context/value association file automatically imports the stylesheet for a genericode file
]
See [Browser-based viewing of an HTML rendering - Section 3.3.3] for the technique of embedding a stylesheet association processing instruction
Instead of embedding simple text for documentation, one can use rich markup
[[1] - the Crane stylesheet supports the embedding of HTML
[1] - note in the order-constraints-doc.xml example the declaration of the HTML namespace and use of the "x:" namespace prefix
]
[Example 5-35: 01 <?xml-stylesheet type="text/xsl" href="Crane-assoc2html.xsl"?>
02 <ValueListConstraints
03 xmlns="urn:oasis:names:tc:ubl:schema:Value-List-Constraints-0.8"
04 xmlns:cbc="urn:oasis:...:CommonBasicComponents-2"
05 xmlns:cac="urn:oasis:...:CommonAggregateComponents-2"
06 xmlns:x="http://www.w3.org/TR/REC-html40"
07 xmlns:sch="http://purl.oclc.org/dsdl/schematron"
08 id="urn:x-illustration"
09 name="code-list-rules">
10 <Title>
11 Illustration of code list constraints -
12 <x:samp>order-constraints.cva</x:samp>
13 </Title>
14 <Identification>
15 <x:pre>
16 $Id: order-constraints-doc.cva,v 1.1 2007/02/10 02:24:18
17 G. Ken Holman Exp $
18 </x:pre>
19 </Identification>
20 <Description>
21 <x:p>
22 This is an illustrative example of all of the features of
23 specifying the context/value constraints that one can express
24 for XML documents.
25 </x:p>
26 <x:p>
27 The validation requirements for this contrived scenario are as
28 follows:
29 <x:ul>
30 <x:li>the UN/CEFACT currency code list is restricted to be
31 only Canadian and US dollars:</x:li>
32 <x:li>the seller must be in the US</x:li>
33 <x:li>the buyer may be in either Canada or the US</x:li>
34 <x:li>the definition for Payment Means is extended to include
35 both UBL definitions and additional definitions</x:li>
36 </x:ul>
37 </x:p>
38 </Description>
39 ...
]
5.3.2 Standalone production of an HTML rendering
[> 6.][< 5.3.1][^][^^][^^^]
Consider the HTML rendering of the earlier example of a context/value association file on [Example 5-35] rendered using:
[[1] - java -jar saxon.jar -o order-constraints.html
order-constraints.cva Crane-assoc2html.xsl
]
The resulting HTML file when rendered appears as follows:
[Figure 5.9: HTML rendering of a context/value association file
A screen shot shows an HTML rendering of the context/value association file.
]
Note how the HTML browser renders the text together in a single paragraph
[[1] - there are no markup constructs in the documentary content
[1] - there are line breaks in the resulting HTML page, but the browser normalizes these into a space, thus running the lines together
]
Compare with the rendering of the example of a context/value association file with embedded HTML on [Example 5-35]:
[Figure 5.10: HTML rendering of a context/value association file containing HTML
A screen shot shows an HTML rendering of the context/value association file with embedded documentation.
]
Note how the HTML browser renders the embedded HTML constructs.
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 Code List Implementation 2009-02-09 22:30UTC//EN
Practical Code List Implementation
First Edition - 2009-02-09
ISBN 978-1-894049-22-1
Copyright © Crane Softwrights Ltd.