Develop JSON Schema for Event Profile 'Fishing Event' #7

RalphTro · 2024-11-07T09:27:49Z

Dear @Aravinda93 , dear @albert-verdeny ,

This is an event profile for fish traceability, loosely aligned with existing solutions and guidelines, but deliberately not a 1:1 copy to not overcomplicate things. It contains a couple of elements that, from my POV, our tool should be able to cover, incl. support for 'legacy' EPC URIs, quantities, specific unit codes, ILMD data (even though the latter is likely to be discouraged/deprecated in the upcoming future), hierarchical data structures in extensions, code values, etc. So, I think that developing the corresponding JSON schema for this is a valuable and important exercise.

Event Profile 'Fishing Event'

Set of rules

The EPCIS Event is an ObjectEvent.
The action field is populated with the value "ADD".
The bizStep field is populated with the value "commissioning".
The readPoint is populated with an SGLN EPC URI (e.g. "urn:epc:id:sgln:4012345.00001.0")
The quantityList includes exactly one ID.
The ID in the quantityList is an LGTIN, expressed as an EPC Class URI (e.g. "urn:epc:class:lgtin:4012345.099914.LOT1").
The quantity field as part of the QuantityElement must be populated with a positive decimal value.
The uom field as part of the QuantityElement must be populated with a UN/CEFACT Rec 20 value for mass (FYC, see https://github.com/gs1/UnitConverterUNECERec20/blob/master/src/UnitConverterUNECERec20.js - type "mass"), e.g. "KGM"
The event contains an ilmd field.
All ILMD field names are prefixed with "cbvmda".
~~The event contains a proper declaration for "cbvmda" ("urn:epcglobal:cbv:mda").~~
Within the ILMD element, there is a cbvmda:bestBeforeDate field.
The cbvmda:bestBeforeDate field is filled with a proper date value.
Within the ILMD element, there is a cbvmda:storageStateCode field.
The cbvmda:storageStateCode field is filled with a corresponding code value according to https://navigator.gs1.org/gdsn/class-details?name=StorageStateCode&version=12 (e.g. "PREVIOUSLY_FROZEN")
Within the ILMD element, there is a cbvmda:vesselCatchInformationList field.
Within the cbvmda:vesselCatchInformationList field, there are two sub-fields: cbvmda:vesselID and cbvmda:vesselFlagState.
The cbvmda:vesselID field is filled with a string value.
The cbvmda:vesselFlagState field is filled with a ISO 3166-1 alpha-2 code value (e.g. "DE").

Are all of the above rules understandable/make sense for you?

Very much looking forward to seeing the corresponding JSON schema come alive - many thanks in advance for your support in this!

Kind regards;
Ralph

@dakbhavesh: FYI.

The text was updated successfully, but these errors were encountered:

Aravinda93 · 2024-11-13T11:34:18Z

Dear @RalphTro

Just wanted to update you that @albert-verdeny and I are in contact and started to develop the JSON Schema based on your detailed description. We will keep you posted on the same and request for your feedback as we have the draft version of the same.

Best regards,
Aravinda

RalphTro · 2024-11-13T11:53:52Z

Dear @Aravinda93 and @albert-verdeny - MANY THANKS!

Aravinda93 · 2024-11-14T09:15:47Z

Dear @RalphTro

I have one small confusion associated with point 16 of your description. It has been mentioned as the field cbvmda:vesselCatchInformationList so should this be of "type": "array" or "type": "object"?

Because the field key contains list I thought it should be array but the later points 17, 18 and 19 of the description do not seem to support list but rather as object so thought of clarifying the same.

Can you please confirm if cbvmda:vesselCatchInformationList is array or object? As per the description in CBV Standard doc it should be a List

Example 1 with "type": "array":

"cbvmda:vesselCatchInformationList": [
  {
    "cbvmda:vesselFlagState": "DE",
    "cbvmda:vesselID": "1234"
  }
]

Example 2 with "type": "object":

"cbvmda:vesselCatchInformationList": {
  "cbvmda:vesselFlagState": "DE",
  "cbvmda:vesselID": "1234"
}

RalphTro · 2024-11-14T10:13:39Z

Dear @Aravinda93 ,
Good question. I just double-checked CBV section 9.2.3, and given that the CBV states "The value of vesselCatchInformationList consists of one or more elements named vesselCatchInformation, which contains the following subelements (...)".
Even though implementations I am aware of did not repeat fields such as e.g. vesselID etc., I think the CBV specification (at this time, we only had an XML mapping) was intended to cater for situations to indicate several ones. So, if we apply/map this to the JSON/JSON-LD world, I think it should be an array of objects; i.e. option 1.
WDYT?
Kind regards;
Ralph

Aravinda93 · 2024-11-14T10:58:55Z

@RalphTro

Thanks a lot for the quick clarification. Yes even I thought it should be an option-1 with "type": "array" but just wanted to double-check. I will proceed with option1 in JSON Schema.

albert-verdeny · 2024-11-19T20:12:04Z

Dear @RalphTro, many thanks for the great profile! And thanks so much @Aravinda93 for driving the technical implementation!

Just a minor clarification about the requirement 11: what do you mean exactly with "declaration"?
"cbvmda": "urn:epcglobal:cbv:mda:" is already part of the epcis context – are you thinking of something beyond that?

RalphTro · 2024-11-20T13:37:41Z

Dear @albert-verdeny ,
You are right! I think this happened becase I was looking at an old XML event when drafting this. ;-)
So, please disregard this requirement.
Just crossed it out. :-)

