About process description - attribution

[francescoingv]

As processes will likely play an important role in the context of AI-ready items, I wonder whether it would be appropriate to have a specific field in the process description (e.g. in processSummary.yml) dedicated to attribution.

In scientific and research environments, attribution is quite important, for example to indicate the author(s) of a process, possibly the version, and related provenance information.

I understand that the links property could potentially be used to point to related references, but it appears to be quite generic for expressing attribution information in a structured way.

Would it make sense to consider introducing an optional attribution field in the process description, or is there already a recommended way to represent this kind of information within the current specification?

I would be interested to know whether this topic has already been discussed or if there are existing patterns or best practices within the OGC API ecosystem.

Thank you

[pvretano]

The process description already has a metadata member (see here and here). Could you use that to encode that sort of information? That information is extensible.

[francescoingv]

Thank you @pvretano, I missed that.

The metadata member indeed seems flexible enough to encode this kind of information.

It might be helpful to include an example in the official documentation showing how citation or attribution information could be represented using the metadata member.

This could also support FAIR principles (in particular proper attribution and provenance), which are quite relevant in scientific and research contexts.

Just a thought — I would be interested to hear if there are existing conventions or best practices within the OGC API ecosystem.

[pvretano]

@francescoingv I'll try to do that but I'm pretty bandwidth limited these days. If you have some free cycles and can pop an example into this chat, I'll be sure to add it to the document before we ship it off to OGC for the RFC process ... and it would be very much appreciated! ;)

[fmigneault]

Depending on the method employed to represent the "internals" of the process (i.e.: the OGC Application Package, CWL or any other), additional metadata is also typically possible.

For example, CWL provides the following metadata fields: https://github.com/crim-ca/ogc-ospd-phase1/blob/5edd4ec4cbd21e5fceb7c3f4b6c5d0ce809a57ea/ogc_app_pkg/algae-usecase-workflow-copernicus.cwl#L5-L29

