Skip to content

Strawmen

Jump to bottom
Philip Crotwell edited this page Sep 24, 2025 · 5 revisions

Some examples of various styles of JSON to consider and provoke discussion.

Code to generate these is in the strawmen folder in the repo.

Most basic, direct xml to json

We most like DO NOT want to do this.

Pros:

  • Very similar to StationXML

Cons:

  • Hierarchical
  • Harder to navigate for clients
{
  "source": "IRIS-DMC",
  "sender": "IRIS-DMC",
  "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
  "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
  "created": "2025-09-09T15:36:31.7855",
  "network": [
    {
      "sourceid": "FDSN:CO",
      "restrictedStatus": "open",
      "startDate": "1987-01-01T00:00:00.0000",
      "description": "South Carolina Seismic Network (SCSN)",
      "identifier": "10.7914/SN/CO\n   ",
      "totalNumberStations": "19",
      "selectedNumberStations": "1",
      "station": [
        {
          "sourceid": "FDSN:CO_BIRD",
          "startDate": "2010-08-25T00:00:00.0000",
          "placeholder": "much omitted"
        }
      ]
    },
    {
      "sourceid": "FDSN:XD1994",
      "endDate": "1995-12-31T23:59:59.9999",
      "restrictedStatus": "open",
      "startDate": "1994-01-01T00:00:00.0000",
      "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
      "identifier": "10.7914/SN/XD_1994\n   ",
      "totalNumberStations": "21",
      "selectedNumberStations": "1",
      "station": [
        {
          "sourceid": "FDSN:XD1994_GOMA",
          "startDate": "1994-06-02T00:00:00.0000",
          "placeholder": "much omitted",
          "endDate": "1995-06-03T00:00:00.0000"
        }
      ]
    }
  ]
}

Flatten using network and station as top level containers

Pros:

  • Not Hierarchical
  • Allows just Station, when Network not needed

Cons:

  • Linkage between station and network is not explicit
  • New types would require new top level elements
{
  "source": "IRIS-DMC",
  "sender": "IRIS-DMC",
  "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
  "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
  "created": "2025-09-09T15:36:31.7855",
  "network": [
    {
      "sourceid": "FDSN:CO",
      "restrictedStatus": "open",
      "startDate": "1987-01-01T00:00:00.0000",
      "description": "South Carolina Seismic Network (SCSN)",
      "identifier": "10.7914/SN/CO\n   ",
      "totalNumberStations": "19",
      "selectedNumberStations": "1"
    },
    {
      "sourceid": "FDSN:XD1994",
      "endDate": "1995-12-31T23:59:59.9999",
      "restrictedStatus": "open",
      "startDate": "1994-01-01T00:00:00.0000",
      "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
      "identifier": "10.7914/SN/XD_1994\n   ",
      "totalNumberStations": "21",
      "selectedNumberStations": "1"
    }
  ],
  "station": [
    {
      "sourceid": "FDSN:CO_BIRD",
      "startDate": "2010-08-25T00:00:00.0000",
      "placeholder": "much omitted"
    },
    {
      "sourceid": "FDSN:XD1994_GOMA",
      "startDate": "1994-06-02T00:00:00.0000",
      "placeholder": "much omitted",
      "endDate": "1995-06-03T00:00:00.0000"
    }
  ]
}

Flatten, use top level items, include type field in each object

Pros:

  • Not Hierarchical
  • Allows just Station, when Network not needed
  • New types easily added

Cons:

  • Linkage between station and network is not explicit
  • Long list of items may be unwieldy
{
  "source": "IRIS-DMC",
  "sender": "IRIS-DMC",
  "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
  "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
  "created": "2025-09-09T15:36:31.7855",
  "items": [
    {
      "sourceid": "FDSN:CO",
      "restrictedStatus": "open",
      "startDate": "1987-01-01T00:00:00.0000",
      "description": "South Carolina Seismic Network (SCSN)",
      "identifier": "10.7914/SN/CO\n   ",
      "totalNumberStations": "19",
      "selectedNumberStations": "1",
      "type": "network"
    },
    {
      "sourceid": "FDSN:CO_BIRD",
      "startDate": "2010-08-25T00:00:00.0000",
      "placeholder": "much omitted",
      "type": "station"
    },
    {
      "sourceid": "FDSN:XD1994",
      "endDate": "1995-12-31T23:59:59.9999",
      "restrictedStatus": "open",
      "startDate": "1994-01-01T00:00:00.0000",
      "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
      "identifier": "10.7914/SN/XD_1994\n   ",
      "totalNumberStations": "21",
      "selectedNumberStations": "1",
      "type": "network"
    },
    {
      "sourceid": "FDSN:XD1994_GOMA",
      "startDate": "1994-06-02T00:00:00.0000",
      "placeholder": "much omitted",
      "endDate": "1995-06-03T00:00:00.0000",
      "type": "station"
    }
  ]
}

