Product defects: ids (how to represent an individual product), quantities

[VladimirAlexiev]

@nissimsan @mkhraisha cc @mgh128

I've looked at https://github.com/w3c-ccg/traceability-vocab/blob/main/docs/openapi/components/schemas/common/Product.yml. I'm comparing to EPCIS object events, which can use these standard IDs:

• GTIN for a product model
• LGTIN for GTIN plus a lot/batch number
• SGTIN for a GTIN plus a serial number

The identifiers in Product.yml are less well defined:

• productID gives example "ISBN", which suggests this should be used for a global identifier. But how would I know in which codification system?
• sku is a local part number. It's ok to have it, but doesn't provide global identification
• batchNumber corresponds to the L part of LGTIN. But there's no instruction whether it should be considered a suffix of productID
• commodity refers to a more generic code from the Harmonized System for customs purposes
• there's no serialNumber so I cannot track individual expensive product like cars or airplanes

In addition, EPCIS events use a generic Quantity element that uses UNCEFACT Rec20 3-char UoM codes. Product.yml has such generic property schema:size "sizeOrAmount", but also the 4 more specific weight, depth, width, height:.

• If I want to say "3kg of tomatoes" should I use size or weight?
• If I want to say "3 tomatoes", maybe schema:size would be a bit confusing?
• If I want to say "3 extra large tomatoes", should I go like this (turtle) <product> schema:size "extra large", 3 or maybe even <product> schema:size "extra large", [a schema:QuantitativeValue; value 3]

Maybe these specific props just cause confusion?

[mkhraisha]

@VladimirAlexiev, I don't think we have thanked you enough for your wonderful work. Thank you for this, and the many other issues you opened.

productID is intentionally made to be a generic id, that may or may not be a global identifier, some of the products in this vocabulary (such as a barrel of oil), simply do not have a global id in the industry, rather, they are provided IDs by individual companies that created them.

batchNumber Excellent point, if we choose to make productID more specific we can align it there. again looking at the barrel of oil example, batchNumber is used as an identification to identify batches of barrels of oil ( usually in the 60k range) and the number is issued by the pipelines, each pipeline creates its own numbering system. Pipelines also regularly reuse batch numbers and combine them with a date of creation to ensure uniqueness.

Commodity your understanding is spot on, not sure if there's a suggestion/point here.

serialNumber excellent point we should look into adding it or if we add SGTIN, might be a better path forward.

On the specific properties causing confusion, I absolutely agree, we have used QuantitativeMeasure and QualitativeMeasure in the past, it might be a good idea to look at the Quantity element @OR13 @nissimsan @mprorock @vivienfan.

[VladimirAlexiev]

@mkhraisha

• GTIN is global because its issuance is delegated to various companies (GS1 subscribers), similar to DOIs and IP addresses. There's no GTIN for "barrel of oil": that'd be in the GPC (global product classification); to learn about it you can start from https://www.wikidata.org/wiki/Property:P8957. There can be a GTIN for eg "Caucasus light oil from oil field X"
• if you use QuantitativeMeasure and QualitativeMeasure variously for weight, depth, width, height, size, that could be another mistake; the first 3 in particular should always be Quantitative IMHO. (And actually, these are QuantitativeValue, QualitativeValue)

[paulfdietrich]