RalphTro · 2024-11-25T14:07:31Z

Dear @albert-verdeny and @Aravinda93,
Brief question: are you able to share a first draft of the JSON profile until Friday this week? That would be perfect, as I reserved some time for testing/providing feedback on Friday, which would then give you the opportunity to refine it before our call on Dec 3rd, if necessary.

Aravinda93 · 2024-11-25T15:58:58Z

Dear @RalphTro

Surely we can provide you with the first draft of the JSON profile before Friday. It has gone through initial testing from @albert-verdeny and my side. There are some minor changes and final validation needs to be done from our end as soon as it's done we will provide you with the same.

RalphTro · 2024-11-25T16:08:58Z

Super. Thanks for the heads-up and looking forward to testing it!

albert-verdeny · 2024-11-26T12:39:02Z

Dear @RalphTro,

Another point I would like to clarify: in your requirement

Within the cbvmda:vesselCatchInformationList field, there are two sub-fields: cbvmda:vesselID and cbvmda:vesselFlagState.

I understand the two fields are required, correct?

Now, in the comments above we see that cbvmda:vesselCatchInformationList needs to be an array.

Do we want to ensure that there is at least one element on this array or any similar condition?

If not, this means cbvmda:vesselCatchInformationList can then technically be empty, so the event wouldn't necessarily have cbvmda:vesselID and cbvmda:vesselFlagState.

RalphTro · 2024-11-26T13:39:14Z

Dear @albert-verdeny ,
Thanks for your follow-up questions.

As to "I understand the two fields are required, correct?" --> Correct. Both fields need to be present. (For instance, to ensure that an event contains data that is legally required.)

As to "Do we want to ensure that there is at least one element on this array or any similar condition?" --> I would like to see that the schema validates/ensures that both sub-fields are present, non-empty, and filled with a proper value (i.e. string + ISO 3166-1 alpha-2 code).

Does this answer your question?

albert-verdeny · 2024-11-26T13:49:07Z

Dear @RalphTro,

Thanks for the reply and apologies I am not clear on the second point yet.

I understand that the attribute cbvmda:vesselCatchInformationList must be an array of items cbvmda:VesselCatchInformation.

I also understand that the items cbvmda:VesselCatchInformation must contain cbvmda:vesselID and cbvmda:vesselFlagState, that's clear now, thanks.

What I'm still unsure about: is there any restriction in the number of items that the array cbvmda:vesselCatchInformationList contains? Should we enforce at least one element in the list?

