hashlink is no substitute for proper semantic description of content

[VladimirAlexiev]

(Split from #290)

https://github.com/w3c-ccg/traceability-vocab/blob/main/docs/openapi/components/schemas/common/CommissionEvent.yml#L43

    $linkedData:
      term: products
      '@id': https://w3c-ccg.github.io/hashlink/#hl-url-params

@nissimsan @mkhraisha

Problems with this example:

• it refers to a section in a document not to the URL of a semantic property
• it binds a specific local term products to a general URL regarding one aspect of data representation ("content protected with hashlink"). If you want to protect e.g. a list of containers with hashlink, would you use another specific term containers and still bind to that general URL?
• it says nothing about the data content (eg are those products expressed with GTIN? SGTIN? LGTIN? Mix of those? No global identifier? How are their quantities expressed? How are product characteristics expressed?)

Hashlink protection can only be used in conjunction with some defined semantic representation, not on its own. @msporny do you agree?

If you want to follow a standard, please read about epcis:ObjectEvent (added to #385 that CommissionEvent seems to address the same event as epcis:ObjectEvent CREATE).

[msporny]

Hashlink protection can only be used in conjunction with some defined semantic representation, not on its own. @msporny do you agree?

It is true that just having a hashlink doesn't provide any semantic details other binding the information digitally signed over to a very specific serialization of something. In some use cases, that might be enough... for example, hashlinking to a PDF/PNG/JPG such that a manual human process can perform after-the-fact discovery if something goes wrong, knowing that they're looking at the same document that was linked to in the original message.

It would be much better to hashlink to a document with some level of semantics, but that's not always possible or necessary. It really does depend on the use case.

I can't speak to this specific example without doing a deep dive on the use case, which I (unfortunately) don't have the cycles to do right now.

[mkhraisha]

Thank you for this!

We struggled a bit when creating this, our goal is to link to the product definition here: product, and indicate that this MUST be a hashlink, or a fully embedded product object, i.e. we want to semantically say this element is a product, and to reach it you must use a hashlink or embed the product schema.

[VladimirAlexiev]

@mkhraisha Is it really important to capture immutability?

• If someone fixes a spelling mistake in the product name, do you think you can sue them for this change?
• If you think it's important, how would you support it in the "embedded product object" case?

Your schema doesn't capture the "embedded product object" case. I've raised such need earlier in #280 (@OR13 @nissimsan).
Also, #290 is related.

[OR13]

This line should be updated to not rely on hashlinks:

https://github.com/w3c-ccg/traceability-vocab/blob/main/docs/openapi/components/schemas/common/CommissionEvent.yml#L56

[OR13]

Can we pull a commission event object schema from: https://ref.gs1.org/standards/epcis/

[nissimsan]

Look into EPCIS if there's a proper term we can use for this term definition.

[OR13]

Example: https://github.com/gs1/EPCIS/blob/ebe220dac0a8ca8f566206e4372650791f403d9f/JSON-simple-context/WithErrorDeclaration/ErrorDeclarationAndCorrectiveEvent.jsonld

{
        "type": "TransformationEvent",
        "eventTime": "2020-01-14T00:00:00+01:00",
        "eventTimeZoneOffset": "+01:00",
        "eventID": "urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8",
        "inputEPCList": [
          "urn:epc:id:sgtin:4012345.011111.987"
        ],
        "outputEPCList": [
          "urn:epc:id:sgtin:4012345.033333.AGHFG"
        ],
        "inputQuantityList": [
          {
            "epcClass": "urn:epc:class:lgtin:4012345.022222.87545GHGH",
            "quantity": 500,
            "uom": "KGM"
          }
        ],
        "outputQuantityList": [
          {
            "epcClass": "urn:epc:idpat:sgtin:4012345.044444.*",
            "quantity": 452,
            "uom": "KGM"
          }
        ],
        "bizStep": "commissioning",
        "readPoint": {"id": "urn:epc:id:sgln:0614141.07346.1234"},
        "errorDeclaration": {
          "declarationTime": "2020-01-15T00:00:00+01:00",
          "reason": "incorrect_data",
          "example:vendorExtension": "Test1",
          "correctiveEventIDs": [
            "urn:uuid:404d95fc-9457-4a51-bd6a-0bba133845a8"
          ]
        }
      }{
        "type": "TransformationEvent",
        "eventTime": "2020-01-14T00:00:00+01:00",
        "eventTimeZoneOffset": "+01:00",
        "eventID": "urn:uuid:374d95fc-9457-4a51-bd6a-0bba133845a8",
        "inputEPCList": [
          "urn:epc:id:sgtin:4012345.011111.987"
        ],
        "outputEPCList": [
          "urn:epc:id:sgtin:4012345.033333.AGHFG"
        ],
        "inputQuantityList": [
          {
            "epcClass": "urn:epc:class:lgtin:4012345.022222.87545GHGH",
            "quantity": 500,
            "uom": "KGM"
          }
        ],
        "outputQuantityList": [
          {
            "epcClass": "urn:epc:idpat:sgtin:4012345.044444.*",
            "quantity": 452,
            "uom": "KGM"
          }
        ],
        "bizStep": "commissioning",
        "readPoint": {"id": "urn:epc:id:sgln:0614141.07346.1234"},
        "errorDeclaration": {
          "declarationTime": "2020-01-15T00:00:00+01:00",
          "reason": "incorrect_data",
          "example:vendorExtension": "Test1",
          "correctiveEventIDs": [
            "urn:uuid:404d95fc-9457-4a51-bd6a-0bba133845a8"
          ]
        }
      }

[mkhraisha]

I believe a solution is at line to move from:

  products:
    title: Products
    description: The products referenced by the event in hashlinks.
    type: array
    items:
      type: string
    $linkedData:
      term: products
      '@id': https://w3c-ccg.github.io/hashlink/#hl-url-params

to:

  products:
    title: Products
    description: The products referenced by the event in hashlinks.
    type: array
    items:
      type: string
      format: url
    $linkedData:
      term: products
      '@id': https://w3id.org/traceability#Product

[nissimsan]

Agreed, @mkhraisha.

Ideally, though, we find an existing alternative to https://w3id.org/traceability#Product.

[nissimsan]

How about https://schema.org/Product