podManagement.bs

Pod Management {#podManagement}
=====================

It is crucial for the interoperability that we handle the POD data in the same way. Here is a proposal of what we can do. Note that this pretends to be an
starting point to the complete specification, and so it is open to discussion.

## File format ## {#fileFormat}
For the file format we can use JSON-LD, we have used JSON along the degree and we are very familiar with it,
it won't be a problem to handle that in the application, in fact Javascript facilitates that task with the built-in object "JSON".


### File example ### {#fileExample}
What comes next is an example of the **minimum** data that should be stored in the pod with the JSON-LD. More data could be added by our apps,
but at least this should be there.

The following properties can be found:

* name: the name of the route.
* author: the webId of the creator of the route (optional).
* description: a description of the route (optional).
* waypoints: a list of waypoints (optional).
* points: points of the route, describing the path.
* comments: a link (@id) to a file related with the route where the users comments will be stored.
* date: the date of creation of the route (optional).
* media: a list of links to resources. Also contains the optional property "name" for each media element.

The example (if any error is seen in the context, please point it out):

_If it cannot be seen in the include please check it manually because afterwards there will be mentions about it._
<pre class="include">path: jsonldProposal/jsonldExample.json</pre>

## Directory hierarchy in the POD ## {#directoryHierarchy}
Not only we need to state what information should be in the pod, but also where it is located.

We proposed a "viade" folder in the root of the pod, and inside it three folders: routes, comments, resources.

<pre>

viade/

		routes/

			example.jsonld
			example2.jsonld

		comments/

			ruta1Comments.jsonld
			ruta2Comments.jsonld

		resources/

			foto.jpg
			image.png
			video.mp4

		inbox/

			sharingNotification1.jsonld
			sharingNotification2.jsonld

		shared/

			luispresacollada.solid.community.jsonld

</pre>

### Comments and resources ### {#resources}

Each route will have linked a file for the comments from the very momment of its creation. In this file the users that have received the route in a share operation can
post their comments. This approach is highly efficient and by using it we get rid of permissions problems with respect to the one that stores the comments of each user in
his pod.

Such files just to follow a convention are supposed to be stored in viade/comments folder, although since we are navigating through a graph it is not really important from
the interoperability point of view where is the file.


Consider the following example:

Luis published a route long ago, and now he shared it with his friend Sara. Sara wants to comment it. Sara will access the comments file of the route by means of the route
file, and she will post there her comment. She has permissions because Luis gave them to her when sharing the route.

You can find examples of the files int the jsonlfProposal folder.


## What should be done about GPX? ## {#gpxToJson}
A gpx file can contain several elements "trk" (from the word "track") which are the ones that match our concept of "Route", that is a path, a sequence of points. Inside this label we can have
several "trkseg", which stand as sequences of ordered points (trkpt). Our duty will be to take all the trkpt and put them inside the "viade:points" property of the example json.

The gpx trk label can have a name and a description so it could be direct translation. Or we may want the user to introduce that data, that's an app design decision.

There is a type of points in a GPX called "waypoints", they are relevant points that are in some way related to the specified tracks. Assuming a path across a city,
a waypoint can be a church, a restaurant, a monument, and so far so forth. We will include this points in our routes jsonld files. They will have name, description  and coordinates.
Check the provided example to see its implementation. Elevation and description are optional attributes.


## How to share ## {#share}
We have performed a voting in order to follow the approach of the permissions, or use the inbox folder in order to manipulate the sharing functionality. In the end we wil be using the second
one. But for such a task we need some kind of agreement in the file structure in the "receiver". Assume Luis wants to share a route with Sara. Luis will give her permissions to the files,
and send her a notification, with the webid of the route and his own webid. Sara's app will parse the notification and add that route id to a file.

Such files will be placed in the folder viade/shared, and will have a name such as: luispresacollada.solid.community. (The corresponding part of the webID)
You may check the structure in the file "sharedRoutesExample", it contains a simple list with @id pointing to the shared routes.

<pre class="include">path: jsonldProposal/sharedRoutesExample.json</pre>