UBL 2.1 JSON Alternative Representation Version 2.0

The OASIS Universal Business Language (UBL) defines a generic XML interchange format for business documents that can be restricted or extended to meet the requirements of particular industries. UBL includes a suite of XML Schemas with which one can validate the structural content of an XML document against the constraints of the vocabulary.

For users of JSON syntax, this note publishes two suites of JSON schemas with which one can validate the structural content of a JSON document against the constraints of the UBL 2.1 vocabulary. Also included are two transliterations of all of the UBL 2.1 example documents in JSON syntax with which one can test a number of the JSON schemas.

The structural patterns exhibited by JSON schemas that conform to the OASIS Business Document Naming and Design Rules Version 1.1 [BDNDR] are distinctive as document interchange structures. As such, their intent is only to convey in syntax the information content reflecting the same abstract model of the UN/CEFACT Core Component Technical Specification 2.01 [CCTS] with which the document model was designed. The rules govern two possible JSON schema structures, a legacy-based approach supporting future backwards compatibility, and a model-based approach specific to this version of UBL. Accordingly, and in parallel to an application’s use of XML syntax, the legacy-based JSON syntax used is generic in nature, supported by schemas of all versions of UBL. The model-based JSON syntax is suitable only for schemas conforming to the UBL 2.1 structures. Neither syntax is streamlined nor optimized for any particular application’s objectives

As one would undertake the unmarshalling of XML syntax into internal application data structures suitable for processing, one must also undertake the unmarshalling of JSON interchange syntax into whatever internal application data structures (or other JSON representations) of the content that are suitable for the task at hand. Of note, it has been observed that there are commercial JSON database tools unable to ingest this JSON interchange syntax directly without an application massaging the content first to suit the database schema necessary to enable a particular arbitrary use. Nevertheless, the JSON syntax used does conform to the published standard [ISO 21778 - ECMA JSON] and has been successfully demonstrated to be ingested by Python and Node.js applications and so is not a barrier to use for application developers.

The UBL Technical Committee makes no assumptions regarding how the XML syntax of UBL documents is to be managed by applications, and so similarly makes no assumptions regarding how any application’s use of the JSON syntax is to be managed. With the only objective being the lossless interchange of document content, the structures in both XML and legacy-based JSON syntax are designed with forward and backward compatibility in mind for applications that ingest the content. Certain constraints in future versions of UBL may be lessened in a backward compatible fashion, such as in regard to cardinality, and so applications can successfully ingest the arrays of objects used in this regard to accommodate changing cardinality. Moreover, transliteration can be accomplished without semantic interpretation of any contents that would require specialized treatment of any given construct.

In contrast, model-based JSON syntax is not designed with forward and backward compatibility due to different conventions for expressing structures of different maximum cardinality. Where a CCTS construct is specified to have an unbounded maximum cardinality, an array is used in the same way arrays are used in legacy-based JSON syntax. Where a CCTS construct is specified to have a bounded maximum cardinality of “1”, the structure is serialized without using an array. Accordingly, the serialization of JSON or the transliteration from XML requires knowledge of the maximum cardinality of all constructs in order to use the appropriate structures. When a version of UBL changes a construct’s maximum cardinality (which can be from bounded to unbounded only), a past instance no longer will validate with the new schemas. This breaks forward compatibility from the past instance’s perspective, and backward compatibility from a new instance’s perspective.

The section Section A.3, “Package Structure” outlines the top-level content of the ZIP file associated with this Committee Note. The directories are named such that the directories in this package can be overlaid on top of the directories of the UBL distribution without overwriting any pre-existing UBL file. In another environment, one would copy the entire json-schema-legacy/ subdirectory or json-schema-model/ subdirectory contents and then users would access the individual document schemas in the maindoc/ subdirectory. These schemas make relative references to shared fragments found in the common/ subdirectory and as such those shared fragments are not referenced directly by users as they are not well-formed schemas in their own right (there is no “$schema” property).

The UBL document schemas make provision for constraining UBL extension metadata but not for constraining extension content. The user wishing to validate extension content is expected to replace the common/UBL-ExtensionContentDataType-2.1.json fragment with one’s own specification of extension constraints. No other schema fragment is expected to be touched by users.

The UBL Technical Committee uses the UN/CEFACT Core Components Technical Specification (CCTS) 2.01 [CCTS] to create the semantic models of business documents. These abstract models are then used to generate concrete syntax models and the validation artefacts with which to constrain instances of that syntax. There is nothing in the model itself that is specific to any syntax. Naming and design rules [BDNDR] for building the models (as information bundles) and for generating the syntax validation artefacts for documents (as user data) are used by the committee to create the deliverables for users. This is depicted in Figure 1, “Naming and Design Rules in an Open-edi Application”.