albert-verdeny · 2024-11-26T13:59:56Z

Basically I want to avoid the situation where we have an event with "cbvmda:vesselCatchInformationList": [] that passes the JSON schema – of course provided that this is something we want to fail.

RalphTro · 2024-11-26T14:04:58Z

Ah, I see now what you meant. Yes, I think avoiding an empty array as you pointed out is a good idea/helpful further quality check! In this case, defining that this property needs to contain at least one sub-property would do the trick from my POV.

Aravinda93 · 2024-11-27T09:57:50Z

Dear @RalphTro

@albert-verdeny and I have created the initial version of the JSON Schema based on your requirements.
Please find the attached schema file and code for your review. We look forward to your feedback and any observations you may have.

Event Profile Issue#7 Schema.json

Example

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "allOf": [
    { 
      "$ref": "https://ref.gs1.org/standards/epcis/epcis-json-schema.json"
    },
    {
      "type": "object",
      "properties": {
        "@context": {
          "type": "array",
          "items": {
            "type": "string",
            "const": "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld"
          },
          "minItems": 1,
          "maxItems": 1
        },
        "type": {
          "type": "string",
          "enum": ["ObjectEvent"]
        },
        "action": {
          "type": "string",
          "enum": ["ADD"]
        },
        "bizStep": {
          "type": "string",
          "enum": ["commissioning"]
        },
        "readPoint": {
          "type": "object",
          "properties": {
            "id": {
               "$ref": "#/definitions/readPointId"
            }
          },
          "required": ["id"]
        },
        "quantityList": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/quantityElement"
          },
          "minItems": 1,
          "maxItems": 1
        },
        "ilmd": {
          "type": "object",
          "properties": {
            "cbvmda:bestBeforeDate": {
              "type": "string",
              "format": "date"
            },
            "cbvmda:storageStateCode": {
              "type": "string",
              "enum": ["NOT_PREVIOUSLY_FROZEN", "PREVIOUSLY_FROZEN"]
            },
            "cbvmda:vesselCatchInformationList": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "cbvmda:vesselID": {
                    "type": "string"
                  },
                  "cbvmda:vesselFlagState": {
                    "$ref": "#/definitions/vesselFlagStateEnum",
                  }
                },
                "required": [
                  "cbvmda:vesselID", 
                  "cbvmda:vesselFlagState"
                ],
                "additionalProperties": false
              },
              "minItems": 1
            }
          },
          "patternProperties": {
            "^cbvmda:": {} 
          },
          "required":[
            "cbvmda:bestBeforeDate",
            "cbvmda:storageStateCode",
            "cbvmda:vesselCatchInformationList"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "@context",
        "type",
        "action",
        "bizStep",
        "readPoint",
        "quantityList",
        "ilmd"
      ],
      "additionalProperties": true
    }
  ],
  "definitions": {
    "readPointId":{
      "type": "string",
      "format": "uri",
      "pattern":"^urn:epc:id:sgln:((\\d{6}\\.\\d{6})|(\\d{7}\\.\\d{5})|(\\d{8}\\.\\d{4})|(\\d{9}\\.\\d{3})|(\\d{10}\\.\\d{2})|(\\d{11}\\.\\d{1})|(\\d{12}\\.))\\.(\\%2[125-9A-Fa-f]|\\%3[0-9A-Fa-f]|\\%4[1-9A-Fa-f]|\\%5[0-9AaFf]|\\%6[1-9A-Fa-f]|\\%7[0-9Aa]|[!\\')(*+,.0-9:;=A-Za-z_-]){1,20}$"
    },
    "quantityElement": {
      "type": "object",
      "properties": {
        "epcClass": {
          "$ref": "#/definitions/quantityElementURI"
        },
        "quantity": {
          "$ref": "#/definitions/quantityElementDecimal"
        },
        "uom": {
          "$ref": "#/definitions/quantityUOM"
        }
      },
      "required": [
        "epcClass", 
        "quantity", 
        "uom"
      ],
      "additionalProperties": false
    },
    "quantityElementURI": {
      "type": "string",
      "format": "uri",
      "pattern": "^urn:epc:class:lgtin:(([\\d]{6}\\.[\\d]{7})|([\\d]{7}\\.[\\d]{6})|([\\d]{8}\\.[\\d]{5})|([\\d]{9}\\.[\\d]{4})|([\\d]{10}\\.[\\d]{3})|([\\d]{11}\\.[\\d]{2})|([\\d]{12}\\.[\\d]{1}))\\.(\\%2[125-9A-Fa-f]|\\%3[0-9A-Fa-f]|\\%4[1-9A-Fa-f]|\\%5[0-9AaFf]|\\%6[1-9A-Fa-f]|\\%7[0-9Aa]|[!\\')(*+,.0-9:;=A-Za-z_-]){1,20}$"
    },
    "quantityElementDecimal": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "quantityUOM": {
      "type": "string",
      "enum": ["KGM", "GRM", "ONZ", "LBR", "MGM", "MC", "STI", "TNE"]
    },
    "vesselFlagStateEnum": {
      "type": "string",
      "enum": [
        "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ",
        "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ",
        "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ",
        "DE", "DJ", "DK", "DM", "DO", "DZ",
        "EC", "EE", "EG", "EH", "ER", "ES", "ET",
        "FI", "FJ", "FK", "FM", "FO", "FR",
        "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GT", "GU", "GW", "GY",
        "HK", "HM", "HN", "HR", "HT", "HU",
        "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT",
        "JE", "JM", "JO", "JP",
        "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ",
        "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY",
        "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ",
        "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ",
        "OM",
        "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PT", "PW", "PY",
        "QA",
        "RE", "RO", "RS", "RU", "RW",
        "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ",
        "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ",
        "UA", "UG", "UM", "US", "UY", "UZ",
        "VA", "VC", "VE", "VG", "VI", "VN", "VU",
        "WF", "WS",
        "YE", "YT",
        "ZA", "ZM", "ZW"
      ]
    }
  }
}

