Change ID format from "uri" to "uri-reference"

[kstreeter]

As we have continued to build tooling around XDM, we have encountered some variation in how strict tools are about validating or generating code for properties with a format of "uri". Some tools allow for both relative URI references as well as absolute ones, while others only accept complete URIs in absolute form.

It appears this variation stems from changes made between JSON Schema draft 4 and draft 6. In draft 4, the specification was not clear about whether format "uri" was intended to be absolute or not. Tools went different direction on this, and the issue was addressed in draft 6. Unfortunately, they chose a method that was not really backwards compatible, designating format "uri" as strictly an absolute URI, and adding a "uri-reference" to encompass the more expansive form.

A particular place where we use format "uri" is for describing the JSON-LD construct @id. In JSON-LD, @id is allowed to be a relative reference. So our use of format "uri" (under draft 6, which we have adopted in XDM) has overly constrained that definition.

We have a number of tools and components that assume it is acceptable to use the relative URI form in @id fields, based on the JSON-LD definition. We are encountering issues in some toolchains that fully honor the definition of format "uri", and reject data that uses the relative form.

Since our use of @id is intended to align with its definition in JSON-LD, I would like to propose that we fix our mapping for @id to use format "uri-reference" rather than format "uri". This will fix the tool chain issues, and bring us closer in sync with JSON-LD.

What are the schemas that are affected by the issue

All

What are examples of products that are impacted by the issue

All

[kstreeter]

@lrosenthol @chrisdegroot @ogoldman please let me know what you think of this proposal.

This should not be a breaking change from a schema perspective (we are relaxing constraints), but it will impact tooling that generates code (POJOs, etc) from schema definitions. If we adopt this, I suggest we migrate definitions on a case-by-case basis after considering impact.

[cdegroot-adobe]

Actually, after reading the URI spec a bit more I get that uri-reference is either an absolute of reference.

Approve for sure.

[ogoldman]

Fine w/ me.

[cdegroot-adobe]

@lrosenthol - can you approve this and move forward with a PR?

[lrosenthol]

I agree - this looks good to me.

So do we need to then make this change in every schema, @cdegroot-adobe ?

[cdegroot-adobe]

@lrosenthol - I would prefer we do it everywhere. @jwen-adobe can you look at how to do this please? I will be away for several weeks so I do not have the cycles.

[jwen-adobe]

@cdegroot-adobe When u say everywhere, that means include those non experience platform xdm schemas as well like assets etc.? And for @id field only?

[kstreeter]

Hey folks, coming back to this issue as validation issues have been raised again by some teams. It seems like we are in agreement on making this fix. My preference would be to do it in a single PR across the repo. And also update the docs. @jwen-adobe do you think you could whip up a script to do this?

[jwen-adobe]

@kstreeter Some @id field does not have format associated, do u want to add a format for that case as well? And this change is for all the schemas which include non experience related?

[jwen-adobe]

unless otherwise, I will create a script to change those schemas contain @id with format "uri" and change their format to "ur-reference"

[lrosenthol]

Looking good here...