Figure 1. Naming and Design Rules in an Open-edi Application

When modeling, CCTS governs how to define a class of business documents by specifying the available components as information bundles to be deployed to users as user data. An ABIE (aggregate) component specifies a collection of constituent components of ASBIE components (associations to ABIEs found in a common library) and BBIE components (basic indivisible portions of content that may have metadata). The Document ABIE is simply an ABIE that is not defined in the common library. A Document ABIE specifies the components at the apex of a business document. A Library ABIE specifies the components comprising an ASBIE at the branches of the business document tree form. BBIE components are the leaves of the business document where content is found in the context of the branches.

From an abstract information bundle perspective, a given business document is comprised of its Document ABIE with its indivisible BBIEs and with its (divisible) ASBIEs that each have their own BBIEs and ASBIEs.

Each BBIE is defined by its data type. The available Core Component Types are summarized in Chapter 8 of the CCTS 2.01 specification [CCTS]. Each type has a mandatory content component and a number of optional metadata supplementary components. The interpretation of the content is informed by the values of its given supplementary components. The data type content and supplementary component values are, ostensibly, either numbers, strings or Boolean values. Interpreting the strings to be abstract concepts such as date and time is up to the program.

The examples in the json-legacy/ and json-model/ subdirectories are transliterated from the sample XML instances found in the UBL 2.1 distribution at https://docs.oasis-open.org/ubl/os-UBL-2.1/xml/.

For legibility the examples are indented. Indentation is insignificant white space and optionally can be eliminated from the file.

The remaining sections are examples of legacy-mode JSON instances. See the model-mode directory for examples of the use of model-mode serialization.

{"_D":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
 "_A":"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
 "_B":"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
 "Invoice":[{
 "ID":[{"_":"123"}],
 "IssueDate":[{"_":"2011-09-22"}],
 "InvoicePeriod":[{
  "StartDate":[{"_":"2011-08-01"}],
  "EndDate":[{"_":"2011-08-31"}]
 }],
 "AccountingSupplierParty":[{
  "Party":[{
   "PartyName":[{
    "Name":[{"_":"Custom Cotter Pins"}]
   }]
  }]
 }],
 "AccountingCustomerParty":[{
  "Party":[{
   "PartyName":[{
    "Name":[{"_":"North American Veeblefetzer"}]
   }]
  }]
 }],
 "LegalMonetaryTotal":[{
  "PayableAmount":[{"_":100.00,
   "currencyID":"CAD"}]
 }],
 "InvoiceLine":[{
  "ID":[{"_":"1"}],
  "LineExtensionAmount":[{"_":100.00,
   "currencyID":"CAD"}],
  "Item":[{
   "Description":[{"_":"Cotter pin, MIL-SPEC"}]
  }]
 }]
}]}

This example has multiple BBIEs for “Note” and multiple ABIEs for “InvoiceLine”:

{"_D":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
 "_A":"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
 "_B":"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
 "Invoice":[{
 "ID":[{"_":"123"}],
 "IssueDate":[{"_":"2011-09-22"}],
 "Note":[{"_":"Test",
  "languageID":"en"},
 {"_":"Tester",
  "languageID":"fr"}],
 "InvoicePeriod":[{
  "StartDate":[{"_":"2011-08-01"}],
  "EndDate":[{"_":"2011-08-31"}]
 }],
 "AccountingSupplierParty":[{
  "Party":[{
   "PartyName":[{
    "Name":[{"_":"Custom Cotter Pins"}]
   }]
  }]
 }],
 "AccountingCustomerParty":[{
  "Party":[{
   "PartyName":[{
    "Name":[{"_":"North American Veeblefetzer"}]
   }]
  }]
 }],
 "LegalMonetaryTotal":[{
  "PayableAmount":[{"_":100.00,
   "currencyID":"CAD"}]
 }],
 "InvoiceLine":[{
  "ID":[{"_":"1"}],
  "LineExtensionAmount":[{"_":100.00,
   "currencyID":"CAD"}],
  "Item":[{
   "Description":[{"_":"Cotter pin, MIL-SPEC"}]
  }]
 },{
  "ID":[{"_":"2"}],
  "LineExtensionAmount":[{"_":200.00,
   "currencyID":"CAD"}],
  "Item":[{
   "Description":[{"_":"Axel"}]
  }]
 }]
}]}