RalphTro · 2024-11-27T14:44:22Z

Dear @Aravinda93 and @albert-verdeny ,

MANY THANKS! And congratulations: happy to report that my first tests were successful. Great work!

One observation: Initially, I tried an EPCIS document (not just the event itself), and the validation failed. So, the interesting question is: do we also want to support our tool to be able to validate EPCIS documents embedding one or several events? If the answer is yes (which I am inclined to advocate), the JSON schema needs to be tweaked a bit so that a document is not invalidated from my POV.
WDYT?

FYC, I attached both of my test files.

EPCISDocWithFishingEvent_valid.json
EPCISFishingEvent_valid.json

Kind regards;
Ralph

PS: In case you are wondering about the file extension: GitHub does not seem to allow uploading JSON-LD files. ;-)

Aravinda93 · 2024-11-27T18:27:44Z

Dear @RalphTro

Thanks a lot for the quick testing and feedback.

Yes, we have currently taken into consideration only the individual event but we will make the changes to the schema so it can be validated by both the event and the document.

dakbhavesh · 2024-11-29T13:16:20Z

Dear @RalphTro, The intention of this exercise is to learn about real profiles from users. So at this stage, I feel it is okay to keep the schema validating the individual events.

We are yet to discuss the API support we want to provide. Therefore, it will be good to come up with ideas at that time whether we want to support the whole document individual event, or both.

My suggestion is to defer schema supporting the EPCIS document (with multiple events) for the time being and keep it limited to event JSON/JSON-LD only.

What do you think?

RalphTro · 2024-11-29T13:30:56Z

Dear @dakbhavesh ,
Thanks for sharing your thoughts. My spontaneous reaction: if we want our tool to be compatible with exising ones such as https://ref.gs1.org/tools/epcis-sandbox/create-event-data, I think it's almost inevitable to support EPCIS documents as e.g. the output of the 'Event Data Generator' is an EPCIS document.
So, how do you like the following idea/solution approach: our library/tool always comes with some kind of 'boilerplate' which inherently supports EPCIS documents (i.e. at least does not invalidate an event if it is embedded in an EPCIS document)?

