Remove WebService and WebServiceVersion, replace with Service, Interface and InterfaceDependency #563

apdavison · 2025-09-29T08:52:22Z

openMetadataInitiative/openMINDS_computation#63

…ace and InterfaceDependency schemas.

lzehl · 2025-10-11T07:43:25Z

schemas/products/interface.schema.tpl.json

+      "type": "string",
+      "_instruction": "Enter a description of this interface."
+    },
+    "developer": {


This should be contributor according to our new plans. However we need to decide for one of the suggested options first #513

Also: should the developer not be part of the SoftwareVersion rather then on the Interface? even if code is only adjusted for the interface the software version will have to change (I though we wanted to conceptualize the Interface, and assume the code base is the software).

An interface is independent of the software that implements it. It is possible to have different software tools that implement the same interface.

So where is the code for the interface? we don't link it right now

The "definition" property links to a WebResource, which is generally a JSON file for REST APIs, or could be a formal human-readable document for other kinds of interface.

"author" would be a better term than "developer" (or rather, we should use the "author" role when we switch to "contributor")

lzehl · 2025-10-11T08:15:30Z

schemas/products/interface.schema.tpl.json

+        "controlledTerms:CommunicationProtocol"
+      ]
+    },
+    "custodian": {


Should most like be removed depending on the option decided in #513

lzehl · 2025-10-11T08:17:01Z

schemas/products/interface.schema.tpl.json

If interfaces are versioned they should in principle be handled as research products with research products versions. However I though we wanted to conceptualize the interface, and assume the code base is the software (making the interface explicitly not a research product with independent versioning). Otherwise the link to the code is missing that would allow for an independent versioning.

Question: If the same software version code base implements multiple versions of the same interface should we just treat them as equal variants with no preference? Then the version identifier actually just becomes just an internal identifier (no version specification needed, should be covered in definition and description). If there is a preference then we need to treat the interface as an independent product with versions I think (we may want to rethink the base elements of RP/RPV).

Do we need to adapt the naming here as well to CommunicationInterface ?

An interface is an independent product. There can be multiple pieces of software that implement a given interface; equally a given piece of software can implement multiple versions of a given interface. There is not necessarily any relationship between the interface version identifier and the software version identifier.

I'm not sure it should be considered a research product, however.

We should not be concerned about the semantics here. The research product can easily be renamed to something more general (would anyway make sense).

If it is an independent product it needs to be implemented in the same way as the others and it has to have then it's own code base.

However I understood this a bit differently. If we have code this is first and foremost a software. That software might have code for an interface as well or only holds the code for an interface, but the interface itself is just the concept of what the code is encoding.

@olinux can we please get your input here as well.
@apdavison maybe some examples would help for the expected cases?

For REST APIs, the interface definition is more like a metadata model. It is very common to use the OpenAPI standard (formerly Swagger), for which the interface definition is a single JSON file. I don't think we would register the openMINDS schema templates as software?

For non-REST APIs, the interface definition would probably be a human-readable, but not machine-readable document.

(Here is the definition for the KG Core API: https://core.kg.ebrains.eu/v3/api-docs/v3)

As another example, at one point I rewrote the neuromorphic Job Queue API from scratch (for maintainability and performance), using different Python libraries but keeping the same API.

lzehl · 2025-10-11T08:24:56Z

schemas/products/service.schema.tpl.json

+      "type": "string",
+      "_instruction": "Enter a description (or abstract) of this service."
+    },
+    "feature": {


Since Services are now broader this can't be only pointing to SoftwareFeatures

agreed, this needs some discussion.

lzehl · 2025-10-11T08:25:32Z

schemas/products/service.schema.tpl.json

+    "type"
+  ],
+  "properties": {
+    "custodian": {


should be removed depending on what we decide for #513

lzehl · 2025-10-11T08:27:39Z

schemas/products/service.schema.tpl.json

Needs to explicitly links to the legal entity providing the service (through #513 or specifically). We need to be able to filter services for this relation (custodian might in principle be also from somewhere else)

lzehl · 2025-10-11T08:30:17Z

schemas/products/interfaceDependency.schema.tpl.json

If in the software version the dependency can be to an interface or to a software version this can't be interface specific to interface but needs to be for interface or software version (failure impact would matter for both, no?)

I'm not sure I understand, can you clarify?

aims towards the issue I have with having a "dependency" and a "requirement" property in the software version. impact of failure is critical in both cases.

lzehl · 2025-10-11T08:31:10Z

schemas/products/softwareVersion.schema.tpl.json

SoftwareApplicationCategory list and SoftwareFeature list need to be revised I think

lzehl · 2025-10-11T08:32:27Z

schemas/products/softwareVersion.schema.tpl.json

      "minItems": 1,
      "uniqueItems": true,
-      "_instruction": "Enter all requirements of this software version.",
+      "_instruction": "Enter any requirements of this software version that are not listed under the 'dependency' property.",


Please explain difference between requirement and dependency. I don't see why we want to separate this. Could we think of a joint solution?

I did it this way for backwards compatibility and ease of migration. "requirement" is an array of strings, while "dependency" is an array of instances. My idea was to keep them both for v5, and then merge them for v6. Otherwise, we need to create SoftwareVersions for all strings in existing "requirement" properties during the v4-v5 migration.

I don't think we need to create SoftwareVersions. We can also say a property called "requirement" or "dependency" to embed ToolDependency (name TBD) which states the failureImpact and links to either an Interface, a SoftwareVersion, a File (to requirements.txt; TBD), a WebResource (to requirements.txt; TBD) or a Configuration (or a StringProperty).

Let's discuss this further

Remove WebService and WebServiceVersion, replace with Service, Interf…

bb8d7bc

…ace and InterfaceDependency schemas.

apdavison marked this pull request as draft September 29, 2025 08:52

apdavison added major update large workload or major update needed to complete v5.0 candidate labels Sep 29, 2025

This was referenced Sep 29, 2025

A new schema for Service, to replace WebService and WebServiceVersion openMetadataInitiative/openMINDS_computation#63

Closed

Schemas for a more fine-grained representation of services openMetadataInitiative/openMINDS_computation#62

Draft

Changes to the SoftwareVersion schema : linking to Interfaces

bcd5a59

lzehl requested changes Oct 11, 2025

View reviewed changes

apdavison changed the base branch from v5 to v6 November 7, 2025 17:02

Remove WebService and WebServiceVersion, replace with Service, Interface and InterfaceDependency #563

Are you sure you want to change the base?

Remove WebService and WebServiceVersion, replace with Service, Interface and InterfaceDependency #563

Uh oh!

Conversation

apdavison commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apdavison Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lzehl Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apdavison Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

apdavison Oct 14, 2025 •

edited

Loading

lzehl Oct 14, 2025 •

edited

Loading

apdavison Oct 14, 2025 •

edited

Loading