search

gs1 / EPCIS

Draft files being shared for EPCIS 2.0 development
Other
22 stars 7 forks source link

openapi.yaml must include No_Preference option in enum of GS1-EPC-Format #254

Closed shalikasingh closed 3 years ago

shalikasingh commented 3 years ago

Hi @joelvogt, @domguinard,

We think we should include No_Preference in the enum of GS1-EPC-Format within openapi.yaml. As-is: 

 enum:
        - Client_Chooses
        - Always_DL
        - Always_EPC_URN
        - Never_Translates

To-be:

 enum:
        - No_Preference
        - Client_Chooses
        - Always_DL
        - Always_EPC_URN
        - Never_Translates
mgh128 commented 3 years ago

I think No_Preference makes sense from the perspective of the client's use of the GS1-EPC-Format header.

I am less convinced that No_Preference makes sense from the perspective of the server (EPCIS repository) providing that value as information to the client about what the server's policy is regarding GS1 EPC Format.

From the perspective of the server/repository, all of the existing As-is values have a clear meaning:

Never_Translates means that the repository does not support translation even if requested by the client. Always_EPC_URN means that the repository always returns EPCIS data in which EPCs are returned as EPC URNs. Always_DL means that the repository always returns EPCIS data in which EPCs are returned as GS1 Digital Link URIs Client_Chooses means that the repository allows the client to choose the preferred format for EPCs.

I just don't understand what it would mean for the server/repository to express 'No_Preference' as an informative response to the client about its capabilities / policy / behaviour regarding GS1 EPC Format.

At https://docs.google.com/document/d/1h7VMLHr88t1w-uW5ZqekzZEK5oEJZcibYyj2D78hjA0/edit?usp=sharing I have prepared a 'truth table' based on my understanding/expectation of the behaviour, considering the supported capability expressed by the server using the informative GS1-EPC-Format header and the client's preferred behaviour expressed using its GS1-EPC-Format request header.

So for the server, I think the permitted values are:

For the client, I think the four permitted values are:

I think we therefore need to split these enumerations for GS1-EPC-Format into two enumerations, as shown above, one for use when validating the server's informative/declarative response about its behaviour / capabilities, the other for use when validating the client's request about preferred behaviour.

shalikasingh commented 3 years ago

Hi @mgh128,

Thanks for your valuable suggestion to split into two enumerations specific to request and response. We agree that No_Preference doesn't mean anything for expressing server capabilities.

shalikasingh commented 3 years ago

Liked the table you prepared and it's perfect to add in EPCIS 2.0 draft, What do you think @mgh128 ?

domguinard commented 3 years ago

Hi @shalikasingh and @mgh128 it is also my understanding that it would not make sense to have No_Preference from a server point of view so no update is needed to the openapi.yaml doc but do let me know if I misunderstood.

dakbhavesh commented 3 years ago

Hi @domguinard, I think there is some confusion about No_Preference enumeration. From the server point of view it doesn't have any significance however from the client's point of view it does hold some value. That's the reason @mgh128 suggested having two different sets of enumeration i.e. one for client and one for server.

dakbhavesh commented 3 years ago

Hi @mgh128, Shall we reopen this issue?

domguinard commented 3 years ago

Okay @dakbhavesh I get it now, thanks for clarifying. I reopened the issue accordingly.

Sorry if I'm missing a point but why don't we treat the absence of the GS1-EPC-Format as "the client has no preference" as this is done with most HTTP headers?

mgh128 commented 3 years ago

We could certainly treat absence of the GS1-EPC-Format as "the client has no preference" and eliminate that option from the code list - but we should state this assumption / interpretation explicitly in the draft. This would also have the advantage of potentially unifying the code list because we eliminate this 'no preference' code value which was only ever expressed by the client - and now handled by suppressing the GS1-EPC-Format header.

dakbhavesh commented 3 years ago

I agree we should state the absence of GS1-EPC-Format behavior in the draft and conclude this issue by unifying the codelist for both client and server.

mgh128 commented 3 years ago

Agreed - Greg will be delighted. One gong to Bhavesh and Dom!

dakbhavesh commented 3 years ago

Hi @mgh128 and @domguinard, Sorry it did not strike me earlier. I think we won't be able to unify GS1-EPC-Format codelist for both client and server as Client_Chooses option is only relevant for the server.

shalikasingh commented 3 years ago

Hi @mgh128, @domguinard,

We agree to treat the absence of the GS1-EPC-Format as "the client has no preference" but then we should surely change the description in openapi.yaml

As-is: description: | Request or response header to express how URIs are represented. Either using the GS1 Digital Link format as as URN. If both server and client set GS1-EPC-Format to No_Preference, the default value is Always_DL:

To-be: description: | Request or response header to express how URIs are represented (i.e.,either using the GS1 Digital Link format or as URN). If server has set GS1-EPC-Format to Client_Chooses then the absence of the GS1-EPC-Format header will be treated as "the client has no preference", and the default value is Always_DL

    _Below line must be removed_
    [- No_Preference: The client (if a request header) or server (if a response header or `OPTIONS` discovery) chooses the representation.]

Moreover, Client_Chooses option for a client does seem intuitive and we should think about separating the codelist for client and server. In case we agree to separate we can include No_Preference in the client's codelist.

domguinard commented 3 years ago

Thanks @shalikasingh I agree and will make the changes asap.