Happy to discuss/reach consensus on this subject in the group.

sboeckelmann · 2024-11-29T16:47:41Z

Dear @RalphTro - in principle you are correct that the outcome also has to be used on an EPCISDocument.
But let's take one step after another. Look at single event first (and identify common patterns).
The EPCISDocument is just a stupid container for EPCIS Events, we will be able to integrate that later.
EPCISDocument implies support for a list of events and this has to be deferred.
Let's investigate on single event level first to also pick up a few learnings for the next level(s).

RalphTro · 2024-12-02T09:08:52Z

Dear @dakbhavesh and @sboeckelmann ,
Got your point. Agreed - let's table EPCIS documents for the time being.

RalphTro assigned Aravinda93 and albert-verdeny Nov 7, 2024

RalphTro linked a pull request Dec 3, 2024 that will close this issue

Inserted md and json file to schema folder #16

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Develop JSON Schema for Event Profile 'Fishing Event' #7

Develop JSON Schema for Event Profile 'Fishing Event' #7

RalphTro commented Nov 7, 2024 •

edited

Loading

Aravinda93 commented Nov 13, 2024

RalphTro commented Nov 13, 2024

Aravinda93 commented Nov 14, 2024 •

edited

Loading

RalphTro commented Nov 14, 2024

Aravinda93 commented Nov 14, 2024

albert-verdeny commented Nov 19, 2024

RalphTro commented Nov 20, 2024 •

edited

Loading

RalphTro commented Nov 25, 2024

Aravinda93 commented Nov 25, 2024

RalphTro commented Nov 25, 2024

albert-verdeny commented Nov 26, 2024

RalphTro commented Nov 26, 2024

albert-verdeny commented Nov 26, 2024

albert-verdeny commented Nov 26, 2024

RalphTro commented Nov 26, 2024 •

edited

Loading

Aravinda93 commented Nov 27, 2024

RalphTro commented Nov 27, 2024

Aravinda93 commented Nov 27, 2024

dakbhavesh commented Nov 29, 2024

RalphTro commented Nov 29, 2024

sboeckelmann commented Nov 29, 2024

RalphTro commented Dec 2, 2024

Develop JSON Schema for Event Profile 'Fishing Event' #7

Develop JSON Schema for Event Profile 'Fishing Event' #7

Comments

RalphTro commented Nov 7, 2024 • edited Loading

Event Profile 'Fishing Event'

Set of rules

Aravinda93 commented Nov 13, 2024

RalphTro commented Nov 13, 2024

Aravinda93 commented Nov 14, 2024 • edited Loading

RalphTro commented Nov 14, 2024

Aravinda93 commented Nov 14, 2024

albert-verdeny commented Nov 19, 2024

RalphTro commented Nov 20, 2024 • edited Loading

RalphTro commented Nov 25, 2024

Aravinda93 commented Nov 25, 2024

RalphTro commented Nov 25, 2024

albert-verdeny commented Nov 26, 2024

RalphTro commented Nov 26, 2024

albert-verdeny commented Nov 26, 2024

albert-verdeny commented Nov 26, 2024

RalphTro commented Nov 26, 2024 • edited Loading

Aravinda93 commented Nov 27, 2024

Example

RalphTro commented Nov 27, 2024

Aravinda93 commented Nov 27, 2024

dakbhavesh commented Nov 29, 2024

RalphTro commented Nov 29, 2024

sboeckelmann commented Nov 29, 2024

RalphTro commented Dec 2, 2024

RalphTro commented Nov 7, 2024 •

edited

Loading

Aravinda93 commented Nov 14, 2024 •

edited

Loading

RalphTro commented Nov 20, 2024 •

edited

Loading

RalphTro commented Nov 26, 2024 •

edited

Loading