Arquisoft / viadeSpec

Viade Data Model Specification
https://arquisoft.github.io/viadeSpec/
MIT License
7 stars 1 forks source link

Proposal for a route format standard #2

Open carlosmanri opened 4 years ago

carlosmanri commented 4 years ago

Proposal for a route format

The use of a subset of the existing "Trip" scheme from schema.org is proposed to structure the route data

I have tried to reduce the number of properties to the minimum possible, but always with the future in mind in order to extend it in the future if changes arise that would make us require more information

Next, the schemes used that will make up the route are broken down. At the end of the document you can see two examples of routes

Already existing schemas and fields in use

As the web Schema.org says:

Schema.org is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet, on web pages, in email messages, and beyond. Schema.org vocabulary can be used with many different encodings, including RDFa, Microdata and JSON-LD. Founded by Google, Microsoft, Yahoo and Yandex, Schema.org vocabularies are developed by an open community process, using the public-schemaorg@w3.org mailing list and through GitHub.

To define the route, existing schema.org schemes have been used. This allows us to create a format that is compatible with existing structured data.

A property name in bold means that it is mandatory to define the route

Trip

Complete schema: Trip Property Expected type Description
name Text The name of the route
description Text A brief description of the route
itinerary ItemList Destinations that make the trip. ItemList ensures the order of the elements

GeoCoordinates

Complete schema: GeoCoordinates Property Expected type Description
name Text The name of the place
address Text Physical address of the item
addressCountry Text The country, You can also provide the two-letter ISO 3166-1 alpha-2 country code
elevation Number The elevation. Assumed in meters
latitude Number The latitude of a location
longitude Number The longitude of a location
description Text A brief description of the place
postalCode Text or Number The postal code
image ImageObject or URL An image of the place

ImageObject

Complete schema: ImageObject Property Expected type Description
contentURL URL Actual bytes of the media object, for example the image file or video file.

ItemList

Complete schema: ItemList Property Expected type Description
itemListElement GeoCoordinate Element that represent a waypoint in the route
itemListOrder itemListOrderType Type of ordering (e.g. Ascending, Descending, Unordered)
numberOfItems Integer Number of items in the list.

Example of a complete route

{
  "@context": "http://schema.org",
  "@type": "Trip",
  "name": "A route 1",
  "description": "The test route with all the properties",
  "itinerary": {
    "@type": "ItemList",
    "numberOfItems": 1,
    "itemListOrder": "http://schema.org/ItemListOrderDescending",
    "itemListElement": [
      {
        "@type": "GeoCoordinates",
        "name": "Waypoint 1",
        "address": "Calle Cardenal Cienfuegos",
        "addressCountry": "ES",
        "elevation": 266,
        "latitude": 43.3551061,
        "longitude": -5.8512792,
        "postalCode": 33007,
        "media": {
          "@type": "ItemList",
          "numberOfItems": 2,
          "itemListOrder": "http://schema.org/ItemListOrderDescending",
          "itemListElement": [
            {
              "@type": "VideoObject",
              "author": "John Doe",
              "contentUrl": "mexico-beach.avi",
              "datePublished": "2013-11-28"
            },
            {
              "@type": "ImageObject",
              "author": "Jane Doe",
              "contentUrl": "mexico-beach.jpg",
              "datePublished": "2008-01-25"
            }
          ]
        }
      }
    ],
    "comments": {
      "@type": "ItemList",
      "numberOfItems": 2,
      "itemListOrder": "http://schema.org/ItemListOrderDescending",
      "itemListElement": [
        {
          "@type": "UserComments",
          "commentText": "hello there!",
          "commentTime": "2020-02-17T15:58:42",
          "creator": "Ben kenobi."
        },
        {
          "@type": "UserComments",
          "commentText": "general kenobi!",
          "commentTime": "2020-02-17T16:58:42",
          "creator": "The angry cyborg"
        }
      ]
    }
  }
}

Example of a minimum route

