Offer data via Frontend
Generally if you want to offer data via the MDS you should directly define a data source for this offer (e.g. your backend-API).
To make it easier for new participants to get started within the MDS and to save unnecessary costs for unused data pipelines the MDS invented another data offer type called data offer on request which allowed to add data source to an asset at a later date. Data offer on request also differs from the standard data offers in that it has a slightly different icon in the catalog browser and in the assets overview.
It is therefore clear to both the provider and the consumer that the asset is offered on request. The consumer of a data offer on request should contact the provider using the contact mask in order to access the real data source. The provider can easily transform a data offer on request in the standard data offer adiing the data source and descriptive metadata and vice versa.
Generally you have two alternatives for the data offer creation. You can separately create an asset, a policy and then a data offer which combines both or you can use the data offer wizard to create all necessary components in a flow. The wizard provides you the choice of how the asset should be published in the data space. As soon as everything is filled in and the Publish button is pressed, a data offer is created automatically and the asset will be published in the data space under the specified policies.
Note: Data offer on request can be created with data offer wizard only.
Below we intentionally start with the separate creation of assets, policies and data offers so that you have a better understanding of single fields and functionalities.
Feel free to skip this introduction and start right away with the data offer wizard. In the data offer wizard the same fields are used, but in a slightly different order, data source description comes at first.
Open the Assets tab and click on Create asset. At least the mandatory fields marked with an asterisk should be filled out.
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 can be found 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'.
Then 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 default, the "always true" policy has already been created at the start of the connector. It can be used to offer data to any other connectors in the data space without restrictions.
If you want to restrict the visibilty or the availability of your asset, these restrictions can be defined via policies.
Three different types of policies are available:
- Evaluation Time: If this policy type is selected, a date can be specified so that the data offers are only visible or valid until this date.
- Participant ID: With this policy, the data offering can be offered only for specific connectors based on their Connector ID. This Connector ID must be known at this time.
- Timespan Restriction: This policy can be used to specify a time period during which the data offering can be visible or accessed.
Policies can also be combined. In other words, several policies can be fulfilled at the same time or independently of each other, depending on the selection.
Use combine option and the + sign with logical operators to create restricted policy you need.
Once defined policies can be later re-used. Policies can be also deleted if not needed anymore and not used in existing data offers.
In order to make your data accessible to other data space participants, you have to create a data offer using the Data Offer tab. A data offer links policies to your assets and then offers it in your catalog, so that other participants can query these offers and, depending on the policy set, can see them in their catalog browser and initiate a contract negotiation.
- ID: Give your contract definition a unique name.
- Access Policy: Determines the conditions under which the data offer is visible to other Connectors when crawling your offers.
- Contract Policy: Determines the conditions under which the data offer is available to other Connectors.
- Assets: Choose the assets you want to offer with this contract definition (more than one asset is allowed).
The data offering is now visible in the dataspace, if chosen policies allow this.
To create a data offer on request please select On Request (without data source). The following fields must be filled in: "Contact E-Mail", "Preferred Mail Subject", "Title", "Description" (in some UI versions falsely labeled as "Reference files description"), "Data category".
To create a standard data offer please select Available (with data source). The following fields must be filled in: "Method", "URL", "Title", "Description" (in some UI versions falsely labeled as "Reference files description"), "Data category".To use more metadata fields please select Show advanced fields. Explanations about meaning of metadata fields can be found here.
At the end of the data offer creation process you can select a publishing option. If you select publish unrestricted the offer will be published with "Free use" policy (visible and available for all MDS participants). Otherwise you can select publish restricted and then you can choose policy you want to have or combine different restrictive policies. More information about policies can be found here. If you select Create asset only the asset will be created, but data offer will not. As a result, your asset will not be visible in the MDS catalogue or for a consumer connector.
Note: The data offer creation wizard always creates a same policy for the visibility and the availability of the offer. If you want to use different policies for the visibility and availability of the offer please use the flow described above.
By clicking on the asset you created, you can see the details of the asset and can also edit or delete it, if it has not been used in a contract.
You also have a possibility to transform the data offer of request into the standard data offer and vice versa.
Important note: It is allowed to use the editing feature for small metadata modifications like typo corrections and insignificant additions. You can also change a data source if needed (please don't forget to update the endpoint documentation field if applicable).
The editing feature is not intended for complete changes of the data offer. If you are going to change the data offer or essential parts of the data offer description please create a new asset.
You can use the data offer on request as placeholder for the commercial data offer.
If you receive a request for this offer (per contact e-mail you mentioned in your data offer of request) from another MDS member and agree on the commercial terms, you can then create a standard data offer with a data source and a connector-restricted policy, using that member's MDS connector ID. For each additional request from other members, you should create a new connector-restricted policy and link it to the existing asset.
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.
You can use both the data offer wizard and separated flow (as described above) to create a parametrized data offer.