Offer data
When the MDS EDC UI is opened, the dashboard with information about the Connector is displayed. All further steps start from here. The dashboard contains a lot of useful information about your Connector, from the number of assets up to the Connector endpoint or information about the DAPS to which the Connector is connected.
To offer data you need to define the data asset first. Open the Assets tab and click on Create asset.
Describe your meta-data. As general information you can set e.g.:
- Name: The name of your data.
- Description: A more detailed description of your data offering.
- Keywords: To describe the data offering with keywords and make it searchable inside Broker. Press 'Enter' after each keyword.
- Content Type: Content type of your offer, e.g. 'text/plain'.
- Version: Version of your offer.
- Language: The inherent language of your data.
The complete list of the MDS asset attributes with explanations and examples please find here.
The Mobility Data Space uses a specific ontology for the description of additional mobility related metadata attributes. You need to select at least a suitable data category at 'Advanced Information'.
Define the data source of the asset you want to offer. In addition to the required fields, you can also input parameterization for the URL or method, add query params, add additional required headers or add an API authentication mechanism. Clicking on the Create button will create the asset.
Congratulations! You have just defined your first MDS asset!
By clicking on the asset you created, you can see the details of the asset and can also delete it again, if it has not been used in a contract.
If an offer for the created asset is to be published in the dataspace later, restrictions can be placed via policies on who should be able to see the offer or whether it should only be negotiable at a certain point in time. When a contract is later offered to the dataspace, assets are then linked to the policies. If such restrictions are intended, a policy must now be created that reflects these specific intended restrictions.
Click the Policies tab. The following policies are currently implemented and are either selectable when creating a new policy or already pre-defined:
- Connector-Restricted-Usage: Your data offer can be consumed only through Connectors you whitelist in this policy.
- Time-Period-Restricted: Your data offer can be consumed within the given time range only.
- always-true: This policy does not need to be created and is already predefined. The data offer can be viewed by everyone and a contract can be negotiated at any time and the data can be transferred at any time.
Example of creating a Time-Period-Restricted policy for 2024:
Create a contract offer using the Contract Definitions tab. Choose a unique ID for your contract offer and select already defined policies and data asset(s).
The data offering is now visible in the dataspace under the set conditions.
To publish a data offer in the Catalogue while ensuring it cannot be immediately consumed without prior agreement, follow this workaround:
This process applies to commerical data offerings which are not available for immediate consumption by other members and only serve the purpose of advertising a data offering in the MDS in the data catalogue.
Please note, that you shall name a contact option in the asset description (e.g. e-mail address) so that other participants can get in touch with you.
Use the access policy to determine how the data offer can be viewed by others. Opt for the "always-true" policy to make the data offer visible to all members in the MDS.
To ensure that consumption requires prior negotiation and agreement, set the "connector-restricted" policy as the contract policy. Specify your own Connector endpoint URL as the Connector. This combination allows the data offer to be visible to all, however negotitation of this data offer is not possible and results in an error message.
Should you get a request for consumption (per contact option you mentioned in the offer description) from another member and you are agreed on commercial conditions, you'll need to create a new connector-restricted policy with the connector URL of this member and link it with the existing asset. No additional asset creation is necessary in this process.
Define General and advanced information for your offer as described above.
Additionally you can list in the field Description parameters which should be used on the consumer side. For the link to a documentaion please use the field Endpoint Documentation.
In the Datasource Information part enable the Method parameterization, Path parameterization and Query Param parameterization and set the base URL (e.g. https://api.hamburg.de)
Press Create to create an offer. Then create a Contract offer as described above. In a short time you will see this offer in the Catalog.
For the CaaS you need an access token to call your CaaS-API. Please contact your CaaS-Provider to get your client id, client secret and access token url of your CaaS. Then create the following auth script or you can download this template from here.
curl \ -d 'grant_type=client_credentials' \ -d 'client_id=[Please set your client id]' \ -d 'client_secret=[Please set your client secret]' \ '[Please set the access token url]'
For the On-premise Connector you are able to configure your access yourself depending on authorization mechanism you are using.
Then you need to create a custom json request for the asset creation. Please use this template as template with all available attributes and just remove attributes you not needed.
Last but not least you need to send the json request to your API (in case of CaaS using the authorisation token from the auth script). You can just use this python script as example or write your own script.
Note: use the endpoint POST [Connector base url]/api/management/v3/assets for asset creation.
Please use this Postman collection as template to define customized policies and Contract Definitions.
For the creation of a contract definition with multiple assets you can use this template. Note: use the endpoint POST [Connector base url]/api/management/v2/contractdefinitions for contract definition creation.
Please use this template as example. Don't forget to set your own base URL.