# JSON Implementation of Time-Frequency Radio Catalogues: TFCat - **Authors**: Cecconi, Baptiste; Bonnin, Xavier; Loh, Alan. - **Date**: Nov. 2021 - **Version**: 1.0 (release candidate 1) - **Publisher**: PADC - **DOI**: [10.25935/6068-8528](https://doi.org/10.25935/6068-8528) TFCat (Time-Frequency Catalogue) is a data interchange format 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 properties, and their temporal and spectral extents. This implementation is inheriting from the GeoJSON file format [[RFC7946](https://tools.ietf.org/html/rfc7946)]. ## 1. Introduction TFCat is a format for encoding a variety of spectro-temporal data 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 to this time-frequency space. the TFCat format is following most of the 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. A TFCat object may represent a region of the tf-space (a Geometry), a tf-spatially bounded entity (a Feature), or a list of Features (a FeatureCollection). TFCat supports the same geometry types as GeoJSON: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. Features in TFCat contain a Geometry object and additional properties, and a FeatureCollection contains a list of Features. The TFCat object contains a list of fields defining the properties listed in the Fetaures, and a coordinate reference system (CRS) describing the temporal and spectral axes of the geometry data. ### 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)] are applicable here, replacing the "GeoJSON" string by "TFCat". We recall them 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" * As another shorthand notation, the term "TFCat types" refers to 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 A TFCat FeatureCollection: ``` { "type": "FeatureCollection", "features": [ { "type": "Feature", "id": 0, "geometry": { "type": "Point", "coordinates": [1158051858, 24730.0] }, "properties": { "quality": "3" } }, { "type": "Feature", "id": 1, "geometry": { "type": "LineString", "coordinates": [[1158051874, 34130.0], [1158051882, 22770.0]] }, "properties": { "quality": "2" } } ], "properties": { "facility_name": "Cassini", "instrument_name: ": "RPWS", "receiver_name": "HFR", "title": "Faraday Rotation (FR) patches", }, "fields": { "quality": { "info": "Quality parameter: -1 (not set), 1 (good), 2 (medium) and 3 (bad quality).", "datatype": "str", "ucd": "meta.code.qual" } }, "crs": { "type": "Cartesian", "properties": { "name": "Time-Spectrogram", "time_coords": { "name": "Timestamp", "id": "unix", "unit": "s", "time_origin": "1970-01-01T00:00:00.000Z", "time_scale": "UTC" }, "spectral_coords": { "name": "Frequency", "unit": "Hz" }, "ref_position":{ "id": "Cassini" } } } } ``` ## 2. TFCat Text > The TFCat Text is defined similarly to Section 2 of > [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every > instance of "GeoJSON" by "TFCat". For the sake of clarity, we > reproduce the applicable definition below. A TFCat text is a JSON text and consists of a single TFCat object. ## 3. TFCat Object > The TFCat Object is defined similarly to Section 3 of > [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every > instance of "GeoJSON" by "TFCat". For the sake of clarity, we > reproduce the applicable definition below. A TFCat object represents a Geometry, Feature or a collection of Features. * 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. * A TFCat object MAY have a "bbox" member, the value of which MUST be a bounding box array (see [Section 5](#5-bounding-box)). * A TFCat object MAY have other members (see [Section 6](#6-extending-tfcat-and-versioning)). ### 3.1. Geometry Object > The Geometry Object is defined similarly to Section 3.1 of > [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every > instance of "GeoJSON" by "TFCat". For the sake of clarity, we > reproduce the applicable definition below. A Geometry object represents points, curves, and surfaces in coordinate space. Every Geometry object is a TFCat object no matter where it occurs in a TFCat text. * The value of a Geometry object's "type" member MUST be one of the seven geometry types (see [Section 1.3](#13-definitions)). * A TFCat Geometry object of any type other than "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 geometry. TFCat processors MAY interpret Geometry objects with empty "coordinates" arrays as null objects. #### 3.1.1. Position > 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. 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, * an array of LineString or linear ring coordinates in the case of a Polygon or MultiLineString geometry, or * 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). In other words, every point (t, f) on a line between a point (t0, f0) and (t1, f1) can be calculated as ``` (t, f) = (t0 + (t1 - t0) * x, f0 + (f1 - f0) * x) ``` with `x` being a real number greater than or equal to 0 and smaller than or equal to 1. Examples of positions and geometries are provided in Appendix A, "Geometry Examples". #### 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 A Feature object represents a spectro-temporal bounded thing. Every Feature object is a TFCat object no matter where it occurs in a TFCat 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 of the properties member is a Properties Object or a JSON null value. * 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. ### 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. ### 3.3. FeatureCollection Object 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 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. ### 3.3.1. Field Object 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. * The Field Object has a member with name "info". The value of this member contain a description of the "field". * The Field Object has a member with name "datatype". The value of this member is one of 'int', 'float' 'bool', or 'str' (TBC) * The "field" value object has a member with name "ucd". The value of this member is a valid UCD (IVOA Unified Content Description). * The "field" value object may have a member with name "unit". The value of this member is a valid unit, as defined in the VOUnit specification. ## 4. Coordinate Reference System The coordinate reference system (CRS) for all TFCat coordinates is a time-frequency coordinate reference system, which consists in a temporal coordinate reference system and a spectral coordinate reference system. 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 one of "Time-Frequency", "Time-Wavelength", "Time-Energy", "Time-Wavenumber". * A CRS object has a member with the name "properties". The value of the properties member is an object. This object has members "time_coords", "spectral_coords" and "ref_position". The "time_coords" member value is a TimeCoords object. The "spectral_coords" member value is a SpectralCoords object. The "ref_position" member value is a RefPosition object. ### 4.1. TimeCoords 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). * A TimeCoords object has a member with name "id", with values in the list: "unix", "jd", "mjd" (_list to be completed_) * A TimeCoords object has a member with name "name", with value set to a character string describing the temporal coordinate axis. * 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 to the origin of the time axis, expressed in ISO 8601 format. The TimeCoords reference position is defined in the RefPosition property of the CRS. Example of TimeCoords object: ``` "time_coords": { "id": "unix", "name": "Timestamp (Unix Time)", "unit": "s", "time_origin": "1970-01-01T00:00:00.000Z", "time_scale": "TT" } ``` ``` "time_coords": { "id": "mjd", "name": "Modified Julian Date", "unit": "d", "time_origin": "1858-11-17T00:00:00.000Z", "time_scale": "UTC" } ``` ### 4.2. SpectralCoords 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. * A TimeCoords object has a member with name "name", with value set to a character string describing the spectral coordinate axis. * 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. Example of SpectralCoords object: ``` "spectral_coords": { "name": "Frequency", "unit": "MHz" } ``` ``` "spectral_coords": { "name": "Wavelength", "unit": "cm" } ``` ### 4.3. RefPosition A RefPosition object represents the reference position of the coordinate system defined by the CRS. * A RefPosition object has a member with name "id", with value set to the 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. Examples of RefPosition object: ``` "ref_position": { "id": "GEOCENTER" } ``` ## 5. Bounding Box > The Feature Object is defined as in Section 5 of > [[rfc7946](https://tools.ietf.org/html/rfc7946)], replacing every > instance of "GeoJSON" by "TFCat". Since the TFCat Point object only has two coordinates, the "bbox" member MUST be an array of length 4. ### 5.1. The Connecting Lines > Section 5.1 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] is > adapted to the TFCat specifications as follows: The four lines of the bounding box are defined fully within the coordinate reference system; that is, for a box bounded by the values "lower_freq", "upper_freq", "lower_time", and "upper_time", every point on the upmost frequency line can be expressed as ``` (t, f) = (lower_time + (upper_time - lower_time) * x, upper_freq) ``` with 0 <= x <= 1. > Section 5.2 and 5.3 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] > are NOT applicable. ## 6. Extending TFCat and Versioning > Section 6, 7 and 8 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] are > applicable, after replacing "GeoJSON" be "TFCat". > Section 9 of [[rfc7946](https://tools.ietf.org/html/rfc7946)] is NOT > applicable. ## 7. Security Considerations TFCat shares security issues common to all JSON content types. See [[RFC7159](https://tools.ietf.org/html/rfc7159)], Section 12 for additional information. TFCat does not provide executable content. TFCat does not provide privacy or integrity services. If sensitive 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 ## 8.1. I-JSON TFCat texts should follow the constraints of Internet JSON (I-JSON) [[RFC7493](https://tools.ietf.org/html/rfc7493)] for maximum interoperability. ## 8.2. IVOA TFCat uses several IVOA elements, which improves its interoperability. The units SHOULD be specified following the [VOUnits](https://www.ivoa.net/documents/VOUnits/) specification. The reference positions and time scale, used to defined 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). ## 9. References ### 9.1. Normative References * [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, <https://tools.ietf.org/html/rfc7159> * [UCD1+] Preite Martinez, A., M. Louys, B. Cecconi, S. Derrière, F. Ochsenbein, S. Erard, M. Demleitner. 2021. UCD1+ controlled vocabulary - Updated List of Terms. Version 1.4 <https://ivoa.net/documents/UCD1+/> * [VOUnits] Demleitner, M., S. Derriere, N. Gray, M. Louys, and F. Ochsenbein. 2014. Units in the VO. Version 1.0. <https://ivoa.net/documents/VOUnits/> ## A. Geometry Examples Each of the examples below represents a valid and complete TFCat object. 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 Coordinates of a Polygon are an array of linear ring (see 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], [1158051866, 24731.0], [1158051866, 24734.0], [1158051860, 24734.0], [1158051860, 24731.0] ] ] } ``` ### A.4. MultiPoints Coordinates of a MultiPoint are an array of positions: ``` { "type": "MultiPoint", "coordinates": [ [1158051858, 24730.0], [1158051868, 24735.0], ] } ``` ### A.5. MultiLineStrings Coordinates of a MultiLineString are an array of LineString coordinate arrays: ``` { "type": "MultiLineString", "coordinates": [ [ [1158051858, 24730.0], [1158051868, 24735.0], ], [ [1158051878, 24740.0], [1158051888, 24745.0], ] ] } ``` ### 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], [1158051886, 24731.0], [1158051886, 24734.0], [1158051880, 24734.0], [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] ] }] } ```