sboeckelmann commented 1 year ago

While working on content negotiation I found a few issues that should be addressed

OpenAPI REST bindings

Content-Type Confusions

The GS1-CBV-XML-Format HTTP header description can easily be misinterpreted:

"When requesting XML content-type only, users can use this header to request receiving events with CBV values in either URN or Web URI format.

The Content-Type HTTP header defines the media-type being sent from the client to the server
The Accept HTTP header defines which media-type the client is expecting from from the server

This has led to some confusion where early adopters where sending JSON data with Content-Type: application/xml http header instead of Accept: application/xml, wondering about sometimes getting an error or JSON instead of XML.

Suggestion: speak of media-type instead of content-type and change description by mentioning the Accept http header.

EPCIS 2.0 Standard Document

12.3 Content negotiation, service discovery and custom headers for EPCIS

Some Examples do not match with OpenAPI sec
Incomplete: not all possible http header values found in OpenAPI REST were documented

GS1-EPC-Format

declared enum in OpenAPI: No_Preference, Always_GS1_Digital_Link, Always_EPC_URN, Never_Translates

example in document: Always_DL

GS1-CBV-XML-Format

declared enum in OpenAPI: [ No_Preference, Always_Web_URI, Always_URN, Never_Translates ]

example in document: Always_URL

mgh128 commented 1 year ago

Hi Sven (@sboeckelmann )

Thanks for this feedback. Agreed - we should talk about media type (formerly known as MIME type) for the data format (e.g. application/xml vs application/ld+json etc.) and we should make it clearer that the HTTP(S) Accept: header is used by the client's request for a specific media type, while the Content-Type: header is used by the server's response to indicate which media type / data format was actually sent.

GS1-CBV-XML-Format is a custom HTTP(S) header that does not select/express media type but does allow the client to request a preferred format for CBV URIs when the data is returned in XML. When the data is returned in JSON/JSON-LD, all standard CBV values are expressed as 'bare string' values such as "shipping", "receiving", which the EPCIS JSON-LD context resource correctly maps to the corresponding Web URI values, thanks to the very helpful work done by @jmcanterafonseca-iota on scoped JSON-LD contexts.

We'll also need to check chapter 12 and the examples to fix those inconsistencies you highlighted. The enumerations in OpenAPI are considered authoritative (unless they're completely wrong / misspelled), so it's likely that the corresponding values in the examples are simply outdated because the examples embedded in the Word / PDF standard were created and/or pasted in much earlier and not subsequently checked that they validate against the current OpenAPI interface - so we'll need to do this consistency check for all embedded examples in the Word/PDF standard.