Json:API

Pros:

  • Not Hierarchical
  • Allows just Station, when Network not needed
  • New types easily added
  • Clearly separates data from metadata
  • Relationships are explicit and separate from attributes
  • Existing standard
  • Links, many other features

Cons:

  • Complicated
  • Verbose
  • Design is more for transactional use, rather than storage
{
  "meta": {
    "source": "IRIS-DMC",
    "sender": "IRIS-DMC",
    "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
    "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
    "created": "2025-09-09T15:36:31.7855"
  },
  "data": [
    {
      "type": "network",
      "id": "FDSN:CO",
      "attributes": {
        "sourceid": "FDSN:CO",
        "restrictedStatus": "open",
        "startDate": "1987-01-01T00:00:00.0000",
        "description": "South Carolina Seismic Network (SCSN)",
        "identifier": "10.7914/SN/CO\n   ",
        "totalNumberStations": "19",
        "selectedNumberStations": "1"
      },
      "relationships": {
        "station": [
          {
            "data": {
              "type": "station",
              "id": "FDSN:CO_BIRD"
            }
          }
        ]
      }
    },
    {
      "type": "network",
      "id": "FDSN:XD1994",
      "attributes": {
        "sourceid": "FDSN:XD1994",
        "endDate": "1995-12-31T23:59:59.9999",
        "restrictedStatus": "open",
        "startDate": "1994-01-01T00:00:00.0000",
        "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
        "identifier": "10.7914/SN/XD_1994\n   ",
        "totalNumberStations": "21",
        "selectedNumberStations": "1"
      },
      "relationships": {
        "station": [
          {
            "data": {
              "type": "station",
              "id": "FDSN:XD1994_GOMA"
            }
          }
        ]
      }
    }
  ],
  "included": [
    {
      "type": "station",
      "id": "FDSN:CO_BIRD",
      "attributes": {
        "sourceid": "FDSN:CO_BIRD",
        "startDate": "2010-08-25T00:00:00.0000",
        "placeholder": "much omitted"
      },
      "relationships": {
        "network": {
          "data": {
            "type": "network",
            "id": "FDSN:CO"
          }
        }
      }
    },
    {
      "type": "station",
      "id": "FDSN:XD1994_GOMA",
      "attributes": {
        "sourceid": "FDSN:XD1994_GOMA",
        "startDate": "1994-06-02T00:00:00.0000",
        "placeholder": "much omitted",
        "endDate": "1995-06-03T00:00:00.0000"
      },
      "relationships": {
        "network": {
          "data": {
            "type": "network",
            "id": "FDSN:XD1994"
          }
        }
      }
    }
  ]
}

Flatten, use meta and data, include type field in each object

This variation of the Flatten, use top level items borrows from jsonapi to have a meta object, and puts attributes inside a data object, but less complex. A meta object at various places may allow for items coming from other name spaces to be put, if network, station, channel, response all allow a meta inside.

Pros:

  • Not Hierarchical
  • Allows just Station, when Network not needed
  • New types easily added
  • Clearly separates data from metadata
  • meta can be at sublevels (net, sta, chan, resp)
  • type is not inside the data object
  • separate id from sourceid, allow start date and publication version?

