Priority mode for Collections vs. Child Links

[chiarch84]

I have the following landing page json response:

{
  "type": "Catalog",
  "id": "BDAP.catalog",
  "title": "JRC Big Data Analytics Platform Catalog",
  "description": "The JRC Big Data Analytics Platform (BDAP) links data, data services, data scientists and thematic experts for generating policy relevant insights and foresight. It will play an instrumental role in advancing JRC to better mobilize and synthesize its collective knowledge and expertise in support to the EC priorities.\nThis Catalog shows the list of all rasters and vectors available in the [JRC Big Data Analytics Platform (BDAP)](https://jeodpp.jrc.ec.europa.eu/bdap/).",
  "stac_version": "1.0.0",
  "conformsTo": [
    "https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features",
    "https://api.stacspec.org/v1.0.0-rc.1/core",
    "https://api.stacspec.org/v1.0.0-rc.1/collections",
    "https://api.stacspec.org/v1.0.0-rc.1/item-search",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"
  ],
  "links": [
    {
      "rel": "self",
      "type": "application/json",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/"
    },
    {
      "rel": "root",
      "type": "application/json",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/"
    },
    {
      "rel": "data",
      "type": "application/json",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections"
    },
    {
      "rel": "conformance",
      "type": "application/json",
      "title": "STAC/WFS3 conformance classes implemented by this server",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/conformance"
    },
    {
      "rel": "search",
      "type": "application/geo+json",
      "title": "STAC search",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/search",
      "method": "GET"
    },
    {
      "rel": "search",
      "type": "application/geo+json",
      "title": "STAC search",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/search",
      "method": "POST"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Administrative Units Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/AdministrativeUnits.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Buildings Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Buildings.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Copernicus Data Access Portfolio Document (DAP) Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Copernicus.DAP.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Copernicus Sentinel Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Copernicus.Sentinel.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Copernicus Services Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Copernicus.Services.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "EUMETSAT Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/EUMETSAT.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Elevation Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Elevation.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Energy Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Energy.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Geographical Grid Systems Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/GeographicalGridSystems.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Geographical Names Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/GeographicalNames.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Hydrography Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Hydrography.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Land cover Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Landcover.catalog"
    },
    {
      "rel": "child",
      "type": "application/json",
      "title": "Landuse Data",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/collections/Landuse.catalog"
    },
[... other children]
    {
      "rel": "service-desc",
      "type": "application/vnd.oai.openapi+json;version=3.0",
      "title": "OpenAPI service description",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/api"
    },
    {
      "rel": "service-doc",
      "type": "text/html",
      "title": "OpenAPI service documentation",
      "href": "http://s-jrciprjeop150p.cidsn.jrc.it:20008/api.html"
    }
  ],
  "stac_extensions": [
    "https://raw.githubusercontent.com/radiantearth/stac-api-spec/v1.0.0-rc.1/fragments/context/json-schema/schema.json"
  ]
}

The 'data' link returns the full list of collections in my catalog, while the 'child' links point to subcatalogs that permit to organize my catalog in a more structured way as proposed by STAC guidelines. So instead than having 400 collections at home level (impossible to read), I have subdivided collections by subcatalogs so that each subcatalog has maximum 20 collections.

If I do not add the link 'data' then I get what I expect, so a clean home page with browsable subcatalogs:

After adding the data link, the child links are ignored and 401 collections are showed in home:

I could decide not to use the 'data' link but that one is needed for some functionalities (e.g. to load the list of collections in the search page).

From my point of view, if 'child' links exist they should have the priority over 'data' ones. What do you think?

[m-mohr]

From my point of view, if 'child' links exist they should have the priority over 'data' ones. What do you think?

It depends on the API implementation, I've also examples where the opposite should happen or they are meant to be merged. Nothing in the API spec defines a priority as far as I know. So by default I can only merge child links and collections so that all content is potentially shown. We could probably define a config option for it as a new feature, which lets you define a priority. New features must be funded though.

[m-mohr]

I've created radiantearth/stac-api-spec#388 as this might be something for the general API spec, too.

[chiarch84]

I understand that both things might happen.
From my point of view I only added the "data" link in order to make the list of collections appear inside the search box.
I though still don't quite really understand why it is not possible to call the /collections method only when opening the search box and only if it is defined in the conformance classes.
From what I understood, "conformance classes" are meant to describe what your APIs are in fact conformant to, so that a connected application can know which APIs to use and which not. So it should be enough to declare in the "conformance" classes the possible call to /collections to know that it is ok to do that call. Why would you also need the link inside the landing page?
In case the /collections function is not implemented in the APIs than it will not appear in the conformances classes either, so there should not be any inconsistency.

[m-mohr]

The reason is simple: The Collections conformance class requires a data link, you are actually violating the specification by providing a conformance class but omitting the data link. STAC Browser is meant to be spec compliant.
See https://github.com/radiantearth/stac-api-spec/tree/main/ogcapi-features#stac-api---collections

[chiarch84]

Ah ok, in fact this Link relations wasn't really clear to me when I read it. Now I understand better what the specification means. So mainly we've always been returning a json non-STAC compliant, because there is no 'data' link inside, and I cannot add it or it will screw up my home page. At the moment we don't have specific fundings that we could use for this, but let's see in the future.

[m-mohr]

You could support radiantearth/stac-api-spec#388 which makes it more likely to have the feature land in STAC Browser, of course.

[chiarch84]

Hmm ok this could be an idea. Let me first think better of what to suggest for the specs. Not too clear now how to handle all 3 scenarios.

[m-mohr]

Please check PR #270

[chiarch84]

Putting here the link to the tests done to the new functionality.