search

DACCS-Climate / Marble-node-registry

The central node registry of the DACCS network
0 stars 1 forks source link

Improve schema locations for services #38

Closed fmigneault closed 6 months ago

fmigneault commented 7 months ago

All components of https://github.com/bird-house/birdhouse-deploy that currently provide the "service" JSON file use the reference: 

{
  "$schema": "https://raw.githubusercontent.com/DACCS-Climate/Marble-node-registry/main/node_registry.schema.json#service"
}

The specified #service is wrong, as there is no "service" key at the root of this document. Most probably, the intention is to point at the definition nested under patternProperties->[regex]->properties->services->items. However, because of the use of a regex and the very nested definition position in the schema, the anchor cannot be easily defined.

The schema should be reworked to move this definition under definitions/service, and use $ref: #/definitions/service in the nested array. The current "service" definition does provide $anchor: service, therefore the schema can be resolved using a schema validator, but this kind of definition is not as common as the #/definitions/service approach. The $anchor method is less supported than the link reference by property keys.

The instances could then use the schema correctly using: 

{
  "$schema": "https://raw.githubusercontent.com/DACCS-Climate/Marble-node-registry/main/node_registry.schema.json#/definitions/service"
}
mishaschwartz commented 7 months ago

The current "service" definition does provide $anchor: service, therefore the schema can be resolved using a schema validator

This is the intended use and validators since version 4 support this syntax fully.

Is there a different use-case for this schema that does not support the anchor tags?

fmigneault commented 7 months ago

I think it is an improvement more from a user point of view that functionality wise. Unless you know to look for $anchor somewhere in that big JSON schema, it is not obvious where this reference is defined, while the #/definitions/service (or #/$defs/service according to https://json-schema.org/understanding-json-schema/structuring#defs) approach is self-explanatory. It also makes it obvious that the nested service definition is intended to be reused by external sources. The JSON-schema's own documentation also mention that $anchor is a less common method (https://json-schema.org/understanding-json-schema/structuring#anchor).

Note that if the schema was moved under $defs/service the $anchor could still be provided as a shortcut, but the long form would be available as well.

mishaschwartz commented 7 months ago

Note that if the schema was moved under $defs/service the $anchor could still be provided as a shortcut, but the long form would be available as well.

Ok sure. I'm not opposed to this