enum constraint for `properties.type`?

[soxofaan]

This came up in EarthCODE meeting today:
why is there this enum constraint on properties.type?:
https://github.com/EOEPCA/metadata-profile/blob/24d2755d1eed34e1e5441cd1b22576adc72a37ea/schemas/resource.json#L756-L767

related to ESA-EarthCODE/EarthCODE#5

cc @Schpidi

[rconway]

The enum is to enforce some standardisation regarding the type of the resource - which is important to make discovery and use of resources easier to consume in clients.
This enum is an initial list that can be extended as required.
@soxofaan Is there a missing type for your current needs?
@kalxas to comment

[soxofaan]

To sketch some context: in ESA-EarthCODE/EarthCODE#5 we are facing the problem that we want to align an "APEx algorithm" document with this schema, but there we use "type": "apex_algorithm", which is not valid against the current enum constraint.

I don't think we want to push to add "apex_algorithm" to the enum, that seem like too much coupling.

But on the other hand, we still like to have some identifier in the document to clearly indicate that it is an "APEx algorithm" description. In an OOP interpretation, an "APEx algorithm" would be a subclass of a workflow I guess, so maybe we should use a field like "subtype". Or are there any other recommendations or conventions to define such a subclass/subtype relation?

[JanssenBrm]

As discussed during the latest EarthCODE/APEx/EOEPCA+ meeting, EOEPCA is going to provide access to a Google Docs environment that will allow all projects to provide their definitions of the different concepts. Based on this, a decision will be made to align the property types across all initiatives.

[JanssenBrm]

The following is an example of an APEx OGC API Record for an openEO User Defined Process. Some important considerations that are currently specific for APEx:

• The type is currently a custom value but this could be aligned to use service.
• We need a clear way to distinguish between records that represent an openEO or OGC API Processes based service. So maybe a subtype is worth considering ("type" of an APEx algorithm OGC record ESA-APEx/apex_algorithms#65)
• The information from the records, and specifically the links section, is used to build a user interface for browsing the records. We are discussing the alignment of these links at Align on the usage of the relationships in the links section ESA-APEx/apex_algorithms#67.

{
  "id": "biopar",
  "type": "Feature",
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core"
  ],
  "geometry": null,
  "properties": {
    "created": "2024-10-03T00:00:00Z",
    "updated": "2024-10-03T00:00:00Z",
    "type": "apex_algorithm",
    "title": "Calculate various biophysical parameters",
    "description": "The algorithm offers a solution to calculate vegetation-related parameters like leaf area index, fraction of absorbed photosynthetically active radiation, and more.",
    "cost_estimate": 4,
    "cost_unit": "platform credits per km²",
    "keywords": [
      "agriculture",
      "crops"
    ],
    "language": {
      "code": "en-US",
      "name": "English (United States)"
    },
    "languages": [
      {
        "code": "en-US",
        "name": "English (United States)"
      }
    ],
    "contacts": [
      {
        "name": "Jeroen Dries",
        "position": "Researcher",
        "organization": "VITO",
        "links": [
          {
            "href": "https://www.vito.be/",
            "rel": "about",
            "type": "text/html"
          },
          {
            "href": "https://github.com/jdries",
            "rel": "about",
            "type": "text/html"
          }
        ],
        "contactInstructions": "Contact via VITO",
        "roles": [
          "principal investigator"
        ]
      },
      {
        "name": "VITO",
        "links": [
          {
            "href": "https://www.vito.be/",
            "rel": "about",
            "type": "text/html"
          }
        ],
        "contactInstructions": "SEE WEBSITE",
        "roles": [
          "processor"
        ]
      }
    ],
    "themes": [
      {
        "concepts": [
          {
            "id": "Leaf Area Index (LAI)"
          },
          {
            "id": "Fraction of Absorbed Photosynthetic Active Radiation (fAPAR)"
          },
          {
            "id": "Fraction of Vegetation Coverage (fCOVER)"
          },
          {
            "id": "Sentinel-2 MSI"
          },
          {
            "id": "Canopy Water Content (CWC)"
          },
          {
            "id": "Canopy Chlorophyll Content (CCC)"
          }
        ],
        "scheme": "https://gcmd.earthdata.nasa.gov/kms/concepts/concept_scheme/sciencekeywords"
      }
    ],
    "formats": [
      {
        "name": "GeoTiff"
      }
    ],
    "license": "other"
  },
  "linkTemplates": [],
  "links": [
    {
      "rel": "application",
      "type": "application/vnd.openeo+json;type=process",
      "title": "openEO Process Definition",
      "href": "https://raw.githubusercontent.com/ESA-APEx/apex_algorithms/refs/heads/main/openeo_udp/biopar/biopar.json"
    },
    {
      "rel": "service",
      "type": "application/json",
      "title": "CDSE openEO federation",
      "href": "https://openeofed.dataspace.copernicus.eu"
    },
    {
      "rel": "license",
      "type": "text/html",
      "href": "https://apex.esa.int/license"
    },
    {
      "rel": "example-output",
      "type": "image/tiff;application=geotiff;",
      "title": "Example output",
      "href": "https://s3.waw3-1.cloudferro.com/swift/v1/apex-examples/biopar/biopar-example.tif"
    }
  ]
}

[JanssenBrm]

The following is an example of APEx OGC API Record for an OGC API Process. The same considerations as above apply here as well.

