The updated resolver spec

[philarcher]

Hi all,

After a discussion with @nicklansley I thought I'd say a few words here about some of the changes that the GS1-Conformant resolver spec introduces that are different from its previous incarnation in the GS1 Digital Link spec version 1.1.

We need to keep a very clear distinction between the way links are stored and associated with GS1 identifiers on the one hand, and how a resolver should respond to a query on the other.

I'll look at the query side first of all and use this DL URI as my example: https://example.com/01/09506000134352/10/ABC/21/123?11=230718 That is:

• GTIN: 09506000134352
• Batch/lot: ABC
• Serial: 123
• Production date 2023-07-18

We can dispense with the production date (and anything else in the query string) straight away. Although anyone is welcome to build a resolver that takes notice of query string parameters, there is no expectation that this will be done. You just pass the query string on to the target URL and otherwise ignore it (query string params describe the entity but don't identify it).

Suppose now the resolver gets a query specifically for certification info. That is, https://example.com/01/09506000134352/10/ABC/21/123?linkType=gs1:certificationInfo. This means "give me certification info about the entity that has that GTIN, Batch/lot and serial". The serial number means it's a specific instance of the product, so you're looking for a certificate about that specific thing.

• If there is a gs1:certificationInfo link at the serial level, redirect to it. Process ends.
• If there is no link to certification info at the serial level, walk up the tree defined in the input URI and look at batch/lot ABC. Got a certificationInfo link there? Redirect to it. Process ends.
• Still no certification info link at batch/lot? Walk up the tree again and look at the GTIN level. Got a certification info link at the GTIN level? If yes, redirect to it. If not, return a 404. Because the resolver was asked for certification info for that thing and it doesn't have any. Therefore, the response should be 404.

This is a change from the old spec where it said if you can't find the requested link type, return the default instead.

What happens if you have multiple links of type gs1:certificationInfo? Let's further assume that there are no differences in the recorded language, media type or context for those links. That is, resolver has no way to decide which of those multiple links to redirect to. In that circumstance you have to pass the decision back to the user and the correct HTTP Response Code is 300. It's little used but it's been there since HTTP was first developed and is perfect for our use case. How a resolver presents that set of options to the user is up to the implementation.

What about requesting the linkset? There are multiple ways to request the full linkset from a resolver.

1. Set the HTTP Accept header to application/linkset+json (conformant resolvers MUST support this)
2. Set the HTTP Accept header to application/json. This is RECOMMENDED (i.e. you SHOULD do it) We had a case where one resolver implementation returned different JSON data depending on whether the Accept header included linkset+ - and it caused problems. You can, but please don't without good reason.
3. Set the linkType parameter in the query string to linkset (irrespective of Accept header). Note that the previous parameter value of all to achieve this is deprecated. You might want to support it but it is likely to disappear as an option in future.

Resolvers should return the complete set of links for the input URI. To continue with the example above, given https://example.com/01/09506000134352/10/ABC/21/123 the linkset should include links for:

1. Any link that is defined for serial number 123 AND batch/lot ABC AND GTIN 09506000134352.
2. Any link that is defined for batch/lot ABC AND GTIN 09506000134352
3. Any link that is defined for GTIN 09506000134352
   In other words, any link that the resolver could redirect the query to.

It should not include links for other serial numbers or batches - because it wasn't asked about those. It may be. of course, that if I ask the same resolver for a different serial number I get back exactly the same linkset but that's irrelevant. Again, keep a clear separation in your mind between what data is stored and what data is being asked for.

Because of the deliberate flexibility in the way links can be stored, especially for GTINs, the "walking up the tree" function has the potential to miss out on some links. Therefore, the GS1-Conformant resolver spec includes a new section: 2.5.10 The GTIN hierarchy. If you're providing links for serialized items, you cannot include the consumer product variant and batch/lot for that link definition. You can, however, repose a link for the GTIN+Serial and then repose exactly the same link for the CPV and/or batch. All the flexibility is there but the way the data is stored needs to be managed carefully.