{
    "@context": "http://schema.org",
    "@type": "Trip",
    "name": "A route 1",
    "description": "The test route with the least number of possible properties",
    "itinerary": {
        "@type": "ItemList",
        "numberOfItems": 6,
        "itemListOrder": "http://schema.org/ItemListOrderDescending",
        "itemListElement": [
            {
                "@type": "GeoCoordinates",
                "latitude": 43.3551061,
                "longitude": -5.8512792
            },
            {
                "@type": "GeoCoordinates",
                "latitude": 43.3547082,
                "longitude": -5.8507937
            },
            {
                "@type": "GeoCoordinates",
                "latitude": 43.3545444,
                "longitude": -5.8494473
            },
            {
                "@type": "GeoCoordinates",
                "latitude": 43.3546653,
                "longitude": -5.8490288
            },
            {
                "@type": "GeoCoordinates",
                "latitude": 43.354872,
                "longitude": -5.8487445
            },
            {
                "@type": "GeoCoordinates",
                "latitude": 43.3552699,
                "longitude": -5.8485675
            }
        ]
    }
}

An example of a route in RDF Triples

/* triples as < subject, predicate, object > */

<root, @type, Trip>
<root, name, A route 1>
<root, description, The test route with all the properties>
<root, itinerary, @type>
<@type, type, ItemList>
<root, itinerary, numberOfItems>
<root, itinerary, itemListOrder>
<itemListOrder, type, http://schema.org/ItemListOrderDescending>
<root, itinerary, itemListElement>
<itemListElement, param, 0>
<itemListElement, param, 1>
<itemListElement, param, 2>
<itemListElement, param, 3>
<itemListElement, param, 4>
<itemListElement, param, 5>

The minimum route from the examples in n-triples

_:genid1 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Trip> .
_:genid1 <http://schema.org/description> "The test route with the least number of possible properties"^^<http://www.w3.org/2001/XMLSchema#string> .
_:genid1 <http://schema.org/itinerary> _:genid2 .
_:genid1 <http://schema.org/name> "A route 1"^^<http://www.w3.org/2001/XMLSchema#string> .
_:genid2 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/ItemList> .
_:genid2 <http://schema.org/itemListElement> _:genid3 .
_:genid2 <http://schema.org/itemListElement> _:genid4 .
_:genid2 <http://schema.org/itemListElement> _:genid5 .
_:genid2 <http://schema.org/itemListElement> _:genid6 .
_:genid2 <http://schema.org/itemListElement> _:genid7 .
_:genid2 <http://schema.org/itemListElement> _:genid8 .
_:genid2 <http://schema.org/itemListOrder> "http://schema.org/ItemListOrderDescending"^^<http://www.w3.org/2001/XMLSchema#string> .
_:genid2 <http://schema.org/numberOfItems> "6"^^<http://www.w3.org/2001/XMLSchema#integer> .
_:genid3 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid3 <http://schema.org/latitude> "4.33551061E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid3 <http://schema.org/longitude> "-5.8512792E0"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid4 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid4 <http://schema.org/latitude> "4.33547082E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid4 <http://schema.org/longitude> "-5.8507937E0"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid5 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid5 <http://schema.org/latitude> "4.33545444E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid5 <http://schema.org/longitude> "-5.8494473E0"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid6 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid6 <http://schema.org/latitude> "4.33546653E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid6 <http://schema.org/longitude> "-5.8490288E0"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid7 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid7 <http://schema.org/latitude> "4.3354872E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid7 <http://schema.org/longitude> "-5.8487445E0"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid8 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/GeoCoordinates> .
_:genid8 <http://schema.org/latitude> "4.33552699E1"^^<http://www.w3.org/2001/XMLSchema#double> .
_:genid8 <http://schema.org/longitude> "-5.8485675E0"^^<http://www.w3.org/2001/XMLSchema#double> .
luispc1998 commented 4 years ago

For the people outside of our team (en2a), we were currently discussing how to store the media content, at this moment we consider a list. If you have any suggestion feel free to comment it :D

carlosmanri commented 4 years ago