{
  "id": "gep_bas",
  "type": "Feature",
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core"
  ],
  "geometry": null,
  "properties": {
    "created": "2024-12-18T00:00:00Z",
    "updated": "2024-12-18T00:00:00Z",
    "type": "apex_algorithm",
    "title": "Burned Area Severity (BAS) analysis",
    "description": "The Burned Area Severity (BAS) service takes as input a pair of optical datasets in their native format, and estimates the severity of burnt areas by using swir22 and nir radiation. The burn severity describes how the fire intensity affects the functioning of the ecosystem in the area that has been burnt. The observed effects often vary within the area and between different ecosystems (Keeley, 2009). The burn severity can also be described as the degree to which an area has been altered or disrupted by the fire.",
    "cost_estimate": 1.5,
    "cost_unit": "\u20ac per input product",
    "keywords": [
      "burn severity",
      "fire impact",
      "remote sensing",
      "optical imagery",
      "NBR",
      "dNBR",
      "RBR"
    ],
    "language": {
      "code": "en-US",
      "name": "English (United States)"
    },
    "languages": [
      {
        "code": "en-US",
        "name": "English (United States)"
      }
    ],
    "contacts": [
      {
        "name": "Platform team",
        "position": "Platform Operations",
        "organization": "Geohazards Exploitation Platform (GEP) by Terradue",
        "links": [
          {
            "href": "https://geohazards-tep.eu",
            "rel": "about",
            "type": "text/html"
          }
        ],
        "contactInstructions": "For inquiries, please email the Platform team",
        "email": "contact@geohazards-tep.eu",
        "roles": [
          "processor",
          "service provider"
        ]
      }
    ],
    "themes": [
      {
        "concepts": [
          {
            "id": "DISASTER MANAGEMENT"
          },
          {
            "id": "REMOTE SENSING"
          }
        ],
        "scheme": "https://gcmd.earthdata.nasa.gov/kms/concepts/concept_scheme/sciencekeywords"
      }
    ],
    "formats": [
      {
        "name": "GeoTiff"
      },
      {
        "name": "PNG"
      },
      {
        "name": "JPEG"
      }
    ],
    "license": "CC-BY-4.0"
  },
  "linkTemplates": [],
  "links": [
    {
      "rel": "application",
      "type": "application/cwl+yaml",
      "title": "Service Application Package",
      "href": "https://repository.terradue.com/artifactory/gep/app-packages/production/burned-area-severity-one-shot.0.1.1.cwl"
    },
    {
      "rel": "service",
      "type": "application/json",
      "title": "Service Endpoint",
      "href": "https://ades.gep.terradue.com/gep/wps3/processes/burned-area-severity-one-shot-0_1_1"
    },
    {
      "rel": "preview",
      "type": "image/png",
      "title": "Preview of the Burned Area Severity service result on the Disaster Charter Platform",
      "href": "https://docs.disasterscharter.org/services/burned-area-severity/media/tutorial-bas-011.png"
    },
    {
      "rel": "order",
      "type": "text/html",
      "title": "Request Access",
      "href": "https://geohazards-tep.eu/#!web_store"
    },
    {
      "rel": "license",
      "type": "application/pdf",
      "title": "End-User License Agreement",
      "href": "https://geohazards-tep.eu/downloadFiles/EULA-GEP.pdf"
    },
    {
      "rel": "about",
      "type": "text/html",
      "title": "Service Documentation",
      "href": "https://geohazards-tep.gitlab.io/gep-docs/services/burned-area-severity/service-specs/"
    },
    {
      "rel": "webapp",
      "type": "text/html",
      "title": "Web App",
      "href": "https://geohazards-tep.eu/geobrowser/?id=opt-bas-app"
    }
  ]
}

[JanssenBrm]

Below is a summary of APEx’s suggestions. We welcome feedback and alternative proposals, as we believe that a common, aligned approach between EarthCODE and APEx on the following topics would benefit both projects.

1. Identification of Service/Workflow/Experiment Type

Both EarthCODE and APEx require a property to provide a more detailed description of a record’s content. While properties.type can categorize records at a high level—such as service, workflow, or experiment—both projects need a way to specify the exact nature of the record. For instance, a record could reference an openEO implementation, an OGC API Process, an OGC Application Package, or a Jupyter Notebook. Although this information could technically be inferred from the link field, relying on custom logic (e.g., iterating through links and interpreting them) may not be ideal.

To address this, as @soxofaan suggested, we propose introducing a subtype property. This would allow for explicit categorization using values such as openeo_pg, openeo_udp, ogc_ap, ogc_api_process, jupyter_notebook, etc.

2. Alignment on Relationship Types

As discussed in ESA-APEx/apex_algorithms#67, aligning on relationship (rel) definitions could improve consistency, ensuring that records from EarthCODE and APEx are interpreted in the same way. The suggestion in the ticket is shown in the table below. However, it is important to note that not all relationships might be relevant for EarthCODE.

rel	description
application	URL to the openEO PG/UDP, OGC AP, Jupyter Notebook
service	Link to the openEO backend or to the OGC API Processes endpoint
example-output	Example of execution results
example-input	Example of input parameters
preview	URL to an image previewing the usage of the service or its results
order	Link to the HTML page to order the service (custom/NoR)
license	Link to the license file
about	Link to the technical documentation
webapp	Link to the web application for executing the service

[JanssenBrm]

@m-mohr, @Schpidi - Feel free to share your thoughts on the suggestions above.

[m-mohr]

@JanssenBrm I was wondering whether it would make sense to indicate the subtype through the conformsTo property, by providing a schema you could also actually point to some validation schema yourself (although they are not used automatically for validation as that's not foreseen by OGC).

I think the relation types should be aligned between this approach and the EarthCode Open Science Catalog, especially application.