hashlink is no substitute for proper semantic description of content

VladimirAlexiev commented 2 years ago

(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 https://github.com/w3c-ccg/traceability-vocab/issues/385 that CommissionEvent seems to address the same event as epcis:ObjectEvent CREATE).

msporny commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 1 year ago

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 commented 1 year ago

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

nissimsan commented 1 year ago

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

OR13 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

Agreed, @mkhraisha.

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

nissimsan commented 1 year ago

How about https://schema.org/Product

w3c-ccg / traceability-vocab

hashlink is no substitute for proper semantic description of content #548