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 a suite 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 is a transliteration 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. Accordingly, and in parallel to an application’s use of XML syntax, the JSON syntax used is generic in nature and is neither 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 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 implement cardinality. Moreover, transliteration can be accomplished without semantic interpretation of any contents that would require specialized treatment of any given construct.

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/ subdirectory contents and then users would access the individual document schemas in the json-schema/maindoc/ subdirectory. These schemas make relative references to shared fragments found in the json-schema/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/ subdirectory 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.

{"_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"}]
    }]
   }]
  }]
 }]
}]}