A simpler version could be created with the use of ShEx.

A route must contain a name, optionally it can have a description. Its composed by at least one waypoint and may or not have a list of comments and media.

The GeoCoordinates must have latitude, longitude and position. They can have as optional properties a name, altitude and a physical address.

A userComment must contain the text of the comment, the time it was published and the author, being the last one a IRI to a pod profile shape.

And finally, an Image or a Video must have an IRI to te resource, another IRI to the pod profile of the author and the time it was published

PREFIX :       <http://example.org/>
PREFIX schema: <http://schema.org/>
PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>

# Node Constraint
:Route {
    # Triple constraint
    schema:name         xsd:string  ;
    schema:description      xsd:string? ;
    schema:containsGeoPoint     IRI @:GeoCoordinates+;
    schema:hasComments      IRI @:UserComment*;
    schema:hasMediaAttached         [IRI @:Image IRI @:Video]*;
}

:GeoCoordinates {
    schema:name         xsd:string? ;
    schema:address          xsd:string?       ;
    schema:elevation        xsd:integer?       ;
    schema:latitude         xsd:float   ;
    schema:longitude        xsd:float   ;
        schema:position                  xsd:integer        ;
}

:UserComment {
    schema:text         xsd:string;
    schema:publishedDate            xsd:datetime;
    schema:author           URI @:PodProfile;
}

:Image {
    schema:contentUrl       IRI;
    schema:publishedDate            xsd:datetime;
    schema:author           URI @:PodProfile;
}

:Video {
    schema:contentUrl       IRI;
    schema:publishedDate            xsd:datetime;
    schema:author           URI @:PodProfile;
}
PabloFerMar commented 4 years ago

Team en_3a considers following this proposal so we can provide interoperability to our applications.

timbl commented 4 years ago

The XML standard in this area is GPX https://en.wikipedia.org/wiki/GPS_Exchange_Format You should make sure you interoperate with that. People will be able to upload and download routes to their GPS devices (like Garmin) and tracking Apps (like Strava) with that.

I played with this many years ago. For example a quick hack to get GPX into turtle is a sed file: https://github.com/linkeddata/swap/blob/master/pim/gpx2n3.sed

This used a namespace http://hackdiary.com/ns/gps# which Matt Biddulph had been using but he never supported it with a namespace document.

One possibility is we could ask W3C to give us namespace like https://www.w3.org/ns/pim/gpx# and deem it to have all the GPX terms in it, and populate a file there it by adding all the fields in the GPX standard.

What you cannot do is just use the fields as though they are in the Schema.org namespace when they are not.

We can go and ask them to put them in as a suggestion, but they would probably make up their own names for things in their own style.

labra commented 4 years ago

@timbl, thanks for the comments.

About GPX, I agree that it would be great to support it. I added this specific issue to discuss how to support GPX in viadeSpec.

Another decision is the namespace for the properties and entities employed, I think we should define our own namespace for new properties and maybe ask for the creation of a gpx namespace at W3C. I created another issue about this topic here

Finally, I also agree about not inventing new schema.org properties. We changed the properties that we found that didn't appear in schema.org by properties in a viade namespace and also repaired the Shape Expression. We also created a simple Turtle example of a route and added a link to show how it can be validated with ShEx.

miguilucky commented 4 years ago

@UO258425 @luispc1998 Most of the mandatory information looks good to me but, is it really necessary to have as a mandatory property the description?

Angelixus commented 4 years ago

@MiguelRodriguezHuerta It may not be mandatory, what do you think @UO258425 @luispc1998 ?

Raulpemol commented 4 years ago

I think that with the name being mandatory it is enough, so the description can be optional.

kriogenia commented 4 years ago

People don't usually fill the descriptions when uploading things, making them mandatory would be like asking people to make "asdasda" alike descriptions. I also support them being optional. My team right now is working with an object route with optional descriptions.

labra commented 4 years ago

In the shape expression the schema:description appears with a question mark which means that it is an optional field. So they are already optional.