Version numbering can cause potential clashes with previous documentation

[andremann]

I see that folders under /ver are like 0.1.0, however in the previous documentation we had 1.0 and 1.1 releases, which should be unambiguously identified as they have been used, e.g., for OpenAIRE dumps.
We could rebase the numbering here, perhaps, increasing the major version. Ideas?

[essepuntato]

The numbering with three digits (x.x.x) is actually following a particular specification, which is very appropriate when dealing with data modelling, i.e. Semantic Versioning: https://semver.org/. I would suggest to continue keeping it.

[andremann]

Sure, but my point is that in these new repos, the version numbering somehow is "younger" than what we left in the old docs.
We had released 1.1, so at least here we should start with 1.2 if not with 2.0 marking the introduction of JSON-LD.
This would help to trace the lineage of our past development. This also relates with something that @rduyme was saying in a mail exchange with me only.

[rduyme]

What is your approach @essepuntato for SPAR versioning and documentation I suppose only the owl is versionned along with documentation.
Shall we state that the only the json-ld context is versioned ? and the document is always "live" with some "since" statements or deprecated statement when needed ?

But :
There a very strong statement done by Silvio in #4
The impact, the way we go, will be that adopters like OSTrails will need Application Profiles for each entity API endpoints. They could simply be compatible with a json-ld context skg-if version
The reason, is that json-ld output can have many compatible forms, and OSTrails will have to specify them for all entities. Unless OSTrails dev gets crazy in implementation process. User don't have triple stores to just "get the json-ld", They need stable json for parsing => OSTrails will have another side documentation website, or OpenApi

OpenAPI is some kind of documenting API.
Application Profile is a model that we will use as input for developing API, specifically for defining the body of messages we send by doing GET POST, etc. So the SKG-IF will be materialised as an API that will be defined in form of OpenAPI specs. The API will be based on the Application Profile. OSTrails Tomasz

Ok why not ...

Unless.... we agree it would be better to have the definition of entity endpoints in SKG-IF repo, to ease adoption and centralized documentation. A structure that could be reused by other projects like GraspOS.

When we define "mandatory" or "optional" in html documentation what is it for ?