A quick note on ProductID above. An ISBN is a form of GTIN (prefix 978 pr 979 as per https://www.gs1.org/docs/barcodes/GS1_General_Specifications.pdf 2.1.3.4) but as @VladimirAlexiev suggests, there is no way to know what the codification for this productID.

[OR13]

@nissimsan can you outline a proposal for steel product based on this discussion here?

[mkhraisha]

278 Is a sub-issue of this issue.

We should make the Product term contain the most generic versions of all identifiers possible GTIN

This could be in an array of externalIdentifiers or just included baseline.

[OR13]

Can someone propose a concrete path to "ready for PR" here?

[nissimsan]

Propose text changes to address issue.

[nissimsan]

The top part of this was addresses long ago, moving away from productID and introducing GTIN.

I very much agree that sizeOrAmount is terrible. It should go, but is currently used by around 30 OG and AGRI examples, which I find is beyond what I should be PRing. I encourage getting rid of it in those domains, and model around it.

Once we have talked this over, I will remove myself from holding this. The v1 tag is not needed for my sake - but others my want to action this short term.

[mkhraisha]

To me the fix is either add in Volume and remove SizeOrAmount or remove Height, Weight, depth, width

[mkhraisha]

@rhofvendahl are you able to articulate how SizeOrAmount is currently being used in agriculture products?

@mkhraisha will review if we can replace SizeOrAmount with Volume on the crude oil products.

[TallTed]

remove SizeOrAmount keep Height, Weight, depth, width consider adding Volume, Gravity, etc.

[rhofvendahl]

@mkhraisha sizeOrAmount in ag is generally used to indicate quantity of individual units of the product, which is independent of the size/weight/dimensions. For example, a product with name "Avocados" and description "Avocados, 4 pack boxes" might have:

          "sizeOrAmount": {
            "type": [
              "QuantitativeValue"
            ],
            "unitCode": "boxes",
            "value": "893"
          },

I agree that sizeOrAmount is unclear, maybe we could change it to unitQuantity?

[TallTed]

unitQuantity?

and then unitHeight, unitDepth, unitWidth, unitWeight, and possibly unitVolume, unitGravity...‽

[rhofvendahl]

@TallTed I think there's a little inconsistency but generally the vocab uses height weight etc. to refer to a large quantity of individual products, for example BillOfLading describes a product of 500. boxes with a weight of 1533 lbs, depth 10ft etc.

Looking at the actual descriptions in Product though, this really isn't clear. depth has description "The depth of the item", width and height also refer to "item", but weight has description "Weight of the product".

If we're using Product to refer to some quantity of individual items present in a shipment (which is consistent with most usage in the vocab), then I think we'll want to update descriptions and property names throughout the schema.

For instance:

description: A product, consisting of some quantity of same-type items packaged together.
[...]
  itemQuantity:
    title:  Item Quantity
    description: The quantity of product items.
    $ref: ./QuantitativeValue.yml
    $linkedData:
      term: itemQuantity
      '@id': [?]
  productWeight:
    title: Product Weight
    description: The weight of the product.
    $ref: ./QuantitativeValue.yml
    $linkedData:
      term: weight
      '@id': https://schema.org/weight
  productDepth:
    title: Depth
    description: The depth of the product.
    $ref: ./QuantitativeValue.yml
    $linkedData:
      term: depth
      '@id': https://schema.org/depth
[...]
  itemPrice:
    title: Item Price
    description: The price of a product item.
    $ref: ./PriceSpecification.yml
    $linkedData:
      term: productPrice
      '@id': https://schema.org/priceSpecification

If we instead want to treat Product as referring to the kind of unit that'd get sold at a store, that'd take some refactoring but should also be do-able. I'd be happy to create a PR for updating the wording on Product, IMO refactoring usage might be more appropriate for another issue.

[TallTed]

I think these ontology efforts are rather a mess, and may stay that way, because the existing paper forms are inconsistent from industry to industry (and possibly from company to company, and even employee to employee).

I'm not sure that this CG has the right makeup to make significant progress on standardizing all this. We might make some progress with a lot of sub-class definitions, but I'm struggling to see how to work with the differences in "unit" definitions between oil&gas "batches" and agricultural "bushels" and manufactured item "things" and...

We might increase efforts to enlist participation from other arenas, especially but not limited to cross-industry groups, whose broader knowledge and experience may inform our work, and result in something that even the most idiosyncratic users of today may adopt going forward. I am sorry to say that I don't have relevant contacts, that I know of.

[mkhraisha]

On the Oil side, we can remove sizeOrAmount and simply use volumes on the OIlAndGasProduct

[mkhraisha]

Action item for @mkhraisha is to create volumes on the Oil and Gas product side

[mkhraisha]

Will tackle this ASAP

[mkhraisha]

This is fixed, no further changes needed in the vocab