Better link to TimeRange definition

Makes the definition of a TimeRange more prominent by referencing it in all the schemas that use it. Also adds links from the descriptions in rendered docs.
bbc · Dec 20, 2023 · f0fdffd · f0fdffd
1 parent b557c46
commit f0fdffd
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 61 deletions.
diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml
@@ -163,7 +163,7 @@ paths:
           description: Filter on flows that overlap the given time range.
           schema:
             default: _
-            $ref: '#/components/schemas/timerange_type'
+            $ref: 'schemas/timerange.json'
         - name: format
           in: query
           description: Filter on flow format.
@@ -251,7 +251,7 @@ paths:
           description: Limit the returned available segment time range to this time range.
           schema:
             default: _
-            $ref: '#/components/schemas/timerange_type'
+            $ref: 'schemas/timerange.json'
       responses:
         "200":
           description: ""
@@ -546,7 +546,7 @@ paths:
             X-Paging-Timerange:
               description: Identifies the time range for the returned data set.
               schema:
-                $ref: '#/components/schemas/timerange_type'
+                $ref: 'schemas/timerange.json'
             X-Paging-Count:
               description: The number of items in the returned data set.
               schema:
@@ -627,7 +627,7 @@ paths:
           description: Only delete flow segments that are completely covered by the given time range.
           schema:
             default: _
-            $ref: '#/components/schemas/timerange_type'
+            $ref: 'schemas/timerange.json'
         - name: object_id
           in: query
           description: Filter on object identifier.
@@ -695,15 +695,15 @@ paths:
             X-Paging-Next-Timerange:
               description: The 'timerange' to use in the Post data to get the next page. If 'X-Paging-Next-Timerange' is not present then it is the last page.
               schema:
-                $ref: '#/components/schemas/timerange_type'
+                $ref: 'schemas/timerange.json'
             X-Paging-Limit:
               description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation.
               schema:
                 type: integer
             X-Paging-Timerange:
               description: Identifies the time range for the returned data set.
               schema:
-                $ref: '#/components/schemas/timerange_type'
+                $ref: 'schemas/timerange.json'
             X-Paging-Count:
               description: The number of items in the returned data set.
               schema:
@@ -789,35 +789,6 @@ components:
       title: UUID
       pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
       type: string
-    timestamp_type:
-      title: Timestamp
-      description: |
-        A signed nanosecond resolution timestamp represented as <sign><seconds>:<nanoseconds>. The intended
-        interpretation of the value is assumed to be defined elsewhere.
-
-        E.g.
-        * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0".
-        * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC.
-
-        Details of the format can be found in the Timestamp class provided in the Python
-        [mediatimestamp](https://github.com/bbc/rd-apmm-python-lib-mediatimestamp) library.
-      type: string
-      pattern: '^-?\d+:\d+$'
-    timerange_type:
-      title: TimeRange
-      description: |
-        A time range of timestamps. It is represented using a pair ot timestamps with inclusivity and exclusivity markers.
-
-        E.g.
-        * "[0:0_10:0)" represents 10 seconds of media starting at timestamp "0:0" and ending before "10:0".
-        * "(5:0_" represents a time range starting after "5:0" and to eternity.
-        * "[1694429247:0_1694429248:0)" is a 1 second TAI time range starting at 2023-09-11T10:46:50.0Z UTC.
-        * A "[" or "]" indicates that bound is inclusive, and a "(" or ")" indicates that bound is exclusive.
-
-        Details of the format can be found in the TimeRange class provided in the Python
-        [mediatimestamp](https://github.com/bbc/rd-apmm-python-lib-mediatimestamp) library.
-      type: string
-      pattern: '^(\[|\()?(-?\d+:\d+)?(_(-?\d+:\d+)?)?(\]|\))?$'
     flowformat:
       title: Flow Format
       description: identifies the flow format using a URN string.
@@ -854,7 +825,7 @@ components:
       in: query
       description: Return only the results in the time range specified.
       schema:
-        $ref: '#/components/schemas/timerange_type'
+        $ref: 'schemas/timerange.json'
     trait_timerange_paged_limit:
       name: limit
       in: query

diff --git a/api/schemas/deletion-request.json b/api/schemas/deletion-request.json
@@ -21,14 +21,12 @@
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
         },
         "timerange_to_delete": {
-            "description": "The time range of FlowSegments to be deleted in this request.",
-            "type": "string",
-            "pattern": "[\\[\\(]\\d*:\\d*_\\d*:\\d*[\\]\\)]"
+            "description": "The time range of FlowSegments to be deleted in this request, as described by the [TimeRange](../schemas/timerange#top) type",
+            "$ref": "timerange.json"
         },
         "timerange_remaining": {
-            "description": "The time range of FlowSegments not yet deleted by this request.",
-            "type": "string",
-            "pattern": "[\\[\\(]\\d*:\\d*_\\d*:\\d*[\\]\\)]"
+            "description": "The time range of FlowSegments not yet deleted by this request, as described by the [TimeRange](../schemas/timerange#top) type",
+            "$ref": "timerange.json"
         },
         "delete_flow": {
             "description": "Whether the Flow should be deleted once the timerange has been",

diff --git a/api/schemas/flow-core.json b/api/schemas/flow-core.json
@@ -82,9 +82,8 @@
       "type": "integer"
     },
     "timerange": {
-      "description": "The time range of samples available in the flow.",
-      "type": "string",
-      "pattern": "^(\\[|\\()?(-?\\d+:\\d+)?(_(-?\\d+:\\d+)?)?(\\]|\\))?$"
+      "description": "The time range of samples available in the flow, as described by the [TimeRange](../schemas/timerange#top) type",
+      "$ref": "timerange.json"
     }
   }
 }
