update all $ref to resolve in jsonschema.RefResolver

[lzehl]

The schemas are defined here on the GitHub. If people are downloading the schemas in order use them for example in a Python script the $ref need to resolve in the jsonschema.RefResolver. Solution:

• needs relative path?
• needs URL to GitHub schema file?

[lzehl]

Feedback from Stefan: should resolve using the link to the GitHub file (raw).

[jcolomb]

While technically easier to implement (one can get a part of the schema and get the other part directly via links to github), the link to the github file has some issues:

• dependence and persistence: what if microsoft turns github down: every link will go to a 404 (also if they decide to change the path to the raw files, actually).
• access: we saw last year that github closed its access to Iran and other countries. It was only for private repositories, but it might be different in the future. Similarly, it means that the schema will not resolve when offline.
• versioning: lets think we have version 3 and 4, links of version 3 should resolve to version 3 github files, while the master is at version 4: so links will need to be changed for each version ?

[lzehl]

All good points I agree. Not sure how to proceed though.

For versioning: in the best case I can imagine, the schemas are version dependent, but the $ref is rather independent of the version (schema should be at the same location).

Problem at the moment: $id is currently only an identifier, but does not lead to a downloadable file.

Not sure if indirect paths could be used as $ref to get to functionally usable schemas on a local machine.

I can't really find nice examples online, although I would have thought that this is a common problem...

[lzehl]

Feedback from Tom:

• create a definitions.json file at the top folder (e.g., under v1.0 for MINDS) containing the $ref to all schemas (introduce short strings for shorter $ref in the schemas later)
• use URI to GitHub raw files for $ref
• import definitions.json into each schema, and use this to reference to other schemas

I will follow this approach. The references in the definitions.json file are easier to maintain. If we stumble upon another solution we can modify it again.

[lzehl]

@UlrikeS91 : thanks for helping. Here what needs to be done (v1.0):

• use $id of schemas in definitions.json for referencing between schemas 1) add "defintions" to each schema (see activity for example) 2) change $ref in each schema to $id of definitions (see activity for example)

[UlrikeS91]

Hi @lzehl,

I added "definitions" to all schemata (each as it's own pull request). For some of them, I had some additional comments. Here a summary:

1. I noted down whenever a ref wasn't referring to the correct name of the schema. I don't know if this is important information, but it's an inconsistency. You need to be the judge on whether or not this is interesting. FYI most of them were replaced by the "#ref" anyway and schema names are correctly referenced in the definitions schema (I checked that).

2. MINDS "external" references: Some $ref's point to schemata that don't belong to the minds project. What should be done for those? Specifically, these are: Files (cscs), DOI (datacite) and Ontologies (ontology).

3. MINDS "internal" references without schemata: Some $ref's point to schemata that do belong to the minds project, but the schemata don't exist as part of v1. What should be done with those? Should the schemata be added to v1? Specifically, these are: parcellationatlas (minds) and parcellationregion (minds).

All remarks can be looked up here: #24, #33, #37, #43.

[lzehl]

@UlrikeS91 : thanks for all the updates! I'm going to take care of the remaining issues before I close this issue. These open issues include : update missing v1.0 schemas, basic check if references are working as expected

[skoehnen]

We should discuss the URL issue with the Knowledge Graph team, the best solution would be to get https://schema.hbp.eu up and running and deploy openMINDS there.

[lzehl]

This issue is in principle solved at the moment (cf. v1.0). I will close it and open a specific issue on the domain vs raw ref to schemas ($id vs `@type; raw vs domain ref)