{"_D":"urn:oasis:names:specification:ubl:schema:xsd:Order-2",
 "_A":"urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
 "_B":"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
 "Order":[{
 "UBLVersionID":[{"_":"2.1"}],
 "CustomizationID":[{"_":"urn:www.cenbii.eu:transaction:biicoretrdm001:ver1.0"}],
 "ProfileID":[{"_":"urn:www.cenbii.eu:profile:BII01:ver1.0",
  "schemeAgencyID":"BII",
  "schemeID":"Profile"}],
 "ID":[{"_":"34"}],
 "IssueDate":[{"_":"2010-01-20"}],
 "IssueTime":[{"_":"12:30:00"}],
 "Note":[{"_":"Information text for the whole order"}],
 "DocumentCurrencyCode":[{"_":"SEK"}],
 "AccountingCostCode":[{"_":"Project123"}],
 "ValidityPeriod":[{
  "EndDate":[{"_":"2010-01-31"}]
 }],
 "QuotationDocumentReference":[{
  "ID":[{"_":"QuoteID123"}]
 }],
 "OrderDocumentReference":[{
  "ID":[{"_":"RjectedOrderID123"}]
 }],
 "OriginatorDocumentReference":[{
  "ID":[{"_":"MAFO"}]
 }],
 "AdditionalDocumentReference":[{
  "ID":[{"_":"Doc1"}],
  "DocumentType":[{"_":"Timesheet"}],
  "Attachment":[{
   "ExternalReference":[{
    "URI":[{"_":"http://www.suppliersite.eu/sheet001.html"}]
   }]
  }]
 },{
  "ID":[{"_":"Doc2"}],
  "DocumentType":[{"_":"Drawing"}],
  "Attachment":[{
   "EmbeddedDocumentBinaryObject":[{"_":"UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi",
    "mimeCode":"application/pdf"}]
  }]
 }],
 "Contract":[{
  "ID":[{"_":"34322"}],
  "ContractType":[{"_":"FrameworkAgreementID123"}]
 }],
 "BuyerCustomerParty":[{
  "Party":[{
   "EndpointID":[{"_":"7300072311115",
    "schemeAgencyID":"9",
    "schemeID":"GLN"}],
   "PartyIdentification":[{
    "ID":[{"_":"7300070011115",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}]
   },{
    "ID":[{"_":"PartyID123"}]
   }],
   "PartyName":[{
    "Name":[{"_":"Johnssons byggvaror"}]
   }],
   "PostalAddress":[{
    "ID":[{"_":"1234567890123",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}],
    "Postbox":[{"_":"PoBox123"}],
    "StreetName":[{"_":"Rådhusgatan"}],
    "AdditionalStreetName":[{"_":"2nd floor"}],
    "BuildingNumber":[{"_":"5"}],
    "Department":[{"_":"Purchasing department"}],
    "CityName":[{"_":"Stockholm"}],
    "PostalZone":[{"_":"11000"}],
    "CountrySubentity":[{"_":"RegionX"}],
    "Country":[{
     "IdentificationCode":[{"_":"SE"}]
    }]
   }],
   "PartyTaxScheme":[{
    "RegistrationName":[{"_":"Herra Johnssons byggvaror AS"}],
    "CompanyID":[{"_":"SE1234567801"}],
    "RegistrationAddress":[{
     "CityName":[{"_":"Stockholm"}],
     "Country":[{
      "IdentificationCode":[{"_":"SE"}]
     }]
    }],
    "TaxScheme":[{
     "ID":[{"_":"VAT",
      "schemeID":"UN/ECE 5153",
      "schemeAgencyID":"6"}]
    }]
   }],
   "PartyLegalEntity":[{
    "RegistrationName":[{"_":"Johnssons Byggvaror AB"}],
    "CompanyID":[{"_":"5532331183",
     "schemeID":"SE:ORGNR"}],
    "RegistrationAddress":[{
     "CityName":[{"_":"Stockholm"}],
     "CountrySubentity":[{"_":"RegionX"}],
     "Country":[{
      "IdentificationCode":[{"_":"SE"}]
     }]
    }]
   }],
   "Contact":[{
    "Telephone":[{"_":"123456"}],
    "Telefax":[{"_":"123456"}],
    "ElectronicMail":[{"_":"pelle@johnsson.se"}]
   }],
   "Person":[{
    "FirstName":[{"_":"Pelle"}],
    "FamilyName":[{"_":"Svensson"}],
    "MiddleName":[{"_":"X"}],
    "JobTitle":[{"_":"Boss"}]
   }]
  }],
  "DeliveryContact":[{
   "Name":[{"_":"Eva Johnsson"}],
   "Telephone":[{"_":"1234356"}],
   "Telefax":[{"_":"123455"}],
   "ElectronicMail":[{"_":"eva@johnsson.se"}]
  }]
 }],
 "SellerSupplierParty":[{
  "Party":[{
   "EndpointID":[{"_":"7302347231111",
    "schemeAgencyID":"9",
    "schemeID":"GLN"}],
   "PartyIdentification":[{
    "ID":[{"_":"SellerPartyID123"}]
   }],
   "PartyName":[{
    "Name":[{"_":"Moderna Produkter AB"}]
   }],
   "PostalAddress":[{
    "ID":[{"_":"0987654321123",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}],
    "Postbox":[{"_":"321"}],
    "StreetName":[{"_":"Kungsgatan"}],
    "AdditionalStreetName":[{"_":"suite12"}],
    "BuildingNumber":[{"_":"22"}],
    "Department":[{"_":"Sales department"}],
    "CityName":[{"_":"Stockholm"}],
    "PostalZone":[{"_":"11000"}],
    "CountrySubentity":[{"_":"RegionX"}],
    "Country":[{
     "IdentificationCode":[{"_":"SE"}]
    }]
   }],
   "PartyLegalEntity":[{
    "RegistrationName":[{"_":"Moderna Produkter AB"}],
    "CompanyID":[{"_":"5532332283",
     "schemeID":"SE:ORGNR"}],
    "RegistrationAddress":[{
     "CityName":[{"_":"Stockholm"}],
     "CountrySubentity":[{"_":"RegionX"}],
     "Country":[{
      "IdentificationCode":[{"_":"SE"}]
     }]
    }]
   }],
   "Contact":[{
    "Telephone":[{"_":"34557"}],
    "Telefax":[{"_":"3456767"}],
    "ElectronicMail":[{"_":"lars@moderna.se"}]
   }],
   "Person":[{
    "FirstName":[{"_":"Lars"}],
    "FamilyName":[{"_":"Petersen"}],
    "MiddleName":[{"_":"M"}],
    "JobTitle":[{"_":"Sales manager"}]
   }]
  }]
 }],
 "OriginatorCustomerParty":[{
  "Party":[{
   "PartyIdentification":[{
    "ID":[{"_":"0987678321123",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}]
   }],
   "PartyName":[{
    "Name":[{"_":"Moderna Produkter AB"}]
   }],
   "Contact":[{
    "Telephone":[{"_":"346788"}],
    "Telefax":[{"_":"8567443"}],
    "ElectronicMail":[{"_":"sven@moderna.se"}]
   }],
   "Person":[{
    "FirstName":[{"_":"Sven"}],
    "FamilyName":[{"_":"Pereson"}],
    "MiddleName":[{"_":"N"}],
    "JobTitle":[{"_":"Stuffuser"}]
   }]
  }]
 }],
 "Delivery":[{
  "DeliveryLocation":[{
   "Address":[{
    "ID":[{"_":"1234567890123",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}],
    "Postbox":[{"_":"123"}],
    "StreetName":[{"_":"Rådhusgatan"}],
    "AdditionalStreetName":[{"_":"2nd floor"}],
    "BuildingNumber":[{"_":"5"}],
    "Department":[{"_":"Purchasing department"}],
    "CityName":[{"_":"Stockholm"}],
    "PostalZone":[{"_":"11000"}],
    "CountrySubentity":[{"_":"RegionX"}],
    "Country":[{
     "IdentificationCode":[{"_":"SE"}]
    }]
   }]
  }],
  "RequestedDeliveryPeriod":[{
   "StartDate":[{"_":"2010-02-10"}],
   "EndDate":[{"_":"2010-02-25"}]
  }],
  "DeliveryParty":[{
   "PartyIdentification":[{
    "ID":[{"_":"67654328394567",
     "schemeAgencyID":"9",
     "schemeID":"GLN"}]
   }],
   "PartyName":[{
    "Name":[{"_":"Swedish trucking"}]
   }],
   "Contact":[{
    "Name":[{"_":"Per"}],
    "Telephone":[{"_":"987098709"}],
    "Telefax":[{"_":"34673435"}],
    "ElectronicMail":[{"_":"bill@svetruck.se"}]
   }]
  }]
 }],
 "DeliveryTerms":[{
  "ID":[{"_":"FOT",
   "schemeAgencyID":"6",
   "schemeID":"IMCOTERM"}],
  "SpecialTerms":[{"_":"CAD"}],
  "DeliveryLocation":[{
   "ID":[{"_":"STO"}]
  }]
 }],
 "AllowanceCharge":[{
  "ChargeIndicator":[{"_":true}],
  "AllowanceChargeReason":[{"_":"Transport documents"}],
  "Amount":[{"_":100,
   "currencyID":"SEK"}]
 },{
  "ChargeIndicator":[{"_":false}],
  "AllowanceChargeReason":[{"_":"Total order value discount"}],
  "Amount":[{"_":100,
   "currencyID":"SEK"}]
 }],
 "TaxTotal":[{
  "TaxAmount":[{"_":100,
   "currencyID":"SEK"}]
 }],
 "AnticipatedMonetaryTotal":[{
  "LineExtensionAmount":[{"_":6225,
   "currencyID":"SEK"}],
  "AllowanceTotalAmount":[{"_":100,
   "currencyID":"SEK"}],
  "ChargeTotalAmount":[{"_":100,
   "currencyID":"SEK"}],
  "PayableAmount":[{"_":6225,
   "currencyID":"SEK"}]
 }],
 "OrderLine":[{
  "Note":[{"_":"Freetext note on line 1"}],
  "LineItem":[{
   "ID":[{"_":"1"}],
   "Quantity":[{"_":120,
    "unitCode":"LTR"}],
   "LineExtensionAmount":[{"_":6000,
    "currencyID":"SEK"}],
   "TotalTaxAmount":[{"_":10,
    "currencyID":"SEK"}],
   "PartialDeliveryIndicator":[{"_":false}],
   "AccountingCostCode":[{"_":"ProjectID123"}],
   "Delivery":[{
    "RequestedDeliveryPeriod":[{
     "StartDate":[{"_":"2010-02-10"}],
     "EndDate":[{"_":"2010-02-25"}]
    }]
   }],
   "OriginatorParty":[{
    "PartyIdentification":[{
     "ID":[{"_":"EmployeeXXX",
      "schemeAgencyID":"ZZZ",
      "schemeID":"ZZZ"}]
    }],
    "PartyName":[{
     "Name":[{"_":"Josef K."}]
    }]
   }],
   "Price":[{
    "PriceAmount":[{"_":50,
     "currencyID":"SEK"}],
    "BaseQuantity":[{"_":1,
     "unitCode":"LTR"}]
   }],
   "Item":[{
    "Description":[{"_":"Red paint"}],
    "Name":[{"_":"Falu Rödfärg"}],
    "SellersItemIdentification":[{
     "ID":[{"_":"SItemNo001"}]
    }],
    "StandardItemIdentification":[{
     "ID":[{"_":"1234567890123",
      "schemeAgencyID":"6",
      "schemeID":"GTIN"}]
    }],
    "AdditionalItemProperty":[{
     "Name":[{"_":"Paint type"}],
     "Value":[{"_":"Acrylic"}]
    },{
     "Name":[{"_":"Solvant"}],
     "Value":[{"_":"Water"}]
    }]
   }]
  }]
 },{
  "Note":[{"_":"Freetext note on line 2"}],
  "LineItem":[{
   "ID":[{"_":"2"}],
   "Quantity":[{"_":15,
    "unitCode":"C62"}],
   "LineExtensionAmount":[{"_":225,
    "currencyID":"SEK"}],
   "TotalTaxAmount":[{"_":10,
    "currencyID":"SEK"}],
   "PartialDeliveryIndicator":[{"_":false}],
   "AccountingCostCode":[{"_":"ProjectID123"}],
   "Delivery":[{
    "RequestedDeliveryPeriod":[{
     "StartDate":[{"_":"2010-02-10"}],
     "EndDate":[{"_":"2010-02-25"}]
    }]
   }],
   "OriginatorParty":[{
    "PartyIdentification":[{
     "ID":[{"_":"EmployeeXXX",
      "schemeAgencyID":"ZZZ",
      "schemeID":"ZZZ"}]
    }],
    "PartyName":[{
     "Name":[{"_":"Josef K."}]
    }]
   }],
   "Price":[{
    "PriceAmount":[{"_":15,
     "currencyID":"SEK"}],
    "BaseQuantity":[{"_":1,
     "unitCode":"C62"}]
   }],
   "Item":[{
    "Description":[{"_":"Very good pencils for red paint."}],
    "Name":[{"_":"Pensel 20 mm"}],
    "SellersItemIdentification":[{
     "ID":[{"_":"SItemNo011"}]
    }],
    "StandardItemIdentification":[{
     "ID":[{"_":"123452340123",
      "schemeAgencyID":"6",
      "schemeID":"GTIN"}]
    }],
    "AdditionalItemProperty":[{
     "Name":[{"_":"Hair color"}],
     "Value":[{"_":"Black"}]
    },{
     "Name":[{"_":"Width"}],
     "Value":[{"_":"20mm"}]
    }]
   }]
  }]
 }]
}]}