It must include the documentation/detail of the API specification that each platform wanting to use the data sharing permissionning module will need to implement. This issue needs to be declined, one per platform to be adapted, to manage the different specificities of every platform. Regarding the API, we imagine that the data sharing module will respect a LDP-compliant API allowing GET and POST/DELETE on a /portals/ containers which allow the producers to assign/update/remove the defined client scopes to the existing parties/portals. We are making different assumptions in the current work: - We should rely on a taxonomy of scope which is globally available, so that we can also easily retrieve the localized version based on the xml:lang approach on labels in the ontology (for a next step) - We should rely on a list presenting which platforms are available and where are their webIds. - We need a webId for each and every platform to get additional information like logo and description, platform url - Every application will implement some JSON-LD endpoints to retrieve and manage the association between those scopes and producers, and return graphs bearing list of resources. - The LDP spec is the one applied for POST/PATCH/PUT - Every application will secure their producers related existing API endpoints using the check on those association between scopes and portals, based on an authentication header they receive in every requests - We are using a LDP basic Containers based representation Limitations: - This does not allow a granular approach of data sharing permissions per field, but only per API endpoint, in a simplified way compared to the Dataspace protocol for instance. - It also does not cover the different points from [the UI spec here](https://openteamag.gitlab.io/agricultural-data-wallet/designrecs/#data-sharing-ui): - Ability to select which datasets will be shared, and to see a preview of the data. The preview may be in a table format or a map format, or other formats as appropriate. - Ideally there is an option to select a subset of a dataset to share, such as specific columns from a spreadsheet - For each dataset, the ability to specify whether it can be shared with additional third parties - Ability to set an expiration date after which the data will no longer be available unless permission is renewed - Ability to set whether data is shared ongoing, or just one time This one: > For each dataset, the ability to specify whether it can be shared with additional third parties Could be handled by defining a specific "subscope" for that. This one: > Ability to set whether data is shared ongoing, or just one time Would need actual data transfer and usage monitoring, and it raises questions. Who is managing the reporting of this access ? Is it a monitoring service to be implemented by every applications ? Sounds heavy. If there is a centralized monitoring service, what trust can we have in it ? We consider that we have the "enterprises" endpoint (with every enterprise having their own webid), we need to define a GET and a POST/PUT/PATCH requests to push the portal/scope association. A really rough API definition for that could look like: ```yaml openapi: 3.0.0 info: title: Data Sharing Module API Definition version: 1.0.0 description: API for managing OIDC custom scopes and portals with producer-specific associations using JSON-LD and LDP principles. paths: /producers/{producerId}/scopes/{scopeId}: get: summary: Get producer-specific scope details parameters: - name: producerId in: path required: true schema: type: string - name: scopeId in: path required: true schema: type: string responses: '200': description: Scope details for the producer content: application/ld+json: schema: type: object properties: '@id': type: string description: type: string portals: type: array items: type: object properties: '@id': type: string name: type: string post: summary: Add a new producer-specific scope association parameters: - name: producerId in: path required: true schema: type: string - name: scopeId in: path required: true schema: type: string requestBody: required: true content: application/ld+json: schema: type: object properties: portalId: type: string responses: '201': description: Scope association added successfully content: application/ld+json: schema: type: object properties: message: type: string delete: summary: Remove a producer-specific scope association parameters: - name: producerId in: path required: true schema: type: string - name: scopeId in: path required: true schema: type: string requestBody: required: true content: application/ld+json: schema: type: object properties: portalId: type: string responses: '200': description: Scope association removed successfully content: application/ld+json: schema: type: object properties: message: type: string ```