A first look at Resolver CE's new data entry format

[nicklansley]

Nick Lansley writes:

Hello!

One big cause of frustration for Resolver CE users was the large, unwieldy, and confusing data entry format for v1/v2 versions of Resolver!

Although it started simply enough, the addition of all those 'default' flags turned an 'OK' data entry format into a confusing nightmare. And yes, you can blame me for that design - It worked but you know you've left the track of simplicity when even developers are getting confused!

No more! Let's look the new data entry format supported by Resolver CE v3.0 API:

[
  {
	"anchor": "/01/09506000134376",
	"itemDescription": "Dal Giardino Medicinal Compound 50 x 200mg",
	"qualifiers": [
	  { "10": "LOT_123"},
	  { "21": "SERIAL_456"}
	],
	"defaultLinktype": "pip",
	"links": [
	  {
		"linktype": "epil",
		"href": "https://dalgiardino.com/medicinal-compound/pil.html",
		"title": "Information for patients",
		"type": "text/html",
		"hreflang": ["en"]
	  },
	  {
		"linktype": "pip",
		"href": "https://dalgiardino.com/medicinal-compound/",
		"title": "Product information",
		"type": "text/html",
		"hreflang": ["en"],
                "context": ["und","marketing"]
	  },
	  {
		"linktype": "pip",
		"href": "https://dalgiardino.com/medicinal-compound/index.html.ja",
		"title": "Product information",
		"type": "text/html",
		"hreflang": ["ja"]
	  }
	]
  }
]

Let's compare it to the original input with the same data:

{
            "identificationKeyType": "01",
            "identificationKey": "09506000134376",
            "itemDescription": "Dal Giardino Medicinal Compound 50 x 200mg",
            "qualifierPath": "/10/LOT_123/22/SERIAL_456",
            "active": true,
            "responses": [
                {
                    "linkType": "gs1:epil",
                    "ianaLanguage": "en",
                    "context": "und",
                    "mimeType": "text/html",
                    "linkTitle": "Information for patients",
                    "targetUrl": "https://dalgiardino.com/medicinal-compound/pil.html",
                    "defaultLinkType": false,
                    "defaultIanaLanguage": true,
                    "defaultContext": true,
                    "defaultMimeType": true,
                    "fwqs": true,
                    "active": true
                },
                {
                    "linkType": "gs1:epil",
                    "ianaLanguage": "en",
                    "context": "xx",
                    "mimeType": "text/html",
                    "linkTitle": "Information for patients",
                    "targetUrl": "https://dalgiardino.com/medicinal-compound/pil.html",
                    "defaultLinkType": false,
                    "defaultIanaLanguage": true,
                    "defaultContext": true,
                    "defaultMimeType": true,
                    "fwqs": true,
                    "active": true
                },
                {
                    "linkType": "gs1:pip",
                    "ianaLanguage": "en",
                    "context": "xx",
                    "mimeType": "text/html",
                    "linkTitle": "Product information",
                    "targetUrl": "https://dalgiardino.com/medicinal-compound/",
                    "defaultLinkType": true,
                    "defaultIanaLanguage": true,
                    "defaultContext": true,
                    "defaultMimeType": true,
                    "fwqs": true,
                    "active": true
                },
                {
                    "linkType": "gs1:pip",
                    "ianaLanguage": "en",
                    "context": "marketing",
                    "mimeType": "text/html",
                    "linkTitle": "Product information",
                    "targetUrl": "https://dalgiardino.com/medicinal-compound/",
                    "defaultLinkType": true,
                    "defaultIanaLanguage": true,
                    "defaultContext": true,
                    "defaultMimeType": true,
                    "fwqs": true,
                    "active": true
                },
                {
                    "linkType": "gs1:pip",
                    "ianaLanguage": "ja",
                    "context": "xx",
                    "mimeType": "text/html",
                    "linkTitle": "Product information",
                    "targetUrl": "https://dalgiardino.com/medicinal-compound/index.html.ja",
                    "defaultLinkType": false,
                    "defaultLanguage": true,
                    "defaultContext": true,
                    "defaultMimeType": true,
                    "fwqs": true,
                    "active": true
                }
            ]
        }

So, what just happened?

