REST/HATEOAS Microformat/FOAF/Schema Domain Specific Confusion

Question

In a RESTful service, you can define links to resources as so:

<next xmlns="http://example.org/state-machine"
  rel="http://mydomain.example.org/user"
  url="http://mydomain.example.com/user/1234"
  type="application/xml"/>

Or a JSON-LD Example:

{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": {
      "@id": "http://xmlns.com/foaf/0.1/homepage",
      "@type": "@id"
    }
  },
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

Or a vCard example:

<address id="hcard" class="vcard">
<p class="fn n">
<span class="given-name">First</span>
<span class="additional-name">M</span>.
<span class="family-name">Last</span>

With the rel attribute pointing to a schema/microformat/microdata/RDFa description of that free-offer object within the domain. Say I have a user object with fields name and homepage,

1. In the examples above, would rel="http://mydomain.example.org/user" be more appropriate since it is domain specific user or should I use something like this from foaf?

   "name": "http://xmlns.com/foaf/0.1/name",@id": http://xmlns.com/foaf/0.1/homepage"
   

2. I am very confused with these RDFa, microformat, microdata, schema, vcards, hcards, foaf, http://www.productontology.org/id/, www.schema.org/name, http://rdf.data-vocabulary.org/#name, json schema, etc. When do I create my own microformat/schema, and when do I use the public ones defined in those different areas (vCards, hcards, foaf, productontology, schema.org)? I understand that RDFa, microformats, etc., are really public metadata about data, but where can I find a full list of them to use?

3. If I were to create my own rel like rel="http://mydomain.example.org/user", defining the user object, how should I document it? Is there a standard I can follow? Some places suggest human readable discovery documents, or maybe a JSON/XML schema at that location describing the contract and the version?

4. One suggestion is to have a different version of http://mydomain.example.com/v1/user/1234 to talk to with a different version of specification for the service so existing client won't break on version change.

Please help me map out this confusion, or the terms I should use, with regards to Microformat, RDF, Microdata, Schema, etc.

Answer 1

When just started learning RDF/Ontology, I’ve the same confusion. There are a lot of vocabs from many different organizations. The key is to use the ones that are well established and adopted by others; but also more importantly, make sure that to use the ‘terms’ which represent the ‘semantic meanings’ that you intend to mean.
To answer your specifics questions: 1) You ‘can’ create your own terms but the point is that when other applications parse your terms, the application will need to know what your terms really means. If you use FOAF:homepage, all applications know its semantic meaning and what it refers to and also from that, it implies that whoever is the subject (subject in the rdf tripple) of FOAF:homepage is a FOAF:Person. There is where open linked data comes in. http://linkeddata.org/

2) Myself does not have a lot of experience with RDFa/Microfromat, my understanding is that these technologies want to provide machine understandable semantic terms at the HTML layer. I think you may not want to create your own if there are existing ones but you can have your own terms defined in addition to what is out there.

3) You can define terms using OWL or RDFS Just saw this, it may be useful.. https://code.google.com/p/tdwg-rdf/wiki/Beginners7OWL

But in my light way project, we just create terms by specifying the namespace, name of the term and what it mean.. You can follow the following to define your terms: http://dublincore.org/documents/dcmi-terms/

JSON/XML/N3… are just different serialization formats and the same term can be serialized using many different formats. The important thing to remember is that you define the semantic meaning of the terms and they will be serialized to different formats. It is not that the format is not important but all formats point to the same term and same meaning.

4) Myself version my vocabs.. But I don’t have much insights into the best practices.

Hope this help!!

Answer 2

There is a well known expression of this in RDFa:

<html><body vocab="http://purl.org/dc/terms/">
<div typeof="foaf:Person">
<span property="creator">manu sporny</span>
<span property="foaf:age" content="66"/>
<span property="foaf:homepage" resource="http://x.com"/>
</div>
</body></html>

The "foaf" prefix is defaulted by RDFa. No context to define. The "dc" prefix is made the default, no prefix required for "creator".

This is the standard, forget everything else.

The list of directly usable prefixes is provided by http://www.w3.org/2011/rdfa-context/rdfa-1.1 You may find here a lot of usable concepts, in fact all the public schemas.

Note the "schema" prefix, for a vocabulary defined here: http://schema.org/ It is specially rich, and widely used. Note also that it tried to define a microformat to compete with RDFa notation. Drop that and use the vocabulary with RDFa.