(CWL <-> OGC fields mapping for metadata: https://pavics-weaver.readthedocs.io/en/latest/package.html#metadata)

As for provenance, I suggest looking into Part 4 Requirements Class “Provenance”
Note that it is still under development, but the idea is that you can get an entire W3C PROV metadata from a job execution.
This has been demonstrated to work with OGC API Processes during Open Science Persistent Demonstrator pilots.
Here's an overview of what endpoints could look like: https://pavics-weaver.readthedocs.io/en/latest/processes.html#job-provenance
And the corresponding OGC Building Blocks supporting these definitions: https://ogcincubator.github.io/bblocks-openscience/
(see the linked graph under https://ogcincubator.github.io/bblocks-openscience/bblock/ogc.osc.api-profiles.processes.ospd)

[francescoingv]

Hi @pvretano, thanks very much the suggestion.

I agree that the existing metadata member seems flexible enough to encode attribution information without introducing new fields into the specification.

Regarding provenance, I understand that Part 4 is intended to address this aspect more formally, and I appreciate the references shared by @fmigneault. At this stage I was mainly referring to OGC API - Processes Part 1, so providing a complete provenance example would probably be premature (and in any case somewhat beyond my current expertise).

Since you asked for an example, below is a possible way attribution information could be represented using the existing metadata and links members. The intent was also to roughly map the kind of metadata that appears in CWL workflows, such as the one referenced above.

id: example_id
version: "1.0.1-beta"

title: Simple example process
description: >
  This process performs an echo
  of all the allowed input to the output.

keywords:
  - echo
  - test

metadata:
  - title: Author Full Name
    role: author
    href: https://orcid.org/0000-0002-1234-5678

  - title: Contributor Full Name
    role: contributor
    href: https://orcid.org/0000-0003-9876-5432

  - title: Maintainer Full Name
    role: maintainer
    href: https://orcid.org/0000-0003-9876-5457

  - title: Source repository
    role: repository
    href: https://github.com/example/echo

links:
  - href: https://example.org/docs/echo
    rel: describedby
    type: text/html
    title: Process documentation

  - href: https://opensource.org/licenses/MIT
    rel: license
    type: text/html
    title: MIT License

This approach allows representing basic attribution information (authors, repository, documentation, license) without extending the current schema.

The intent here is not to introduce new fields, but simply to illustrate a possible usage pattern of the existing metadata member for attribution purposes.

This could also help support FAIR principles, in particular proper attribution and traceability in scientific and research workflows.

[fmigneault]

This is the way I used to do based on old OGC testbeds.
https://hirondelle.crim.ca/weaver/processes/ogc-tb16-land-cover-mapping?f=html#metadata

metadata:
- title: Provider Name
  lang: en-CA
  value: Computer Research Institute of Montreal (CRIM)
  role: http://www.opengis.net/eoc/applicationContext/providerMetadata
- title: Nom du fournisseur
  lang: fr-CA
  value: "Centre de Recherche Informatique de Montréal (CRIM)"
  role: http://www.opengis.net/eoc/applicationContext/providerMetadata
- title: Provider Site
  hreflang: en-CA
  href: https://www.crim.ca/en
  type: text/html
  rel: provider-site-en
  role: http://www.opengis.net/eoc/applicationContext/providerMetadata
- title: Page du fournisseur
  hreflang: fr-CA
  href: https://www.crim.ca/fr
  type: text/html
  rel: provider-site-fr
  role: http://www.opengis.net/eoc/applicationContext/providerMetadata

Nowadays, I would probably consider some other JSON-LD definition like: https://doi.org/10.5063/schema/codemeta-2.0
https://w3id.org/codemeta/3.0
in order to annotate specific role based on contextual URIs and anchors.
(open to hear about alternatives if you know any)

[bpross-52n]

Does the SWG have an action to take away from this or can we close the issue?

[bpross-52n]

The SWG should think about where to put the provenance requirements class, might even be an additional Part 5. At the very least, some more guidance about the schema for provenance should be given.

[francescoingv]

From my perspective, no change to the specification seems necessary. The existing metadata member already provides enough flexibility to represent attribution information.

However, it might still be useful to include an example in the documentation showing how attribution (e.g. authors, contributors, repository, license) could be expressed using metadata and links, particularly for scientific or research workflows and in support of FAIR principles.

If that would be helpful, the example I shared above could potentially serve as a starting point, possibly integrated with the example based on old OGC testbeds from @fmigneault . Otherwise I’m fine with closing the issue.

[fmigneault]

I agree with @francescoingv.

Following are my suggested actions :

1. Add an example with common authorship information (most common case, as shown above).
2. Because metadata allows both by-link and by-value information, demonstrate both in the included example.
3. Because metadata has language concepts, corresponding hreflang/lang for href/value variants should be indicated. Notably, this should show how the same role (and rel if link) can be shared across multiple translations of the metadata.
4. A recommendation (/rec/) should be added referring to https://w3id.org/codemeta/3.0, https://schema.org/, or other schema/ontologies that should ideally be used for the role property to provide more context about the referenced metadata in value or href. Such URIs would help interpret the metadata properly across implementations and avoid subtle ambiguities. This is specifically important when value: {} is used, since it can be any JSON content!
5. We cannot make the use of URIs a requirement since plain role might be relevant for other use cases.

[pvretano]

@francescoingv @francescoingv if one of you could come up with the example to add to the standard that would be much appreciated ... I don't have too many free cycles these days! ;)

[francescoingv]

Merging my example with the one suggested by @fmigneault , the following could be a possible result.
The structure follows the process description schema defined in: https://github.com/opengeospatial/ogcapi-processes/tree/master/openapi/schemas/processes-core

id: example-echo-process
version: "1.2.0"

title: Echo
description: >
  Echo example to include attribution metadata.

keywords:
  - echo
  - test
  - metadata

metadata:
  - title: Provider Name
    lang: en-CA
    value: Computer Research Institute of Montreal (CRIM)
    role: http://www.opengis.net/eoc/applicationContext/providerMetadata

  - title: Nom du fournisseur
    lang: fr-CA
    value: "Centre de Recherche Informatique de Montréal (CRIM)"
    role: http://www.opengis.net/eoc/applicationContext/providerMetadata

  - title: Provider Site
    hreflang: en-CA
    href: https://www.crim.ca/en
    type: text/html
    rel: provider-site-en
    role: http://www.opengis.net/eoc/applicationContext/providerMetadata

  - title: Page du fournisseur
    hreflang: fr-CA
    href: https://www.crim.ca/fr
    type: text/html
    rel: provider-site-fr
    role: http://www.opengis.net/eoc/applicationContext/providerMetadata

links:
  - href: https://example.org/processes/example-echo-process/docs
    rel: describedby
    type: text/html
    title: Process documentation

  - href: https://example.org/processes/example-echo-process/openapi
    rel: service-desc
    type: application/vnd.oai.openapi+json;version=3.0
    title: OpenAPI definition

  - href: https://spdx.org/licenses/MIT.html
    rel: license
    type: text/html
    title: MIT License

This example illustrates how attribution information (provider, provider site, multilingual variants) can be represented using the existing metadata and links members without extending the current schema.

[francescoingv]

@fmigneault perhaps we could also include an example entry for an author using the same pattern as the provider metadata. For instance:

- title: Author Name
  lang: en
  value: Jane Doe
  role: author

where the role should be replaced with a more appropriate URI or convention for authorship.