Skip to content

Conversation

@gouttegd
Copy link
Contributor

@gouttegd gouttegd commented May 1, 2025

Resolves [#439]

  • docs/ have been added/updated if necessary
  • make test has been run locally
  • [ ] tests have been added/updated (if applicable)
  • CHANGELOG.md has been updated.

If you are proposing a change to the SSSOM metadata model, you must

  • provide a full, working and valid example in examples/
  • provide a link to the related GitHub issue in the see_also field of the linkml model
  • provide a link to a valid example in the see_also field of the linkml model
  • run SSSOM-Py test suite against the updated model

This PR adds the new sssom_version set-level slot suggested in #439.

Contrary to the original suggestion of using a xsd:string-typed slot, it uses a enum-typed slot, with a new sssom_version_enum slot whose values represent the different versions of the specification (for now, the current 1.0 version and the upcoming 1.1). This should allow implementations to very easily check whether the version found in a set is one they support or not: if the value is not one of the “permissible values”, then either it’s a completely bogus value, or it’s one from a more recent version of the model than the one supported by the implementation.

It also add a new section in the documentation of the model, to explain how to deal with that sssom_version slot and, perhaps more importantly, to explain what are our promises regarding the evolution of the specification and backwards compatibility. That part may require further discussion before it is accepted, but it mostly follows the discussion that happened in #325. Basically, we promise never to break backwards compatibility across minor versions, which notably means that:

  • a new minor version may only add new slots or enum values, but never remove a slot or an enum value;
  • when adding a new slot in a minor version, that slot must be optional (possibly recommended, but never mandatory);
  • a new minor version cannot make mandatory a slot that was previously optional.

Any change to the spec that would make invalid a set that was previously valid, MUST happen in a new major version, for which we do not make any blanket promise of backwards compatibility.

Lastly, it adds a new meta model extension, Versionable, that can (and should) be used to mark any slot that has been added post-1.0.

gouttegd added 4 commits May 1, 2025 16:07
We add a new set-level slot to indicate the version that a set is
compliant with.

We also extend the metamodel with a new extension class ("Versionable")
that we use to explicitly mark a slot (such as the new `sssom_version`
slot) as having been introduced in a specific version of SSSOM.

Both the `sssom_version` slot and the `Versionable#added_in` annotation
uses a new enum, `sssom_version_enum`, to represent the version of the
SSSOM specification. For now, that enum contains only two allowed
values, representing the current published version of the spec (1.0) and
the upcoming version (1.1).

We update the documentation of the model to explain the versioning
scheme we use, what are our promises regarding backwards compatibility,
and how to deal with the new `sssom_version` slot.
Though the `predicate_type` slot had been in the schema since (AFAIK)
the beginning, it has only been added to the Mapping and MappingSet
classes *after* the publication of version 1.0 of the spec. That slot
should therefore be considered a novelty of the upcoming version 1.1,
since it was *not* usable in version 1.0.
Add a sample file illustrating the use of the `sssom_version` slot and
add a link to that file in the LinkML schema.
matentzn
matentzn previously approved these changes May 12, 2025
Introduce the versioning rules by making an *informative* reference to
the Semantic Versioning specification (https://semver.org/). This may
help developers that are already familiar with those principles.
@matentzn matentzn merged commit aef07ad into master May 13, 2025
4 checks passed
@matentzn matentzn deleted the sssom_version branch May 13, 2025 17:41
matentzn pushed a commit that referenced this pull request May 21, 2025
This PR updates the contributing guidelines to explain that changes to
the model in the 1.x branch should be ideally limited to adding optional
slots, and that added slots should be tagged with the `added_in`
annotation to indicate the version of the spec they will be introduced
in.

Arguably this could/should have been done as part of the PR in which the
`sssom_version` slot was introduced (#440).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants