spdx-3-model icon indicating copy to clipboard operation
spdx-3-model copied to clipboard
verified publisher icon spdx

Marking deprecation in a machine-readable way

Open bact opened this issue 10 months ago • 4 comments

Background

  • As the spec evolves, there should be a way to signal a deprecation of a class/datatype/enum/property.

    • See #969 for example of a deprecation

  • It will be ideal if we can mark the deprecation inside a Markdown file of that class/datatype/enum/property in a way that allow both human and machine to read.

  • We may also like to be able to mark the spec version that it starts depreciated and the spec version that it will be longer supported.

    • Also an equivalent class/property recommended to be used instead.

  • A validator may use this information to provide relevant warnings / suggestions.

Proposals

  • One possible way to do this is by putting the deprecation information under the Metadata heading.

  • JSON Schema has a "deprecated" boolean property in its 2019-09 draft: https://json-schema.org/understanding-json-schema/reference/annotations

  • Could something similar to deprecatedVersion and obsoletedBy properties in licensing be used?

Examples

  • Example of deprecation info, with "deprecated since" info, (for human to read) in SPDX 2.2.x: https://github.com/spdx/spdx-spec/pull/521/files
  • Example of deprecated property in JSON Schema: https://github.com/spdx/spdx-spec/pull/841/files
  • Enhancement request for information indicating deprecated classes and properties: https://github.com/spdx/spdx-spec/pull/303#pullrequestreview-403692708

bact avatar Feb 12 '25 21:02 bact

OWL also has a deprecated value: https://www.w3.org/TR/2012/REC-owl2-syntax-20121211/#a_deprecated

I like the idea of adding deprecated to the metadata. I would suggest that the spec-parser add the deprecated OWL property to the URI for the class or property being deprecated. The code generators could then pick this up and add it to the language bindings and additional schemas.

goneall avatar Feb 13 '25 19:02 goneall

There is also: https://www.w3.org/TR/owl-ref/#Deprecation

JPEWdev avatar Feb 13 '25 22:02 JPEWdev

https://github.com/JPEWdev/shacl2code/pull/46 adds support for owl:DeprecatedClass and owl:DeprecatedProperty to shacl2code and the generated bindings. If someone can explain how the owl:deprecated annotation is supposed to work, I can add that also; I couldn't figure it our from reading the description and there aren't any example I could find

JPEWdev avatar Feb 14 '25 20:02 JPEWdev

ExpandedLicensing has these three properties:

listVersionAdded could be generalised as versionAdded to use with class/property/individual

bact avatar Feb 25 '25 12:02 bact

I believe this is mostly resolved with https://github.com/JPEWdev/shacl2code/pull/46 - @bact if there are additional suggestions, pls. open a separate PR

goneall avatar Nov 14 '25 23:11 goneall

@goneall We need an agreed keyword in the Markdown that the spec-parser can recognize and feed it further to the shacl2code.

  1. Human put deprecation info in Markdown
  2. spec-parser convert deprecation info to RDF/OWL
  3. schacl2code picks the RDF/OWL for bindings

We only have (3) now.

But keep this closed, I will structured the proposal again and put it as new PR in the future.

bact avatar Nov 15 '25 08:11 bact

@goneall We need an agreed keyword in the Markdown that the spec-parser can recognize and feed it further to the shacl2code.

  1. Human put deprecation info in Markdown
  2. spec-parser convert deprecation info to RDF/OWL
  3. schacl2code picks the RDF/OWL for bindings

We only have (3) now.

But keep this closed, I will structured the proposal again and put it as new PR in the future.

Thanks @bact for structuring a proposal for this.

goneall avatar Nov 16 '25 03:11 goneall