💡 [Feature] Provide component service version

[fmigneault]

Description

All components that provide a service definition to be reported in /services of the platform should provide a version field when available.
This way, the /services endpoint would provide a centralized view of available/deployed service versions.

The current schema definition (https://github.com/DACCS-Climate/Marble-node-registry/blob/7fc410a0fa545c11540805db0adf2d7ad576fbf6/node_registry.schema.json#L83) does not disallow adding version, but it could add it explicitly using the same definition (https://github.com/DACCS-Climate/Marble-node-registry/blob/7fc410a0fa545c11540805db0adf2d7ad576fbf6/node_registry.schema.json#L145) as used by the nodes.

[mishaschwartz]

If we do this we need to have some concept of what a version means for a specific component or service first.

Some things to consider:

What is the value of the version here? The version of the docker image? What if we make changes to the default configuration for a service in this repo that doesn't require a change to the docker container? What if we start using a different image for a given service?

[fmigneault]

I would leave it up to the specific component to define what version applies. In many cases, the docker container's tag/version would be directly the version of the service, but it does not strictly need to be the case.

The idea came from recent discussions with participants of the OGC OSPD effort. There needs to be some kind of "service and versioning listing" details where information about the specific versions of services and platform employed can be obtained. I naturally thought about our /version and /service endpoints to fulfill that requirement, but noticed respective versions of services were not available. A user needs to somehow know where those versions are available, or hope that the service provides a links entry with the version relation type. Hence, this issue.

[mishaschwartz]

Another thing we should think about. We don't actually have anything that indicates a unique name for a give service. We have the "name" field but that could be any value.

For example, let's say that a node wants to deploy two versions of finch, an older one and a newer one. They can call one old-finch and one new-finch. The service definition doesn't have anything that makes it clear that these two services are the same, just with different versions.

We could introduce an "id" field which could be used with the "version" field to uniquely identify which service we're referring to and which version, no matter what the name is. So for the example above we'd have something like:

"services": [
  {
    "name": "old-finch",
    "id": "finch",
    "version": "1.0",
    ....
  },
  {
    "name": "new-finch",
    "id": "finch",
    "version": "2.0",
    ....
  }
]

[fmigneault]

I'm not sure if I see the use case. If the 2 versions are deployed at the same time, they should have a different URI for their service link anyway. Interacting with either would imply that the user is looking for different capabilities provided by each one. Beside the name, there might be very little that actually "relates" them. Maybe consider related/predecessor-version/successor-version link combinations instead?

[mishaschwartz]

My point is that we're adding a version number without having a clear definition of what it is a version of. Maybe this is a more clarifying example:

"services": [
  {
    "name": "some-arbitrary-service-name",
    "id": "finch",
    "version": "1.0",
    "links": [
        {
           "rel": "service",
           "href": "http://example.com/some-arbitrary-service-name"
        },
        {
           "rel": "service-doc",
           "href": "http://some-custom-documentation.example.com/"
        }
    ]
    ....
  }
]

Without the "id", we don't know that the service is some version of "finch", the "name" can be anything.

Another option is to use the "version" key to specify both the id and version (similar to a docker tag):

"version": "finch:1.0"

[fmigneault]

Ok. I get what you meant now.

I'm not sure I like id for this kind of use, since it usually implies a "unique" constrain, but here we could have multiple "finch" versions. In a similar way, version is usually expected to be some semver string pattern, so finch:1.0 isn't quite right.

In a way, even "finch" here could point to relatively anything. One needs to have the context of birdhouse to guess what it refers to, and even then, is it https://github.com/bird-house/finch or one of its forks?

Maybe the best would be to have explicit references as follows. The "id" would be the literal docker reference.

{
  "links": [
    {
      "rel": "service-meta",
      "href": "registry.hub.docker.com/birdhouse/finch:version-0.12.0",
      "type": "application/vnd.oci.image.index.v1+json"
    },
    {
      "rel": "service-desc",
      "href": "https://github.com/bird-house/finch",
      "type": "text/html"
    }
  ]
}

[mishaschwartz]

Ok that makes sense. Would we then require the service-meta link instead of a version key?

Also would type be a more appropriate rel value here?

[fmigneault]

I think rel: type is more to represent the context of the item's type instead of a "polymorphism identifying type". In a way type could point back at https://raw.githubusercontent.com/DACCS-Climate/Marble-node-registry/main/node_registry.schema.json#service, but that is redundant since $schema is already specified. For the "identifying type", a types property as discussed in DACCS-Climate/Marble-node-registry#39 seems more appropriate.

I think the version would be relevant as the semver value only, but that value has to take into consideration the context of service-meta.