Providing an Importable Feed
Before you start building your feed, it is essential to understand
our Datamodel and What an Entity is.
After familiarizing yourself with the datamodel, you need to scout your existing data, compare it with our structure,
and transform it accordingly.
Requirements
- The feed must be provided in JSON format.
- The feed must contain an array of entities, where each entity is an object with the following properties:
types: An array of types that the entity belongs to.remoteIdentifier: Each entity must have aremoteIdentifierfield. That contains the unique identifier for the entity in your system.content: An object containing the content of the entity.urls: An array of URLs pointing to files related to the entity (optional).
- The feed must be accessible via a public URL, so we can fetch it for import.
1. Scout Data
Carefully examine the data structure in your current system to understand how your information is organized.
Identify which data fields and records are important for you and decide which of them you want to import into our
system.
2. Selection of the correct Types
Next, you need to select the appropriate types from our Datamodel. That can be difficult depending on what your data model looks like. To help you with this, we recommend the following steps:
- First, review our Datamodel to understand the available types.
- Compare your existing data with our Datamodel. This comparison will help you identify overlaps, similarities, and structural differences between your system and ours. By doing so, you can find a common ground that allows you to align your data with our structure effectively.
- If you find that your data does not fit perfectly into our types, consider how you can adapt or transform your data to align with our structure.
- If necessary, consult with our support team or documentation to clarify any uncertainties regarding the types and their usage.
3. Transform Data
Once you have selected the appropriate types, the next step is to transform your data to fit our structure.
In order to know which data fields must/can be mapped, it is now important to find out which data fields result from the defined types.
For this, you can visit our Datamodel Types documentation (https://datamodel.social.vns.services/schema/types/{type}), where you can find detailed information about each type and its associated fields.
(You can replace the {type} placeholder with the type you want to look at, for example schema:Event or venus:hotel)
After identifying the necessary fields, you can start transforming your data to match our structure.
This may involve renaming fields, changing data formats, or restructuring your data to fit our requirements.
Make sure that each field in your data corresponds to the correct type and follows the conventions of our
Datamodel.
Remote Identifier (remoteIdentifier)
Each entity in your feed must have a remoteIdentifier field that contains the unique identifier for the entity in your system.
This identifier is crucial for establishing a relationship between your data and our system.
It is important to ensure that this identifier is consistent and does not change over time, as it will be used to
reference the entity in our system.
Files
If you have files (e.g., images, documents) that you want to include in your feed, you can reference them in your JSON file.
You can do this by providing the URLs of the files in the urls field of your JSON feed.
Make sure that the URLs are accessible and point to the correct files.
4. Combine Feed
After transforming your data to match our structure, the final step is to combine all converted elements into a single JSON file. This file will serve as your import package, containing all the entities and information you want to include in our system.
You can publish the file on different platforms, such as a web server or a cloud storage service, and share the URL with us.
The only requirement is that the file must be accessible via a public URL, so we can fetch it for import.
Feed Example
This is an example of how your feed should look like.
It contains a single entity of type schema:Event with various fields populated according to our
Datamodel.
You can use this as a reference to create your own feed.
[
{
"types": [
"schema:Event"
],
"remoteIdentifier": "abc-123",
"content": {
"venus:eventSchedule": [
{
"startDate": "2077-02-22T23:00:00.000+0000",
"endDate": "2077-02-22T23:59:59.999+0000",
"doorTime": "08:00",
"startTimezone": "Europe/Berlin",
"endTimezone": "Europe/Berlin",
"allDay": true
}
],
"schema:name": [
{
"lang": "de-DE",
"value": "Gamescom 2077"
},
{
"lang": "en",
"value": "Gamescom 2077"
}
],
"schema:description": [
{
"lang": "de-DE",
"value": "<pre><code class=\"language-plaintext\">Die Gamescom ist die weltweit größte Gaming-Veranstaltung. Sie findet jährlich in Köln, Deutschland statt.</code></pre>"
},
{
"lang": "en",
"value": "<pre><code class=\"language-plaintext\">Gamescom is the world's largest gaming event. It takes place annually in Cologne, Germany.</code></pre>"
}
],
"venus:topics": [
"venus:profession",
"venus:music_school",
"venus:exercise"
],
"schema:address": {
"country": "Deutschland",
"city": "Atting",
"zip": "94348",
"street": "Flugplatzstraße 2"
},
"schema:duration": 720,
"schema:latitude": 48.902269149999995,
"schema:longitude": 12.513263756471972,
"schema:maximumAttendeeCapacity": 20,
"schema:genre": [
"venus:live",
"venus:design",
"venus:technology",
"venus:graphic",
"venus:video_art",
"venus:pop_culture",
"venus:fantasy",
"venus:science_fiction",
"venus:horror",
"venus:action",
"venus:animation"
],
"schema:url": [
{
"lang": "de-DE",
"value": "hier-eine-webadresse.de"
}
]
},
"urls": [
"https://example.com/files/file.json",
"https://example.com/files/picure1.png",
"https://example.com/files/picuter2.jpeg"
]
}
]