1. identificationKeyType and identificationKey have disappeared. Instead, a new anchor property has appeared that holds the URI stem of the GS1 Digital Link identifier.
2. qualifierPath has been replaced by a qualifiers array that contains one or more relevant qualifiers for this entry. The qualifiers can be in any order, although Resolver CE will respond to them according to GS1 standards - for example, a serial number is subject to a particular lot number if both are included in the array. Template variables can be used as qualifier values as before.
3. defaultLinkType, defaultLanguage, defaultContext, and defaultMimeType have completely disappeared. Instead, there is a new property defaultLinkType specified towards the top of the entry that signifies which link type is the default. The other three defaults are inferred from your data - no need to explicitly state them.
4. ianaLanguage has become hreflang, which more effectively reflects its purpose: 'the language of the link reference'. It has been expanded to optionally include locale/territory, allowing Resolver to read the 'accept-language' header from a web client and act on it when choosing an appropriate link. Examples include 'en', 'en-GB', 'en-US', 'fr-FR'. A single hreflang property is an array of one or more language-and-optional-locale entries suitable for the link. If the language is not applicable, we've replaced 'xx' with 'und' (for undefined) as this is a standards-compliant value.
5. context has become an optional array of strings. Some enterprising developers press-ganged context to be used for 'locale'. Fortunately, hreflang takes over this important consideration, leaving context to return to being used to provide filtered contexts for choosing the link, chosen by the optional query string element 'context=' added to the end of the GS1 Digital Link URL by a smart web client. If you only used context 'xx' before then there is no longer supply context at all. If some entries apply to both particular contexts and 'no context' then you can use values like "context": ["marketing", "und"] where 'und' is 'undefined' just like 'hreflang' uses it.
6. active has disappeared. This property was part of an original design to enable links to be available or hidden. This property was never used as end-users never needed this functionality. Why put the link in Resolver CE if you don't want it public?!
7. Similarly, fwqs has also disappeared. 'Forward Query Strings' was included in v1.0 of Resolver CE because one of our earliest tester's websites kept crashing if it received query strings it was not expecting! This effect has never been seen since and is never used. It's time we let it go.

You may already be familiar with 'linkset' output from Resolver CE if you append 'linktype=all' to the GS1 Digital Link URL request, and add request header 'accept-language: application/json' or 'accept-language: application/linkset+json' to the request. If so, you may look at the data entry input format above and conclude that it is similar? No coincidence! The data entry is a simplified form of the linkset output. Let's look at the same data in the linkset output format:

{
  "linkset": [
	{
	  "anchor": "https://id.gs1.org/01/09506000134376",
	  "itemDescription": "Dal Giardino Medicinal Compound 50 x 200mg",
	  "https://gs1.org/voc/defaultLink": [
		{
		  "href": "https://dalgiardino.com/medicinal-compound/",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true
		}
	  ],
	  "https://gs1.org/voc/epil": [
		{
		  "href": "https://dalgiardino.com/medicinal-compound/pil.html",
		  "title": "Information for patients",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"en"
		  ],
		  "context": [
			"und"
		  ]
		}
	  ],
	  "https://gs1.org/voc/pip": [
		{
		  "href": "https://dalgiardino.com/medicinal-compound/",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"en"
		  ]
		},
		{
		  "href": "https://dalgiardino.com/medicinal-compound/index.html.ja",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"ja"
		  ]
		},
		{
		  "href": "https://dalgiardino.com/medicinal-compound/",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"en"
		  ],
		  "context": [
			"und","marketing"
		  ]
		}
	  ],
	  "https://gs1.org/voc/defaultLinkMulti": [
		{
		  "href": "https://dalgiardino.com/medicinal-compound/",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"en"
		  ]
		},
		{
		  "href": "https://dalgiardino.com/medicinal-compound/index.html.ja",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"ja"
		  ]
		},
		{
		  "href": "https://dalgiardino.com/medicinal-compound/",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"en"
		  ]
		},
		{
		  "href": "https://dalgiardino.com/medicinal-compound/index.html.ja",
		  "title": "Product information",
		  "fwqs": true,
		  "public": true,
		  "type": "text/html",
		  "hreflang": [
			"ja"
		  ]
		}
	  ]
	}
  ]
}

Well... if you want to, you can upload fully formed linkset data as data entry!

There is some greater complexity involved in authoring linksets (and Resolver CE will thoroughly check you have it perfect), thus the simplified version is easier to understand. What is important is that the linkset is the internal data structure stored in the document database. If you upload the simplified version, then it will be authored for you.

That's a first look at the new data entry format for GS1 Digital Link Resolver CE v3.0 - comments welcome!

If you a CSV data uploader, all good - the UI will still be there to convert your CSV documents and upload them for you.

Nick Lansley

[john-doherty]

Much better 👌🏽

Are these changes backwards compatible? - in other words, will existing integrations continue to work?

[nicklansley]

Thanks John! v3.0 is a breaking change but will include data entry accepting the old format - just not guaranteed on day 1.

That's because the v3.0 will spend a short time in 'release-candidate' mode so that new and existing users can test the latest version. This gives me time to understand and develop 'transition' tools from v2.x to v3.0 based on feedback, including maintaining backwards compatibility where needed.

[philarcher]

Delighted to see these changes, @nicklansley. Thank you. This feels good!

Just two nit picks:

"linktype": "epil",

should be "gs1:epil", i.e. the namespace is important. I admit that there's no formal way here to define the namespace, so one could argue it's moot, and, yes, we probably should work to introduce to the Linkset RFC but for now we should just make sure we use the namespace consistently.

And this looks questionable?

"context": [
"und","marketing"
]

i.e. keeping the "und" value as well as "marketing"?

Oh, one more, sorry...

if you append 'linktype=all'

That's deprecated as of GS1-Conformant resolver 1.0.0 in favour of linkType=linkset and we should make it clear that if the HTTP Accept header is set to application/linkset+json then you get the linkset, whether or not the linkType param is set to linkset (or all for backwards compatibility).