diff --git a/api/schemas/flow-segment.json b/api/schemas/flow-segment.json
@@ -24,29 +24,24 @@
       "type": "string"
     },
     "ts_offset": {
-      "description": "The timestamp offset between the timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set.",
-      "type": "string",
-      "pattern": "^-?\\d+:\\d+$"
+      "description": "The timestamp offset between the timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative",
+      "$ref": "timestamp.json"
     },
     "range": {
-      "description": "The timerange from the first media unit in the segment to the last (exclusive end if exclusive_last_ts is true).",
-      "type": "string",
-      "pattern": "^(\\[)?-?\\d+:\\d+(_-?\\d+:\\d+)?(\\]|\\))?$"
+      "description": "The timerange from the first media unit in the segment to the last (exclusive end if exclusive_last_ts is true), as described by the [TimeRange](../schemas/timerange#top) type",
+      "$ref": "timerange.json"
     },
     "first_ts" : {
-      "description": "The timestamp of the first media unit in the segment (which may not be the first unit in the object).",
-      "type": "string",
-      "pattern": "^-?\\d+:\\d+$"
+      "description": "The timestamp of the first media unit in the segment (which may not be the first unit in the object). Format as described by the [Timestamp](../schemas/timestamp#top) type",
+      "$ref": "timestamp.json"
     },
     "last_duration": {
-      "description": "The duration of the last media unit in the segment (which may differ from that of the object). Defaults to 1/rate if a fixed media rate is set.",
-      "type": "string",
-      "pattern": "^\\d+:\\d+$"
+      "description": "The duration of the last media unit in the segment (which may differ from that of the object). Defaults to 1/rate if a fixed media rate is set. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative",
+      "$ref": "timestamp.json"
     },
     "last_ts" : {
-      "description": "The timestamp of the start of the last media unit in the segment, or end of the last media unit in the segment if exclusive_last_ts is true.",
-      "type": "string",
-      "pattern": "^-?\\d+:\\d+$"
+      "description": "The timestamp of the start of the last media unit in the segment, or end of the last media unit in the segment if exclusive_last_ts is true. Format as described by the [Timestamp](../schemas/timestamp#top) type",
+      "$ref": "timestamp.json"
     },
     "exclusive_last_ts" : {
       "description": "A true value indicates that the last_ts timestamp is the exclusive end of the last media unit in the segment.",

diff --git a/api/schemas/flow-storage.json b/api/schemas/flow-storage.json
@@ -30,7 +30,7 @@
     },
     "segments": {
       "type": "object",
-      "description": "Mapping of timeranges (validated by regex) to segment storage locations.",
+      "description": "Mapping of timeranges (validated by regex) to segment storage locations. Format as described by the [TimeRange](../schemas/timerange#top) type",
       "patternProperties": {
         "^[\\[\\(]?([0-9]+:[0-9]+)?_([0-9]+:[0-9]+)?[\\]\\)]?$": {
           "type": "object",

diff --git a/api/schemas/timerange.json b/api/schemas/timerange.json
@@ -0,0 +1,6 @@
+{
+    "title": "TimeRange",
+    "description": "A time range of timestamps. It is represented using a pair ot timestamps with inclusivity and exclusivity markers.\n\nE.g.\n* \"[0:0_10:0)\" represents 10 seconds of media starting at timestamp \"0:0\" and ending before \"10:0\".\n* \"(5:0_\" represents a time range starting after \"5:0\" and to eternity.\n* \"[1694429247:0_1694429248:0)\" is a 1 second TAI time range starting at 2023-09-11T10:46:50.0Z UTC.\n* A \"[\" or \"]\" indicates that bound is inclusive, and a \"(\" or \")\" indicates that bound is exclusive.\n\nDetails of the format can be found in the TimeRange class provided in the Python\n[mediatimestamp](https://github.com/bbc/rd-apmm-python-lib-mediatimestamp) library.\n",
+    "type": "string",
+    "pattern": "^(\\[|\\()?(-?\\d+:\\d+)?(_(-?\\d+:\\d+)?)?(\\]|\\))?$"
+ }
diff --git a/api/schemas/timestamp.json b/api/schemas/timestamp.json
@@ -0,0 +1,6 @@
+{
+    "title": "Timestamp",
+    "description": "A signed nanosecond resolution timestamp represented as <sign><seconds>:<nanoseconds>. The intended\ninterpretation of the value is assumed to be defined elsewhere.\n\nE.g.\n* \"1:40000000\" is the timestamp of the 27th video frame for 25 Hz video with origin at \"0:0\".\n* \"1694429247:40000000\" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC.\n\nDetails of the format can be found in the Timestamp class provided in the Python\n[mediatimestamp](https://github.com/bbc/rd-apmm-python-lib-mediatimestamp) library.\n",
+    "type": "string",
+    "pattern": "^-?\\d+:\\d+$"
+ }