spec.md 26.7 KB
Newer Older
Cecconi Baptiste's avatar
Cecconi Baptiste committed
1
# JSON Implementation of Time-Frequency Radio Catalogues: TFCat
Cecconi Baptiste's avatar
Cecconi Baptiste committed
2

Cecconi Baptiste's avatar
Cecconi Baptiste committed
3
- **Authors**:  Cecconi, Baptiste (1); Taylor, Mark (2); Bonnin, Xavier (1); Loh, Alan (1).
Taylor Mark's avatar
Taylor Mark committed
4
- **Affiliations**: (1) LESIA, CNRS, Observatoire de Paris-PSL, France; (2) H H Wills Physics Laboratory, University of Bristol, Bristol, UK.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
5
- **Date**: Sep. 2022 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
6
- **Version**: 1.0
Cecconi Baptiste's avatar
Cecconi Baptiste committed
7
- **Publisher**: PADC 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
8
- **DOI**: [10.25935/6068-8528](https://doi.org/10.25935/6068-8528)
Cecconi Baptiste's avatar
Cecconi Baptiste committed
9

Cecconi Baptiste's avatar
Cecconi Baptiste committed
10
TFCat (Time-Frequency Catalogue) is a data interchange format 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
11
12
13
based on JSON. It defines several types of JSON objects and the manner 
in which they are combined to represent data about time-frequency 
features of a time spectrogram (a.k.a. dynamic spectrum), their 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
14
15
16
17
properties, and their temporal and spectral extents. 

This implementation is inheriting from the GeoJSON file format 
[[RFC7946](https://tools.ietf.org/html/rfc7946)]. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
18
19
20
21


## 1. Introduction

Cecconi Baptiste's avatar
Cecconi Baptiste committed
22
TFCat is a format for encoding a variety of spectro-temporal data 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
23
24
25
26
structures using JavaScript Object Notation (JSON) 
[[RFC7159](https://tools.ietf.org/html/rfc7159)]. The representation 
space of the structures is the time-frequency plane. We will use 
"tf-plane", "tf-space", "tf-spatial" and "tf-spatially" terms to refer 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
27
to this time-frequency space. the TFCat format is following most of the 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
28
29
30
31
GeoJSON specification [[rfc7946](https://tools.ietf.org/html/rfc7946)]. 
All spatial information described in the GeoJSON specification are 
applicable, after transposition into the time-frequency plane space. 

Cecconi Baptiste's avatar
Cecconi Baptiste committed
32
A TFCat object may represent a region of the tf-space (a Geometry), 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
33
a tf-spatially bounded entity (a Feature), or a list of Features 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
34
(a FeatureCollection). TFCat supports the same geometry types as 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
35
GeoJSON: Point, LineString, Polygon, MultiPoint, MultiLineString, 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
36
MultiPolygon, and GeometryCollection. Features in TFCat contain a 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
37
Geometry object and additional properties, and a FeatureCollection 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
38
contains a list of Features. The TFCat object contains a list of 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
39
fields defining the properties listed in the Features, and a
Cecconi Baptiste's avatar
Cecconi Baptiste committed
40
41
42
coordinate reference system (CRS) describing the temporal and 
spectral axes of the geometry data. 
 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

### 1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 
"OPTIONAL" in this document are to be interpreted as described in 
[[RFC2119](https://tools.ietf.org/html/rfc2119)].

### 1.2. Conventions Used in This Document

The ordering of the members of any JSON object defined in this
document MUST be considered irrelevant, as specified by 
[[RFC7159](https://tools.ietf.org/html/rfc7159)].

Some examples use the combination of a JavaScript single-line comment
(//) followed by an ellipsis (...) as placeholder notation for
content deemed irrelevant by the authors. These placeholders must of
course be deleted or otherwise replaced, before attempting to
validate the corresponding JSON code example.

Whitespace is used in the examples inside this document to help
illustrate the data structures, but it is not required. Unquoted
whitespace is not significant in JSON.

### 1.3. Definitions

The definitions of section 1.3 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
70
are applicable here, replacing the "GeoJSON" string by "TFCat". We recall them
Cecconi Baptiste's avatar
Cecconi Baptiste committed
71
72
73
74
75
76
77
78
79
below. 

* JavaScript Object Notation (JSON), and the terms object, member,
  name, value, array, number, true, false, and null, are to be
  interpreted as defined in [[RFC7159](https://tools.ietf.org/html/rfc7159)].
* Inside this document, the term "geometry type" refers to seven
  case-sensitive strings: "Point", "MultiPoint", "LineString",
  "MultiLineString", "Polygon", "MultiPolygon", and
  "GeometryCollection"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
80
* As another shorthand notation, the term "TFCat types" refers to
Cecconi Baptiste's avatar
Cecconi Baptiste committed
81
82
83
84
85
86
87
88
89
90
  nine case-sensitive strings: "Feature", "FeatureCollection", and
  the geometry types listed above.
* The word "Collection" in "FeatureCollection" and
  "GeometryCollection" does not have any significance for the
  semantics of array members.  The "features" and "geometries"
  members, respectively, of these objects are standard ordered JSON
  arrays, not unordered sets.

### 1.4. Example

Cecconi Baptiste's avatar
Cecconi Baptiste committed
91
A TFCat FeatureCollection: 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

```
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "id": 0,
            "geometry": {
                "type": "Point",
                "coordinates": [1158051858, 24730.0]
            },
            "properties": {
                "quality": "3"
            }
        },
        {
            "type": "Feature",
            "id": 1,
            "geometry": {
                "type": "LineString",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
113
                "coordinates": [[1158051874, 34130.0], [1158051882, 22770.0]]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
114
115
116
117
118
119
120
            },
            "properties": {
                "quality": "2"
            }
        }
    ],
     "properties": {
Cecconi Baptiste's avatar
Cecconi Baptiste committed
121
        "facility_name": "Cassini",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
122
        "instrument_name": "RPWS",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
123
        "receiver_name": "HFR",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
124
        "title": "Faraday Rotation (FR) patches"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
125
126
127
    },
    "fields": {
      "quality": {
128
129
130
        "info": "Quality parameter: -1 (not set), 1 (good), 2 (medium) and 3 (bad quality).",
        "datatype": "str",
        "ucd": "meta.code.qual"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
131
      }
Cecconi Baptiste's avatar
Cecconi Baptiste committed
132
133
    },
    "crs": {
Cecconi Baptiste's avatar
Cecconi Baptiste committed
134
        "type": "local",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
135
        "properties": {
Cecconi Baptiste's avatar
Cecconi Baptiste committed
136
            "time_coords_id": "unix",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
137
            "spectral_coords": {
138
                "type": "frequency",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
139
                "unit": "kHz"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
140
            },
Cecconi Baptiste's avatar
Cecconi Baptiste committed
141
            "ref_position_id": "cassini-orbiter"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
142
143
144
145
146
        }
    }
}
```

Cecconi Baptiste's avatar
Cecconi Baptiste committed
147
## 2. TFCat Text
Cecconi Baptiste's avatar
Cecconi Baptiste committed
148

Cecconi Baptiste's avatar
Cecconi Baptiste committed
149
> The TFCat Text is defined similarly to Section 2 of 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
150
> [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
151
> instance of "GeoJSON" by "TFCat". For the sake of clarity, we 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
152
153
> reproduce the applicable definition below.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
154
A TFCat text is a JSON text and consists of a single TFCat 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
155
156
object.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
157
## 3. TFCat Object
Cecconi Baptiste's avatar
Cecconi Baptiste committed
158

Cecconi Baptiste's avatar
Cecconi Baptiste committed
159
> The TFCat Object is defined similarly to Section 3 of 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
160
> [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
161
> instance of "GeoJSON" by "TFCat". For the sake of clarity, we 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
162
163
> reproduce the applicable definition below.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
164
A TFCat object represents a Geometry, Feature or a collection of 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
165
166
Features. 

Cecconi Baptiste's avatar
Cecconi Baptiste committed
167
168
169
* A TFCat object is a JSON object.
* A TFCat object has a member with the name "type". The value of
  the member MUST be one the TFCat types.
170
171
* A TFCat object MAY have a "crs" member, the value of which
  MUST be a Coordinate Reference System object
Taylor Mark's avatar
Taylor Mark committed
172
  (see [Section 4](#4-coordinate-reference-system)).
Cecconi Baptiste's avatar
Cecconi Baptiste committed
173
* A TFCat object MAY have a "bbox" member, the value of which 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
174
  MUST be a bounding box array (see [Section 5](#5-bounding-box)).
Cecconi Baptiste's avatar
Cecconi Baptiste committed
175
176
* A TFCat object MAY have other members (see 
  [Section 6](#6-extending-tfcat-and-versioning)).
Cecconi Baptiste's avatar
Cecconi Baptiste committed
177
178
179

### 3.1. Geometry Object

Cecconi Baptiste's avatar
Cecconi Baptiste committed
180
> The Geometry Object is defined similarly to Section 3.1 of 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
181
> [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
182
> instance of "GeoJSON" by "TFCat". For the sake of clarity, we 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
183
184
> reproduce the applicable definition below.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
185
A Geometry object represents points, curves, and surfaces in
Cecconi Baptiste's avatar
Cecconi Baptiste committed
186
187
coordinate space. Every Geometry object is a TFCat object no
matter where it occurs in a TFCat text.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
188
189

* The value of a Geometry object's "type" member MUST be one of the
Cecconi Baptiste's avatar
Cecconi Baptiste committed
190
  seven geometry types (see [Section 1.3](#13-definitions)).
Cecconi Baptiste's avatar
Cecconi Baptiste committed
191
* A TFCat Geometry object of any type other than
Cecconi Baptiste's avatar
Cecconi Baptiste committed
192
193
194
  "GeometryCollection" has a member with the name "coordinates".
  The value of the "coordinates" member is an array. The structure
  of the elements in this array is determined by the type of
Cecconi Baptiste's avatar
Cecconi Baptiste committed
195
  geometry. TFCat processors MAY interpret Geometry objects with
Cecconi Baptiste's avatar
Cecconi Baptiste committed
196
197
198
199
  empty "coordinates" arrays as null objects.

#### 3.1.1. Position

Cecconi Baptiste's avatar
Cecconi Baptiste committed
200
201
202
203
> The Position is defined similarly as Section 3.1.1 of 
> [[rfc7946](https://tools.ietf.org/html/rfc7946)], with restrictions.
> For the sake of clarity, we reproduce the applicable definition below.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
204
205
206
207
208
209
A position is the fundamental geometry construct.  The "coordinates"
member of a Geometry object is composed of either:

* one position in the case of a Point geometry,
* an array of positions in the case of a LineString or MultiPoint
  geometry,
Cecconi Baptiste's avatar
Cecconi Baptiste committed
210
211
* an array of LineString or linear ring coordinates in the case of 
  a Polygon or MultiLineString geometry, or
Cecconi Baptiste's avatar
Cecconi Baptiste committed
212
213
214
215
216
217
218
219
220
221
222
* an array of Polygon coordinates in the case of a MultiPolygon
  geometry.

A position is an array of numbers. There MUST be two elements. 
The two elements are the temporal and spectral coordinates, in that 
order, using decimal numbers.

A line between two positions is a straight Cartesian line, the
shortest line between those two points in the coordinate reference
system (see Section 4).

Cecconi Baptiste's avatar
Cecconi Baptiste committed
223
In other words, every point (t, f) on a line between a point (t0, f0) and 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
224
225
(t1, f1) can be calculated as

Cecconi Baptiste's avatar
Cecconi Baptiste committed
226
227
228
```
(t, f) = (t0 + (t1 - t0) * x, f0 + (f1 - f0) * x)
```
Cecconi Baptiste's avatar
Cecconi Baptiste committed
229

Cecconi Baptiste's avatar
Cecconi Baptiste committed
230
with `x` being a real number greater than or equal to 0 and smaller
Cecconi Baptiste's avatar
Cecconi Baptiste committed
231
232
233
234
235
than or equal to 1. 

Examples of positions and geometries are provided in Appendix A,
"Geometry Examples".

Cecconi Baptiste's avatar
Cecconi Baptiste committed
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
#### 3.1.2. Geometric Object Classes

> For Point, MultiPoint, LineString, MultiLineString, Polygon, and 
> MultiPolygon, the same definitions as in section 3.1.2. to 3.1.7. of 
> [[rfc7946](https://tools.ietf.org/html/rfc7946)] are applicable.
> The GeometryCollection is also defined as in section 3.1.8. of 
> [[rfc7946](https://tools.ietf.org/html/rfc7946)]. 

> Section 3.1.9 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] is 
> NOT applicable. 

#### 3.1.3. Uncertainty and Precision

> Section 3.1.10 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] is
> applicable. 

### 3.2. Feature Object

254
A Feature object represents a spectro-temporal bounded thing.  Every 
255
Feature object is a TFCat object no matter where it occurs in a TFCat 
256
257
258
259
260
261
262
263
text.

* A Feature object has a "type" member with the value "Feature".
* A Feature object has a member with the name "geometry".  The value 
  of the geometry member SHALL be either a Geometry object as defined 
  above or, in the case that the Feature is unlocated, a JSON null 
  value.
* A Feature object has a member with the name "properties".  The value 
264
  of the properties member is a Properties Object or a JSON null value.
265
266
267
268
* If a Feature has a commonly used identifier, that identifier
  SHOULD be included as a member of the Feature object with the name
  "id", and the value of this member is either a JSON string or
  number.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
269

270
271
272
273
274
275
276
277
278
279
### 3.2.1. Properties Object

The Properties Object contains additional metadata associated to the 
corresponding Feature Object. The Properties Object is a JSON Object, 
which members are called "property".  

* Each "property" name MUST be defined in the Fields Object (see 
  [Section 3.3.1.](#3.3.1-fields-object)).
* A "property" value MUST be either a JSON string or number.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
280
281
### 3.3. FeatureCollection Object

282
283
284
285
286
287
288
A TFCat object with the type "FeatureCollection" is a
FeatureCollection object.  A FeatureCollection object has a member
with the name "features".  The value of "features" is a JSON array.
Each element of the array is a Feature object as defined above.  It
is possible for this array to be empty.

* The FeatureCollection Object has a member with name "fields". The 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
289
290
291
292
293
  value of the "fields" member is a JSON Object. 
* The names of "fields" object members MUST correspond to the 
  "property" members of the Properties Objects of the Feature 
  Objects listed in the "features" member. 
* The members of the "fields" Object are Field Objects. 
294

Cecconi Baptiste's avatar
Cecconi Baptiste committed
295
### 3.3.1. Field Object
296

Cecconi Baptiste's avatar
Cecconi Baptiste committed
297
298
299
300
The Field Object contains the metadata defining one of the "property" 
included in the Properties Object members of each Feature Object (see 
[Section 3.2.1.](#3.2.1-properties-object)).  The Field Object is a 
JSON object.
301

Cecconi Baptiste's avatar
Cecconi Baptiste committed
302
* The Field Object has a member with name "info". The value of this 
303
  member contain a description of the "field".
Cecconi Baptiste's avatar
Cecconi Baptiste committed
304
305
* The Field Object has a member with name "datatype". The value of 
  this member is one of 'int', 'float' 'bool', or 'str' (TBC)
306
* The Field Object has a member with name "ucd". The value of this 
307
  member is a valid UCD (IVOA Unified Content Description).
308
* The Field Object may have a member with name "unit". The value of 
309
  this member is a valid unit, as defined in the VOUnit specification.
310
  If "unit" is not applicable, the member should not be present.  
Cecconi Baptiste's avatar
Cecconi Baptiste committed
311
312
313

## 4. Coordinate Reference System

Cecconi Baptiste's avatar
Cecconi Baptiste committed
314
The coordinate reference system (CRS) for all TFCat coordinates is a
Cecconi Baptiste's avatar
Cecconi Baptiste committed
315
time-frequency coordinate reference system, which consists in a temporal 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
316
317
coordinate reference system and a spectral coordinate reference system. It
also defines the CRS reference position.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
318

Taylor Mark's avatar
Taylor Mark committed
319
The CRS of a TFCat object is determined by its
320
321
322
323
324
325
"crs" member (referred to below as the CRS object). 
If a TFCat object has no "crs" member, then its parent's CRS
is considered to apply.  A CRS MUST be in scope for every Geometry object.
This is usually applied by providing a "crs" member in the top-level
TFCat object in a TFCat Text.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
326
327
328
The CRS object contains the description of the TimeFrame and SpectralFrame. 

* A CRS object has a member with the name "type". The value of member MUST be
Cecconi Baptiste's avatar
Cecconi Baptiste committed
329
330
  one of "local", "link" or "name". In this version, solely the "local" value 
  is actually implemented, so that the "link" and "name" SHOULD not be used. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
331
* A CRS object has a member with the name "properties". The value of the 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
332
333
  properties member is an object. 

334
### 4.1. Local CRS 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
335

336
337
* A Local CRS object is a CRS object with its "type" member set to "local".
* A Local CRS object has a member with the name "properties". The value of the 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
338
339
  properties member is a Local CRS Properties Object

340
#### 4.1.1 Local CRS Properties Object
Cecconi Baptiste's avatar
Cecconi Baptiste committed
341
342
343
344
345
346
347
348
349
350

* A Local CRS Properties Object MAY have a member with name "time_coords". The 
  value of this element is a TimeCoords object. 
* A Local CRS Properties Object MAY have a member with name "time_coords_id". 
  The velue of this member MUST be one of the following values: "unix", "jd", 
  "mjd", "mjd_nasa", "mjd_cnes", "cdf_tt2000". The definitions of the 
  "time_coords_id" values is provided in Appendix B.
* One of the "time_coords" and "time_coords_id" members MUST be present in a 
  Local CRS Properties Object. 
* A Local CRS Properties Object MUST have a member with name "spectral_coords".
Taylor Mark's avatar
typos    
Taylor Mark committed
351
  The value of this element is a SpectralCoords object. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
352
353
354
355
* A Local CRS Properties Object MUST have a member with name "ref_position_id".
  The value of this member is a named reference location. The allowed values 
  for this member SHOULD be either from the https://www.ivoa.net/rdf/refposition 
  list of values, or the spacecraft name (free string until an Observation 
356
  Facility vocabulary is available).  
Cecconi Baptiste's avatar
Cecconi Baptiste committed
357
358
359
360
361
362
363

Example of Local CRS object:

```
      "crs": {
        "type": "local",
        "properties": {
Cecconi Baptiste's avatar
typo    
Cecconi Baptiste committed
364
          "time_coords_id": "unix",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
365
          "spectral_coords": {
366
            "type": "frequency",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
367
368
369
370
371
372
373
            "unit": "kHz"
          },
          "ref_position_id": "cassini-orbiter"
        }
      }
```

Cecconi Baptiste's avatar
Cecconi Baptiste committed
374

375
#### 4.1.2 TimeCoords Object
Cecconi Baptiste's avatar
Cecconi Baptiste committed
376
377
378
379
380
381

A TimeCoords object represents the time coordinate reference system in use 
for the 1st coordinate axis of the Point objects. The time coordinate 
reference system is defined by a frame (with time scale and a reference 
position), and a representation (e.g., a unit and a time origin). 

Cecconi Baptiste's avatar
Cecconi Baptiste committed
382
* A TimeCoords object may have a member with name "name", with value set to a 
383
  character string describing the temporal coordinate axis. The value of this
Taylor Mark's avatar
typos    
Taylor Mark committed
384
  member may be used by display tools for presenting the data. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
385
386
387
388
389
390
391
392
393
394
395
* A TimeCoords object has a member with name "time_scale", with values in the 
  list: GPS, TAI, TCB, TCG, TDB, TT, UT, UTC, UNKNOWN. The definition of the  
  time scale terms is available from https://www.ivoa.net/rdf/timescale/ 
  Two additional allowed values are: SCET (SpaceCraft Event Time), SCLK 
  (Spacecraft Clock). They refer to the time measured by the spacecraft clock, 
  SCET being transformed into a user readable unit, and SCLK is in the 
  internal spacecraft clock format.    
* A TimeCoords object has a member with name "unit", with value set to the
  unit of the time axis. The unit MUST be a valid 
  [VOUnit](https://www.ivoa.net/documents/VOUnits/) string. 
* A TimeCoords object has a member with name "time_origin", with value set 
396
397
  to the origin of the time axis, expressed in the following ISO 8601-like
  format:
398
  ```
399
  [-]YYYY-MM-DD['T'hh:mm:ss[.SSS]]
400
  ```   
Cecconi Baptiste's avatar
Cecconi Baptiste committed
401

Cecconi Baptiste's avatar
Cecconi Baptiste committed
402
403
404
405
406
407
Example of TimeCoords object:

```
        "time_coords": {
            "name": "Timestamp (Unix Time)",
            "unit": "s",
408
            "time_origin": "1970-01-01T00:00:00",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
409
            "time_scale": "UTC"
Cecconi Baptiste's avatar
Cecconi Baptiste committed
410
411
412
413
414
415
416
        }
```

```
        "time_coords": {
            "name": "Modified Julian Date",
            "unit": "d",
417
            "time_origin": "1858-11-17T00:00:00.0",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
418
419
420
            "time_scale": "UTC"
        }
```
Cecconi Baptiste's avatar
Cecconi Baptiste committed
421

422
### 4.1.3. SpectralCoords
Cecconi Baptiste's avatar
Cecconi Baptiste committed
423
424
425
426
427

A SpectralCoords object represents the spectral coordinate reference system
in use for the 2nd coordinate axis of the Point objects. The spectral 
coordinate reference system is defined by a reference position and a unit. 

428
429
* A SpectralCoords object has a member with name "type", with value set to a 
  character string describing the spectral coordinate axis. The allowed values
Taylor Mark's avatar
typos    
Taylor Mark committed
430
  are: "frequency", "wavelength", "energy", "wavenumber". 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
431
432
433
* A SpectralCoords object has a member with name "unit", with value set to the
  unit of the spectral axis. The unit MUST be a valid 
  [VOUnit](https://www.ivoa.net/documents/VOUnits/) string. 
434
435
436
437
* A SpectralCoords object may have a member with name "scale", with value set
  to ether "linear" or "log". If present, the value of this member may be 
  used by display tools to present the data with a linear or logarithmic 
  spectral scale.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
438

Cecconi Baptiste's avatar
Cecconi Baptiste committed
439
440
441
442
Example of SpectralCoords object:

```
        "spectral_coords": {
443
            "type": "frequency",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
444
445
446
447
448
449
            "unit": "MHz"
        }
```

```
        "spectral_coords": {
450
            "type": "wavelength",
Cecconi Baptiste's avatar
Cecconi Baptiste committed
451
452
453
454
            "unit": "cm"
        }
```

455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
### 4.2. Linked CRS 

* A Linked CRS object is a CRS object with its "type" member set to "link". 
* A Linked CRS object has a member with the name "properties". The value of the 
  properties member is a Linked CRS Properties Object.

#### 4.2.1 Linked CRS Properties Object

* A Linked CRS Properties Object has a member with name "href", with 
  value set to a URL linking to the TFCat CRS definition; 
* A Linked CRS Properties Object has a member with name "type", with 
  value set to a string defining the standard used to describe the linked 
  TFCat CRS definition. 
  
In this version of the TFCat specification, the allowed values for the "type"
element are not defined. Hence, the Linked CRS object SHOULD NOT be used.

Cecconi Baptiste's avatar
Cecconi Baptiste committed
472
### 4.3. Named CRS 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
473

474
475
476
477
478
479
480
* A Named CRS object is a CRS object with its "type" member set to "name".
* A Named CRS object has a member with the name "properties". The value of the 
  properties member is a Named CRS Properties Object.

#### 4.3.1 Named CRS Properties Object

* A Named CRS Properties Object has a member with name "name", with 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
481
482
483
484
  value set to a string referring to a well-known TFCat CRS. 
  
In this version of the TFCat specification, the allowed values for the "name"
element are not defined. Hence, the Named CRS object SHOULD NOT be used.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
485
486
487

## 5. Bounding Box 

Cecconi Baptiste's avatar
Cecconi Baptiste committed
488
489
490
491
> Section 5 [[rfc7946](https://tools.ietf.org/html/rfc7946)] is 
> applicable, after replacing "GeoJSON" be "TFCat". The following
> text is a simplified normative version applicable to TFCat. 

Cecconi Baptiste's avatar
Cecconi Baptiste committed
492
A TFCat object MAY have a member named "bbox" to include
Cecconi Baptiste's avatar
Cecconi Baptiste committed
493
information on the coordinate range for its Geometries, Features, 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
494
or FeatureCollections.  The value of the bbox member MUST be an 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
495
496
497
498
array of length 4 and MUST be of the form: 
```
[lower_time, lower_spectral, upper_time, upper_spectral]
```
Cecconi Baptiste's avatar
Cecconi Baptiste committed
499

Cecconi Baptiste's avatar
Cecconi Baptiste committed
500
## 6. Extending TFCat and Versioning
Cecconi Baptiste's avatar
Cecconi Baptiste committed
501

Cecconi Baptiste's avatar
Cecconi Baptiste committed
502
> Section 6, 7 and 8 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] are 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
503
> applicable, after replacing "GeoJSON" be "TFCat". 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
504
505
506
507
508
509

> Section 9 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] is NOT 
> applicable. 

## 7. Security Considerations

Cecconi Baptiste's avatar
Cecconi Baptiste committed
510
TFCat shares security issues common to all JSON content types.  See
Cecconi Baptiste's avatar
Cecconi Baptiste committed
511
[[RFC7159](https://tools.ietf.org/html/rfc7159)], Section 12 for additional 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
512
information. TFCat does not provide executable content.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
513

Cecconi Baptiste's avatar
Cecconi Baptiste committed
514
TFCat does not provide privacy or integrity services. If sensitive
Cecconi Baptiste's avatar
Cecconi Baptiste committed
515
516
517
518
519
520
data requires privacy or integrity protection, those must be provided
by the transport -- for example, Transport Layer Security (TLS) or
HTTPS. There will be cases in which stored data need protection,
which is out of scope for this document.

## 8. Interoperability Considerations
Cecconi Baptiste's avatar
Cecconi Baptiste committed
521

Cecconi Baptiste's avatar
Cecconi Baptiste committed
522
## 8.1. I-JSON
Cecconi Baptiste's avatar
Cecconi Baptiste committed
523

Cecconi Baptiste's avatar
Cecconi Baptiste committed
524
TFCat texts should follow the constraints of Internet JSON (I-JSON)
Cecconi Baptiste's avatar
Cecconi Baptiste committed
525
[[RFC7493](https://tools.ietf.org/html/rfc7493)] for maximum interoperability.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
526

Cecconi Baptiste's avatar
Cecconi Baptiste committed
527
## 8.2. IVOA
Cecconi Baptiste's avatar
Cecconi Baptiste committed
528

Cecconi Baptiste's avatar
Cecconi Baptiste committed
529
TFCat uses several IVOA elements, which improves its interoperability. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
530
The units SHOULD be specified following the [VOUnits](https://www.ivoa.net/documents/VOUnits/) 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
531
specification. The reference positions and time scale, used to define
Cecconi Baptiste's avatar
Cecconi Baptiste committed
532
533
534
the coordinate reference systems are using terms defined in IVOA controlled
vocabularies, which are, respectively, [RefPosition](https://www.ivoa.net/rdf/refposition)
and [TimeScale](https://www.ivoa.net/rdf/timescale).
Cecconi Baptiste's avatar
Cecconi Baptiste committed
535

Cecconi Baptiste's avatar
Cecconi Baptiste committed
536
## 9. References
Cecconi Baptiste's avatar
Cecconi Baptiste committed
537

Cecconi Baptiste's avatar
Cecconi Baptiste committed
538
### 9.1. Normative References
Cecconi Baptiste's avatar
Cecconi Baptiste committed
539

Cecconi Baptiste's avatar
Cecconi Baptiste committed
540
541
542
543
544
545
546
547
548
549
550
551
552
* [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
  Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
  <http://www.rfc-editor.org/info/rfc2119>.
* [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
  Specifications and Registration Procedures", BCP 13,
  RFC 6838, DOI 10.17487/RFC6838, January 2013,
  <http://www.rfc-editor.org/info/rfc6838>.
* [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
  Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
  2014, <http://www.rfc-editor.org/info/rfc7159>.
* [RFC7493]  Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
  DOI 10.17487/RFC7493, March 2015, <http://www.rfc-editor.org/info/rfc7493>.
* [RFC7946]  Butler, H., Ed., "The GeoJSON Format", RFC 7946, 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
553
  <https://tools.ietf.org/html/rfc7946>
Cecconi Baptiste's avatar
Cecconi Baptiste committed
554
555
* [UCD1+]  Preite Martinez, A., M. Louys, B. Cecconi, S. Derrière, F. Ochsenbein, 
  S. Erard, M. Demleitner. 2021. UCD1+ controlled vocabulary - Updated List 
556
  of Terms. Version 1.4. IVOA Endorsed Note. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
557
  <https://ivoa.net/documents/UCD1+/>
Cecconi Baptiste's avatar
Cecconi Baptiste committed
558
* [VOUnits]  Demleitner, M., S. Derriere, N. Gray, M. Louys, and
559
  F. Ochsenbein. 2014. Units in the VO. Version 1.0. IVOA Recommendation. 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
560
561
562
563
  <https://ivoa.net/documents/VOUnits/>

## A. Geometry Examples

Cecconi Baptiste's avatar
Cecconi Baptiste committed
564
Each of the examples below represents a valid and complete TFCat object.
Cecconi Baptiste's avatar
Cecconi Baptiste committed
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
In the provided examples, the time values are provided in "unixtime" (seconds
since 1970-01-01), and frequency values are proided in units of Hz.

### A.1.  Points

Point coordinates are in t, f order (time, frequency):

```
     {
         "type": "Point",
         "coordinates": [1158051858, 24730.0]
     }
```

### A.2.  LineStrings

Coordinates of LineString are an array of positions (see
Section 3.1.1):

```
     {
         "type": "LineString",
         "coordinates": [
             [1158051858, 24730.0],
             [1158051858, 24735.0]
         ]
     }
```
### A.3.  Polygons

Cecconi Baptiste's avatar
Cecconi Baptiste committed
595
Coordinates of a Polygon are an array of linear ring (see [[rfc7946](https://tools.ietf.org/html/rfc7946)]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
Section 3.1.6) coordinate arrays.  The first element in the array
represents the exterior ring.  Any subsequent elements represent
interior rings (or holes).

No holes:

```
     {
         "type": "Polygon",
         "coordinates": [
             [
                 [1158051858, 24730.0],
                 [1158051868, 24730.0],
                 [1158051868, 24735.0],
                 [1158051858, 24735.0],
                 [1158051858, 24730.0]
             ]
         ]
     }
```

With holes:

```
     {
         "type": "Polygon",
         "coordinates": [
             [
                 [1158051858, 24730.0],
                 [1158051868, 24730.0],
                 [1158051868, 24735.0],
                 [1158051858, 24735.0],
                 [1158051858, 24730.0]
             ],
             [
                 [1158051860, 24731.0],
                 [1158051860, 24734.0],
633
634
                 [1158051866, 24734.0],
                 [1158051866, 24731.0],
Cecconi Baptiste's avatar
Cecconi Baptiste committed
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
                 [1158051860, 24731.0]
             ]
         ]
     }
```

### A.4. MultiPoints

Coordinates of a MultiPoint are an array of positions:

```
     {
         "type": "MultiPoint",
         "coordinates": [
              [1158051858, 24730.0],
Cecconi Baptiste's avatar
Cecconi Baptiste committed
650
              [1158051868, 24735.0]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
         ]
     }
```

### A.5. MultiLineStrings

Coordinates of a MultiLineString are an array of LineString
coordinate arrays:

```
     {
         "type": "MultiLineString",
         "coordinates": [
             [
              [1158051858, 24730.0],
Cecconi Baptiste's avatar
Cecconi Baptiste committed
666
              [1158051868, 24735.0]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
667
668
669
             ],
             [
              [1158051878, 24740.0],
Cecconi Baptiste's avatar
Cecconi Baptiste committed
670
              [1158051888, 24745.0]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
             ]
         ]
     }
```

### A.6. MultiPolygons

Coordinates of a MultiPolygon are an array of Polygon coordinate
arrays:

```
     {
         "type": "MultiPolygon",
         "coordinates": [
             [
                 [
                     [1158051858, 24730.0],
                     [1158051868, 24730.0],
                     [1158051868, 24735.0],
                     [1158051858, 24735.0],
                     [1158051858, 24730.0]
                 ]
             ],
             [
                 [
                     [1158051878, 24730.0],
                     [1158051888, 24730.0],
                     [1158051888, 24735.0],
                     [1158051878, 24735.0],
                     [1158051878, 24730.0]
                 ],
                 [
                     [1158051880, 24731.0],
                     [1158051880, 24734.0],
705
706
                     [1158051886, 24734.0],
                     [1158051886, 24731.0],
Cecconi Baptiste's avatar
Cecconi Baptiste committed
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
                     [1158051880, 24731.0]
                 ]
             ]
         ]
     }
```

### A.7. GeometryCollections

Each element in the "geometries" array of a GeometryCollection is one
of the Geometry objects described above:

```
     {
         "type": "GeometryCollection",
         "geometries": [{
             "type": "Point",
             "coordinates": [1158051880, 24731.0]
         }, {
             "type": "LineString",
             "coordinates": [
                 [1158051878, 24730.0],
                 [1158051888, 24730.0]
             ]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
731
         }]
Cecconi Baptiste's avatar
Cecconi Baptiste committed
732
733
734
735
     }
```


Cecconi Baptiste's avatar
Cecconi Baptiste committed
736
## B. TFCat CRS Predefined TimeCoords 
Cecconi Baptiste's avatar
Cecconi Baptiste committed
737

738
739
740
741
742
743
744
745
`time_coords_id` | Description              | `time_origin`        | `unit` | `time_scale` |
| ---------------- | ------------------------ | -------------------- | ------ | ------------ |
| `unix`           | Unix Timestamp           |  1970-01-01T00:00:00 | s      | UTC          |
| `jd`             | Julian Day               | -4712-01-01T12:00:00 | d      | UTC          |
| `mjd`            | Modified Julian Day      |  1858-11-17T00:00:00 | d      | UTC          |
| `mjd_nasa`       | NASA Modified Julian Day |  1968-05-24T00:00:00 | d      | UTC          | 
| `mjd_cnes`       | CNES Modified Julian Day |  1950-01-01T00:00:00 | d      | UTC          |
| `cdf_tt2000`     | CDF Epoch TT2000         |  2000-01-01T00:00:00 | ns     | TT           |
Cecconi Baptiste's avatar
Cecconi Baptiste committed
746

Cecconi Baptiste's avatar
Cecconi Baptiste committed
747
748
749
750