OASIS Universal Business Language (UBL) TC

 View Only
  • 1.  issue UBL-467 : Add ApplicableTerritoryAddress to Catalogue

    Posted 20 days ago
    All,

    Here is a summary of the request registered under UBL-467 : Add ApplicableTerritoryAddress to Catalogue.

    The UBL TC got a request via Peter Borresen to add the ApplicableTerritoryAddress to the root of the Catalogue document. The arguments to add this element are:
    • The CatalogueRequest document has the ApplicableTerritoryAddress also at the root level and by adding this the Catalogue document there is a similar link between the CatalogueRequest and the Catalogue.
    • It would make it easier to generate a Catalogue document because the ApplicableTerritoryAddress doesn't have to be repeated on each CatalogueLine under the RequiredItemLocationQuantity element. 
    • It is in line with more "Request/Response" documents in UBL where details from the request are repeated back in the response.

    I have looked into this request and I am against adding this element on catalogue document root level.

    From the UBL documentation and diagrams it is clear that the CatalogueRequest is just that, a request to send an (updated) catalogue document to the requester that meets its request. The receiver of the CatalogueRequest can determine how to respond to this. So any data that is contained in the CatalogueRequest should be considered by the receiver as just that: A request to create a catalogue document that contains data that are of interest to the requestor (now the receiver of the catalogue).
    (see https://docs.oasis-open.org/ubl/csd01-UBL-2.5/UBL-2.5.html#S-CATALOGUE)
    The current Catalogue document also does not contain a reference to a CatalogueRequest so it is also not possible to relate a received catalogue to a request that might have initiated it.

    The current Catalogue document has the ApplicableTerritoryAddress under the RequiredItemLocationQuantity. That is "A class for information about pricing structure, lead time, delivery, and location associated with an item." So whenever a catalogue producer needs to be able to specify anything about these elements this element needs to be provided. It is the only place in the catalogue to do so. And that also means that if you want to limit any of those elements to a "ApplicableTerritoryAddress" that is the place to do so. So multiple RequiredItemLocationQuantity can be present under a CatalogueLine if there are multiple variations of the mentioned elements for various "Territories". So it is already possi

    By adding this also at the root level of the document it might be confusing and restrictive for the producer.

    The "rule" that if it is not present at the line/detail level means that the ApplicableTerritoryAddress at root level should be "assumed" is something that actually goes against one of the rules we have in UBL:

    [IND6] The absence of a construct or data in a UBL instance document SHALL NOT carry meaning.

    That might be considered "controversial" and counter to what we are used to do with some elements at root level (like an OrderReference that then applies to the whole document for example) but in the strict reading of that rule it is not something that the receiver should "assume"

    The next reason is that the Catalogue producer is free to determine what catalogue document they want to send to a Receiver. And it also doesn't have to be based on a request. It also does not force the producer to create a document that is strictly limited to the request. So if the request as an ApplicableTerritoryAddress that is literally the address of the requestor, the producer can still issue a catalogue with a larger ApplicableTerritoryAddress (the whole city, the whole region, the whole country) so there is no requirement that the returned ApplicableTerritoryAddress is the same as on the request. It might even be that the producer just has a standard catalogue document available that is valid and has all the regions and places it does business. It could just send that catalogue back based on the request and the recipient would need to distill themselves what applies in their specific situation.

    That brings it also to additional burden on the recipient of a catalogue document. If both options are possible it needs to create and work with a situation where the ApplicableTerritoryAddress can be in different places for different producers so that is additional work to handle those differences.

    one might argue that the ApplicableTerritoryAddress should be a "broader" scope and could say "this is the catalogue for this country" or similar .. while still having different records under RequiredItemLocationQuantity for different regions in that country. But then we might have to add a different element in my view that is semantically different from the current at detail level.

    So those are my arguments and rationale to not add this element to the Catalogue at root level.

    If we decide to still go ahead and add this element then it should also be added to Catalogue Item Specification Update and Catalogue Pricing Update because a producer can also respond to a request with those two documents (or even send them out without any request)

    Regards,

    Kees D.


  • 2.  RE: issue UBL-467 : Add ApplicableTerritoryAddress to Catalogue

    Posted 20 days ago
    Thank you, Kees, for the providing your detailed perspective.

    Just to have the clarifications and counterpoints in the same thread:

    - The Catalogue is a business document in its own right. It is not necessarily a response to a Catalogue Request, neither in UBL nor in real-world practice. A Catalogue may be distributed independently as a standing offer, and constraining the cardinalities of the elements in the document based on the possibility that it might at times be a response to another document should be defined at Profile level and not in the document schema itself.

    - Saying that "this Catalogue applies to, e.g., the Benelux region" is semantically different than saying "this Item applies to the Benelux region". One defines the commercial scope of the Catalogue as a whole, while the line-level one defines restrictions or variations for individual items. These are complementary, not redundant, and both represent real business cases.

    - The requirement to be able to express the geographical scope of the Catalogue at document level is a common business requirement and is being brought to us by a community of users. We've always worked from the idea that UBL should be "designed to plug directly into existing business practices", not the other way around. And when a business practice requires the present of an element not yet existing in UBL, it's been our position to accommodate, not to ask industry to change their business practice to conform to UBL.

    - Suggesting that a receiver of a Catalogue can simply infer the intended geographical scope of the document by aggregating the item level data and then "doing the math" is against UBL's core principle of manifest values. It's also not how UBL is modelled elsewhere (document level totals vs. line level amounts, just to give an example). "The onus is on the sender to include all information, such as all pertinent indications and all relevant sums or calculations. The receiver must not be required to make any assumptions nor perform any computations whatsoever when dealing with the sender's information.".

    Additionally, I'm not sure that IND6 applies in this case. The rule that "the absence of a construct or data in a UBL instance shall not carry meaning" is meant to prevent inferred negation, e.g., omitting ProjectReference from an invoice does not imply "no project".  Adding an optional ApplicableTerritoryAddress at document level neither violates nor relies on that rule but it simply allows the sender to state the scope explicitly when relevant.

    Best regards,
    Kenneth

    Este correo electrónico y cualquier archivo transmitido con él son propiedad de Efact S.A.C., contiene información confidencial, y están destinados exclusivamente al uso de la persona o entidad a la que van dirigidas. Si usted no es el destinatario señalado, no puede difundir y distribuir o copiar este e-mail. Por favor notifique inmediatamente al remitente por correo electrónico si usted ha recibido este correo electrónico por error, y eliminar este correo electrónico de su sistema. Si usted no es el destinatario, se le notifica que revelar, copiar, distribuir o tomar cualquier acción basada en el contenido de esta información está estrictamente prohibida.

    This email and any files transmitted with it are the properties of Efact S.A.C., contains confidential information, and are intended solely for the use of the individual or entity to whom they are addressed. If you are not the named addressee you may not disseminate, distribute or copy this e-mail. Please notify the sender immediately by e-mail if you have received this e-mail by mistake, and delete this e-mail from your system. If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.






  • 3.  RE: issue UBL-467 : Add ApplicableTerritoryAddress to Catalogue

    Posted 20 days ago
    Kenneth,

    I agree with most of your points ... and especially your second point makes it clear that we need a different semantic element at Catalogue root level to say " "this Catalogue applies to, e.g., the Benelux region" so that it is clear it is different and independent and has a different meaning from the ApplicableTerritoryAddress at detail level.

    I also said in my original email: 
    "But then we might have to add a different element in my view that is semantically different from the current at detail level."

    So for that use case it would mean adding a CatalogueApplicableTerritoryAddress to show that it is something else than the detail at Catalogue line level and also something else then the ApplicableTerritoryAddress in the CatalogueRequest document.

    But the original request was (according to my interpretation of that request) done in conjunction with the Catalogue Request document and with the intention that the ApplicableTerritoryAddress in the Catalogue Request root was coming back one on one in the Catalogue document at root level. And that was "wrong" in my view.

    If we add a semantically different element at root level it also means it is NOT a replacement for the ApplicableTerritoryAddress at detailed level.

    Kees D.

    On Wed, Nov 19, 2025 at 2:34 PM Kenneth Bengtsson via OASIS <Mail@mail.groups.oasis-open.org> wrote:
    Thank you, Kees, for the providing your detailed perspective. Just to have the clarifications and counterpoints in the same thread: -... -posted to the "OASIS Universal Business Language (UBL) TC" community

    OASIS Universal Business Language (UBL) TC

    Post New Message
    Re: issue UBL-467 : Add ApplicableTerritoryAddress to Catalogue
    Reply to Group Reply to Sender via Email
    Nov 19, 2025 8:35 AM
    Kenneth Bengtsson
    Thank you, Kees, for the providing your detailed perspective.

    Just to have the clarifications and counterpoints in the same thread:

    - The Catalogue is a business document in its own right. It is not necessarily a response to a Catalogue Request, neither in UBL nor in real-world practice. A Catalogue may be distributed independently as a standing offer, and constraining the cardinalities of the elements in the document based on the possibility that it might at times be a response to another document should be defined at Profile level and not in the document schema itself.

    - Saying that "this Catalogue applies to, e.g., the Benelux region" is semantically different than saying "this Item applies to the Benelux region". One defines the commercial scope of the Catalogue as a whole, while the line-level one defines restrictions or variations for individual items. These are complementary, not redundant, and both represent real business cases.

    - The requirement to be able to express the geographical scope of the Catalogue at document level is a common business requirement and is being brought to us by a community of users. We've always worked from the idea that UBL should be "designed to plug directly into existing business practices", not the other way around. And when a business practice requires the present of an element not yet existing in UBL, it's been our position to accommodate, not to ask industry to change their business practice to conform to UBL.

    - Suggesting that a receiver of a Catalogue can simply infer the intended geographical scope of the document by aggregating the item level data and then "doing the math" is against UBL's core principle of manifest values. It's also not how UBL is modelled elsewhere (document level totals vs. line level amounts, just to give an example). "The onus is on the sender to include all information, such as all pertinent indications and all relevant sums or calculations. The receiver must not be required to make any assumptions nor perform any computations whatsoever when dealing with the sender's information.".

    Additionally, I'm not sure that IND6 applies in this case. The rule that "the absence of a construct or data in a UBL instance shall not carry meaning" is meant to prevent inferred negation, e.g., omitting ProjectReference from an invoice does not imply "no project".  Adding an optional ApplicableTerritoryAddress at document level neither violates nor relies on that rule but it simply allows the sender to state the scope explicitly when relevant.

    Best regards,
    Kenneth

    Este correo electrónico y cualquier archivo transmitido con él son propiedad de Efact S.A.C., contiene información confidencial, y están destinados exclusivamente al uso de la persona o entidad a la que van dirigidas. Si usted no es el destinatario señalado, no puede difundir y distribuir o copiar este e-mail. Por favor notifique inmediatamente al remitente por correo electrónico si usted ha recibido este correo electrónico por error, y eliminar este correo electrónico de su sistema. Si usted no es el destinatario, se le notifica que revelar, copiar, distribuir o tomar cualquier acción basada en el contenido de esta información está estrictamente prohibida.

    This email and any files transmitted with it are the properties of Efact S.A.C., contains confidential information, and are intended solely for the use of the individual or entity to whom they are addressed. If you are not the named addressee you may not disseminate, distribute or copy this e-mail. Please notify the sender immediately by e-mail if you have received this e-mail by mistake, and delete this e-mail from your system. If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.



      Reply to Group via Email   Reply to Sender via Email   View Thread   Recommend   Forward  




     
    You are subscribed to "OASIS Universal Business Language (UBL) TC" as kees@sipico.com. To change your subscriptions, go to My Subscriptions. To unsubscribe from this community discussion, go to Unsubscribe.



    Original Message:
    Sent: 11/19/2025 8:35:00 AM
    From: Kenneth Bengtsson
    Subject: RE: issue UBL-467 : Add ApplicableTerritoryAddress to Catalogue

    Thank you, Kees, for the providing your detailed perspective.

    Just to have the clarifications and counterpoints in the same thread:

    - The Catalogue is a business document in its own right. It is not necessarily a response to a Catalogue Request, neither in UBL nor in real-world practice. A Catalogue may be distributed independently as a standing offer, and constraining the cardinalities of the elements in the document based on the possibility that it might at times be a response to another document should be defined at Profile level and not in the document schema itself.

    - Saying that "this Catalogue applies to, e.g., the Benelux region" is semantically different than saying "this Item applies to the Benelux region". One defines the commercial scope of the Catalogue as a whole, while the line-level one defines restrictions or variations for individual items. These are complementary, not redundant, and both represent real business cases.

    - The requirement to be able to express the geographical scope of the Catalogue at document level is a common business requirement and is being brought to us by a community of users. We've always worked from the idea that UBL should be "designed to plug directly into existing business practices", not the other way around. And when a business practice requires the present of an element not yet existing in UBL, it's been our position to accommodate, not to ask industry to change their business practice to conform to UBL.

    - Suggesting that a receiver of a Catalogue can simply infer the intended geographical scope of the document by aggregating the item level data and then "doing the math" is against UBL's core principle of manifest values. It's also not how UBL is modelled elsewhere (document level totals vs. line level amounts, just to give an example). "The onus is on the sender to include all information, such as all pertinent indications and all relevant sums or calculations. The receiver must not be required to make any assumptions nor perform any computations whatsoever when dealing with the sender's information.".

    Additionally, I'm not sure that IND6 applies in this case. The rule that "the absence of a construct or data in a UBL instance shall not carry meaning" is meant to prevent inferred negation, e.g., omitting ProjectReference from an invoice does not imply "no project".  Adding an optional ApplicableTerritoryAddress at document level neither violates nor relies on that rule but it simply allows the sender to state the scope explicitly when relevant.

    Best regards,
    Kenneth

    Este correo electrónico y cualquier archivo transmitido con él son propiedad de Efact S.A.C., contiene información confidencial, y están destinados exclusivamente al uso de la persona o entidad a la que van dirigidas. Si usted no es el destinatario señalado, no puede difundir y distribuir o copiar este e-mail. Por favor notifique inmediatamente al remitente por correo electrónico si usted ha recibido este correo electrónico por error, y eliminar este correo electrónico de su sistema. Si usted no es el destinatario, se le notifica que revelar, copiar, distribuir o tomar cualquier acción basada en el contenido de esta información está estrictamente prohibida.

    This email and any files transmitted with it are the properties of Efact S.A.C., contains confidential information, and are intended solely for the use of the individual or entity to whom they are addressed. If you are not the named addressee you may not disseminate, distribute or copy this e-mail. Please notify the sender immediately by e-mail if you have received this e-mail by mistake, and delete this e-mail from your system. If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.