deprecated: Mark isSequenceOf as deprecated and document Segment …

…as alternative (DEV-3455) (#3161)

Co-authored-by: Marcin Procyk <marcin.procyk@dasch.swiss>

docs/02-dsp-ontologies/knora-base.md

@@ -587,6 +587,26 @@ is part of another resource needs to have a property `kb:seqnum` or a subpropert
 client can then use this information to leaf through the parts of the compound resource (p.ex. to leaf through the pages
 of a book like in [this](../01-introduction/example-project.md#resource-classes) example).
 
+#### Segment
+
+DSP-API supports the creation of segment resources. 
+A segment is a part of a resource which has a temporal extent; 
+the segment is defined by a start and end time relative to the resource. 
+Segments are modelled as resources of type `kb:Segment`, 
+having the properties `kb:isSegmentOf`, a [LinkValue](#linkvalue) pointing to the resource the segment is part of,
+and `kb:hasSegmentBounds`, a [IntervalValue](#intervalvalue) representing the temporal extent of the segment.
+However, `kb:Segment` is "abstract" and cannot be used directly in data. 
+Segments may have a comment attached to them through `kb:hasComment`.
+
+There are two concrete subclasses of `kb:Segment`: `kb:AudioSegment` and `kb:VideoSegment`.
+`kb:AudioSegment` has the property `kb:isAudioSegmentOf`, which points to an [AudioRepresentation](#representations),
+`kb:VideoSegment` has the property `kb:isVideoSegmentOf`, which points to a [MovingImageRepresentation](#representations). 
+Both use the `kb:hasSegmentBounds` property directly.
+
+It is possible to create subclases of `kb:AudoSegment` and `kb:VideoSegment` to add additional properties, 
+but this is discouraged and may not be supported in future versions of DSP-API. 
+Instead, instances of `kb:Annotation` pointing to the segment should be used to add additional information.
+
 
 ### Text with Standoff Markup
 

docs/10-migration-guides/index.md

@@ -0,0 +1,55 @@
+# Overview
+
+Generally, DSP-API is designed to be backward compatible.
+Whenever a new major version of DSP-API is released,
+the existing data is migrated to the new version automatically.
+The public Rest API is also stable and should remain backward compatible.
+
+However, when a feature appears not to be used,
+or if there are urgent technical reasons to change the API,
+we may decide to release breaking changes.
+In these instances, we try to provide a migration guide,
+in case some project or application is affected by the change.
+
+If you experience any issues with the migration,
+please contact us via the [DaSCH Help Center](https://www.dasch.swiss/help-center).
+
+## Migration Guides
+
+<!--- 
+For the following list, I propose the structure `vXX to vYY: Title` 
+or if the version is not yet known: `Planned: Title`
+--->
+
+### Planned: Removal of `knora-base:isSequenceOf` and `knora-base:hasSequenceBounds`
+
+If you have used `knora-base:isSequenceOf` and `knora-base:hasSequenceBounds` in your data,
+this should be replaced by `knora-base:isAudioSegmentOf` or `knora-base:isVideoSegmentOf` respectively,
+and `knora-base:hasSegmentBounds`.
+
+The issue with that is that these properties are only allowed
+on resources of type `knora-base:AudioSegment` and `knora-base:VideoSegment`,
+whereas previously `knora-base:isSequenceOf` could be added to any `knora-base:Resource`.
+This means that you will have to change the type of the resources that you have been using
+to be of type `knora-base:AudioSegment` or `knora-base:VideoSegment`.
+
+## Deprecation Warnings
+
+<!---
+These items should be removed, once the feature has been removed from the codebase.
+Then, only the migration guides should be kept.
+--->
+
+### `isSequenceOf` and `hasSequenceBounds`
+
+With the introduction of the new `Segment` concept in DSP-API v30.11.0,
+the previously existing properties `knora-base:isSequenceOf` and `knora-base:hasSequenceBounds`
+have been deprecated and will be removed in a future version.
+
+If you are creating a new ontology,
+please do not use these properties anymore.
+Instead, use the newly introduced Segment type.
+
+More information on Segments can be found [here](../02-dsp-ontologies/knora-base.md#segment).
+
+

mkdocs.yml

@@ -105,6 +105,7 @@ nav:
   - Frequently Asked Questions: 08-faq/index.md
   - Release Notes:
       - Changelog: 09-release-notes/index.md
+  - Migration Guides and Deprecations: 10-migration-guides/index.md
 
 plugins:
   - include-markdown