Cons:

  • Linkage between station and network is not explicit
  • Long list of items may be unwieldy
  • repetition of data at multiple levels may be confusing
{
  "meta": {
    "source": "IRIS-DMC",
    "sender": "IRIS-DMC",
    "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
    "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
    "created": "2025-09-09T15:36:31.7855"
  },
  "data": [
    {
      "type": "network",
      "id": "FDSN:CO@1987-01-01T00:00:00.0000/3",
      "data": {
        "sourceid": "FDSN:CO",
        "restrictedStatus": "open",
        "startDate": "1987-01-01T00:00:00.0000",
        "description": "South Carolina Seismic Network (SCSN)",
        "identifier": {
          "type": "DOI",
          "id": "10.7914/SN/CO"
        }
      },
      "meta": {
        "pubVersion": "3",
        "otherNS": "stuff here",
        "totalNumberStations": "19",
        "selectedNumberStations": "1"
      }
    },
    {
      "type": "station",
      "id": "FDSN:CO_BIRD@2010-08-25T00:00:00.0000/4",
      "data": {
        "sourceid": "FDSN:CO_BIRD",
        "startDate": "2010-08-25T00:00:00.0000",
        "placeholder": "much omitted"
      },
      "meta": {
        "pubVersion": "4",
        "otherNS": "other stuff for station too"
      }
    },
    {
      "type": "network",
      "id": "FDSN:XD1994@1994-01-01T00:00:00.0000/3",
      "data": {
        "sourceid": "FDSN:XD1994",
        "endDate": "1995-12-31T23:59:59.9999",
        "restrictedStatus": "open",
        "startDate": "1994-01-01T00:00:00.0000",
        "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
        "identifier": {
          "type": "DOI",
          "id": "10.7914/SN/XD_1994"
        }
      },
      "meta": {
        "pubVersion": "3",
        "otherNS": "stuff here",
        "totalNumberStations": "21",
        "selectedNumberStations": "1"
      }
    },
    {
      "type": "station",
      "id": "FDSN:XD1994_GOMA@1994-06-02T00:00:00.0000/4",
      "data": {
        "sourceid": "FDSN:XD1994_GOMA",
        "startDate": "1994-06-02T00:00:00.0000",
        "placeholder": "much omitted",
        "endDate": "1995-06-03T00:00:00.0000"
      },
      "meta": {
        "pubVersion": "4",
        "otherNS": "other stuff for station too"
      }
    }
  ]
}

Flat, use JSON-LD 

{
  "@context": {
    "name": "http://fdsn.org"
  },
  "meta": {
    "source": "IRIS-DMC",
    "sender": "IRIS-DMC",
    "module": "IRIS WEB SERVICE: fdsnws-station | version: 1.1.52",
    "moduleUri": "https://service.iris.edu/fdsnws/station/1/query?net=CO,XD&station=GOMA,BIRD&level=station&format=xml&includecomments=true&nodata=404",
    "created": "2025-09-09T15:36:31.7855"
  },
  "data": [
    {
      "@type": "network",
      "@id": "FDSN:CO@1987-01-01T00:00:00.0000/3",
      "data": {
        "sourceid": "FDSN:CO",
        "restrictedStatus": "open",
        "startDate": "1987-01-01T00:00:00.0000",
        "description": "South Carolina Seismic Network (SCSN)",
        "identifier": {
          "type": "DOI",
          "id": "10.7914/SN/CO"
        }
      },
      "meta": {
        "pubVersion": "3",
        "otherNS": "stuff here",
        "totalNumberStations": "19",
        "selectedNumberStations": "1"
      }
    },
    {
      "@type": "station",
      "@id": "FDSN:CO_BIRD@2010-08-25T00:00:00.0000/4",
      "data": {
        "sourceid": "FDSN:CO_BIRD",
        "startDate": "2010-08-25T00:00:00.0000",
        "placeholder": "much omitted"
      },
      "meta": {
        "pubVersion": "4",
        "otherNS": "other stuff for station too"
      }
    },
    {
      "@type": "network",
      "@id": "FDSN:XD1994@1994-01-01T00:00:00.0000/3",
      "data": {
        "sourceid": "FDSN:XD1994",
        "endDate": "1995-12-31T23:59:59.9999",
        "restrictedStatus": "open",
        "startDate": "1994-01-01T00:00:00.0000",
        "description": "Seismic investigations of the Lithospheric Structure of the Tanzanian Craton (Tanzania)",
        "identifier": {
          "type": "DOI",
          "id": "10.7914/SN/XD_1994"
        }
      },
      "meta": {
        "pubVersion": "3",
        "otherNS": "stuff here",
        "totalNumberStations": "21",
        "selectedNumberStations": "1"
      }
    },
    {
      "@type": "station",
      "@id": "FDSN:XD1994_GOMA@1994-06-02T00:00:00.0000/4",
      "data": {
        "sourceid": "FDSN:XD1994_GOMA",
        "startDate": "1994-06-02T00:00:00.0000",
        "placeholder": "much omitted",
        "endDate": "1995-06-03T00:00:00.0000"
      },
      "meta": {
        "pubVersion": "4",
        "otherNS": "other stuff for station too"
      }
    }
  ]
}

Clone this wiki locally