There is no actual bug, but I figured if the json is being validated, it would fail using the old URL so that would be an error. I can change the prefix, up to you.

Actually, it seems that the URLs were fixed in the commit you referenced but then broken again in 5ae5564

then broken again in 5ae5564

Good catch. That said, since the logic used to check if a specific document is associated with a specific schema account for both URL, it was not strictly a breaking change.

Regarding the schema reference, my understanding ¹² is that having the URL being valid is helpful but not strictly required as its purpose is to identify the document.

The application is then responsible to map that to actual schema and perform validation (which we don't do in Slicer).

Also worth noting that the @schema convention does not seems to be part of the standard ³⁴. There is also a draft proposal ⁵ for JSON reference, I am wonder if this means we should use $schema instead of @schema.

cc: @lassoan @fedorov

I can change the prefix

Changing to STYLE may be sensible indeed as runtime behavior is unchanged

Yes, the URL does not have to be an actual download URL. Actual server addresses, organization names, etc. (and therefore the download URL) may change, while the schema name is a unique identifier that is supposed to be unchanged forever.

is a unique identifier that is supposed to be unchanged forever

In this case I think they should not be URLs at all, because then it suggests that that's where the schema file can be found, which is not really expected.

I changed the prefix.

use $schema instead of @schema

This JSON validator also uses the convention with the dollar sign.

For reference, I am working on the issue SlicerRt/SlicerRT#218 and am trying to define the schema. This is why I started looking into this.

In this case I think they should not be URLs at all, because then it suggests that that's where the schema file can be found, which is not really expected.

That's a good point. https://raw.githubusercontent.com/qiicr/dcmqi/master/... is

1. so specific that it misleads people to believe it is an actual download URL, and
2. it is hard to keep it up-to-date (i.e., to actually make it a valid download URL).

If we change the schema URL then we should use a simpler URL, such as http://qiicr.org/schemas/.... It would be nice if we could even redirect to the actual file on github (it should be possible to do it with some web server redirect rules).

This is what Microsoft does, too. They use a schema names like https://developer.microsoft.com/json-schemas/... (see for example here), but the schema is actually stored on github, at https://github.com/Microsoft/json-schemas.

That's a good point. https://raw.githubusercontent.com/qiicr/dcmqi/master/... is

1. so specific that it misleads people to believe it is an actual download URL, and
2. it is hard to keep it up-to-date (i.e., to actually make it a valid download URL).

It is supposed to be the actual download URL, and from what I see in the dcmqi repository in https://github.com/QIICR/dcmqi/tree/master/doc/schemas, they are such downloadable URLs (unless I don't correctly interpret "downloadable URL" term). Can you clarify Andras? Do you mean it is hard to keep it up to date because of the commit hash tags and versioning of that file? Here's a potentially relevant discussion on schema versioning: json-schema-org/website#197.

Separately - the URL below is just invalid - it does not exist in any of the schemas that are available in dcmqi. Is this just a bug/typo that should be fixed?

Separately - the URL below is just invalid - it does not exist in any of the schemas that are available in dcmqi. Is this just a bug/typo that should be fixed?

The old (now invalid because it has been moved into the schemas folder) URL is allowed so that terminology files defined before this relocation of the json file are still accepted. You can see in this commit 56c9d32 that the new, valid URL was added, but the old one kept for this sort of backwards compatibility.

Thanks for the clarification, I missed it. It is unfortunate that I didn't think of this consequence while re-organizing that folder back in 2017.

It is supposed to be the actual download URL, and from what I see in the dcmqi repository in https://github.com/QIICR/dcmqi/tree/master/doc/schemas, they are such downloadable URLs

It is not a hard requirement to make a schema file avaialable at that URL on the public internet. Its primary role is to serve as a unique identifier. It is just a nice convenience feature that this URI may be used to obtain the schema (because then editors can automatically retrieve the schema and use it for documentation, syntax highlighting, validation checks, etc). But an application may have other mechanisms to obtain a schema file based on a schema URI. If you lose access over the download server and the schema URI does not download the schema file anymore, then it may still make sense to keep the same schema URI, especially if files with this schema are widely circulated.

In this specific case, I would not change https://raw.githubusercontent.com/qiicr/dcmqi/master/doc/anatomic-context-schema.json to https://raw.githubusercontent.com/qiicr/dcmqi/master/doc/schemas/anatomic-context-schema.json# because they are both bad. They are both too complex and they are not under QIICR's control. These github URLs will not disappear overnight, but github may change download URL syntax or may arbitrarily limit access for any reasons (security, bandwith use, geographical location, etc.) at any time. If the schema URI is ever changed again, it should be something like https://qiicr.org/schemas/... or https://schema.qiicr.org/..., and they can be redirected to github with redirection rules on the qiicr.org web server.

Something as simple as renaming the default branch of https://github.com/QIICR/dcmqi from master to main would make these https://raw.githubusercontent.com type links invalid.

For renaming a branch:

Although file URLs are automatically redirected, raw file URLs are not redirected.

https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch#about-renaming-branches

Indeed, you convinced me that the current approach is not good and is not reliable. I wish we had this discussion before those schemas were published!

but:

• since it is not clear if there is support for schema versioning, or established standard practice in JSON-Schema, even if we had a reliable way to dereference the link, it would not be possible to communicate the version of the schema that was used to create the specific document
• I am not convinced dereferencing via qiicr.org is more reliable/stable than the github download link, since it would be dependent on timely domain fee payments and maintenance

Maybe the way to do it, if one would do it over, would be to use versioned DOIs from a service like Zenodo https://zenodo.org/record/1256592 ?

While discussing this during the 2022-11-01 hangout, three competing priorities were identified:

• Stable schema URL (do not change often)
• URL allowing to download schema
• Simple schema URL with domain, version and name

We also discussed:

• Having schemas consolidated under https://slicer.org/schemas/ through the creation of github.com/Slicer/schemas
  • Would we apply the same approach to qiicr.org and have qiicr.org/schemas ?
  • ASsociated challenge related to maintenance of qiicr.org
• Reaching out to maintainer of dicom.nema.org

Considering that ensuring domain like qiccr.org maintain redirects for the foreseeable future, we are suggesting to:

• keep track of mapping between Schema URL as identifier and Schema URL as downloadable asset in a json file (conceptually similar DICOMExtensions.json)
• implement a C++ logic (that would be python wrapped) allowing to obtain the downloadable URL given a Schema URL as identifier

Next steps:

• Define where the mapping file would be located
• Consolidate existing json related logic and add support for schema validation

@cpinter @lassoan @pieper @thewtex @fedorov @jamesobutler How does that sound ?

Thank you for discussing it and the update about the potential solution! Yes it sounds good to me to have such a mapping.

I would close this issue, as we know that the updated URLs would not remain a valid URL forever (for example, it does not contain any version identifier). Maybe we could add a low-priority issue in the bugtracker to record the results of this discussion.

For reference, I am duplicating here a note I also added in the referenced issue:

The use of https://json-schema.org/ should also be investigated.