I have a massive Relax scheme and I want to generate a documentation for it. But the problem is that the documentation has no description of each tag attribute or choice. Is there a possibility to add some description to each entity in plain English, so that all those descriptions appear on generated documentation pages in a nice way?
Related
Let's say I have an API to get a product given an product ID as: api/products/<productid>.
What would be a REST way to get relevant products given a product ID. I think I can use a query on the same endpoint as api/products?id=<productid>, but not sure if this is ideal or it might be confusing.
Standard practice for making api url is api/products/<productid>.
for params other than id (generally for filtering or searching purpose), query params are considered api/products?name=somename
The detailed resource naming guide can be found here
What would be REST way to get relevant resources?
Answer this question: how would you do it on the web?
You might have a web page for the product, and then a link from that page to a new page describing the related resources, where each entry in that page would include links to the product page of the specific resources.
What we need to define for the client (or make it easy to discover) is how to find the links.
In the case of the web, we are typically using HTML representation of our pages. HTML is special in that it has a standardized understanding of links. For human consumers, we surround the link with context (typically, the contents of the A element); for machines, we should be a bit more precise about defining the rule.
For representations that don't have a standardized understanding of links, we need to do something else. The most common answer is to use Web Linking, which is to say we put a description of the relationship between to URI into the headers of the response.
REST doesn't care what spelling conventions you use for your resource identifiers, so long as they are consistent with the production rules defined in RFC 3896. So you can choose any spelling convention you like.
For instance, it is common to use spelling conventions that include key value pairs in the query part of the URI, because HTML GET forms can be used to describe links with that shape, which simplifies certain use cases.
Since REST doesn't care about your spelling conventions, you can use the extra freedom to address other problems (what spellings are easy for people reading the logs? what spellings are easy for people documenting the API? and so on....)
According to google's Structured Data Testing Tool, there are no errors in my review schema code, but the stars still are not displaying in the preview. Does anyone have any idea why? I thought maybe it was a nesting issue, but I tried to organize the data in all kinds of arrangements and to no avail. Any thoughts would be very appreciated!
Thanks in advance!
Here's the page I'm referring to:
http://www.junkluggers.com/locations/westchester-ny/white-plains-ny-junk-removal-and-furniture-pickup/
(The review I'm working on is the one at the bottom of the page, not the testimonial on the right sidebar.)
According to Google:
" If you've added structured data for rich snippets, but they are not appearing in search results, the problem can be caused by two types of issues:
Technical issues with the structured data markup or with the Google’s ability to crawl, index, and utilize the structured data.
Quality issues, that is, structured data that is technically correct, but does not adhere to Google’s quality guidelines."
Full answer here: https://support.google.com/webmasters/answer/1093493?hl=en
Along with RustyFluff's comment, I do notice a few technical errors in your markup, Catherine. In a nutshell, you haven't defined who or what is being reviewed, and you should be using the reviewBody property instead of description. You also should remove the city from within the author's name markup. And something else that I should point out is that you should remove the authorship markup from the page, as it's not appropriate for an authorship tag according to Google's guidelines. Also, the publisher tag only needs to go on your homepage, and it should link to your Google+ business page, not to a personal profile.
Keep in mind, though, that even if your markup is technically perfect, there are no guarantees that Google will display your rich snippets. They determine that based on, among other things, various quality signals.
I wonder if it is possible to configure MediaWiki (or other wiki tools) as a modular predefined wiki. For instance, on a regular wiki page one can freely edit sections, text, everything.
I am looking for a solution that predefines a number of sections (or modules) that can be added to each wiki page. Then users are free to edit inside those sections within their predefined formats.
Hope someone can help, thanks.
As for MediaWiki, there is at least one extension that can work that way: Semantic Forms, usually used together with Semantic MediaWiki (though that is not necessary). With SF, you will define one or more templates that receives the data entered in the form, and the form can be divided into sections.
A more lighweight solution might be using one of the many boiler plate extensions available.
Either way, with a wiki you can never force your users to follow a certain scheme. The whole philosophy, making wiki's unique among collaborative tools, is that the users, not you, create not only the content but also the structure for the content!
The former Semantic Forms is now called Page_Forms and it is not dependent on SMW https://www.mediawiki.org/wiki/Extension:Page_Forms and can also make use of the Cargo extension https://www.mediawiki.org/wiki/Extension:Cargo
I would disagree that wiki users cannot or should not be forced to follow a scheme for some types of information, though the default is that they do control the categories and namespaces and can create those at will as the data evolves. All this means though is that you manage such issues socially rather than with complex permissions structures, i.e. someone undoes your change and says "do it this way instead". So it's a different kind of forcing, but, still, someone has to make sure categories don't proliferate with bad names, capitalization, etc.
The typical use of forms data is when it must be used to satisfy some legal or professional requirement (say logging for what reason a change was made for Sarbanes-Oxley, or logging what precedents were consulted for logging legal time), or will be providing input strictly to some application (like maps). It would not be a good idea to rigorize literally every page of a wiki this way.
My question is the following: when marking up an organization, business or brand with microdata and schema.org, should I use as a global identifier it's official webpage URL? Is there any kind of better reference that I could use (like IMDB for movies or actors)?
I'd like to know if there's any standard, convention or common practice recommended.
It would be better to use some kind of controlled vocabulary (e.g. VIAF) that uniqely identifies the organization in question.
The choice of identifiers is part of the explanation of REST. http://www.infoq.com/articles/rest-introduction
Inspect closely the first principle (for convention), though it is in broader terms of resources rather than specific to org/biz/brand. REST is the thesis that started this trend. Microformats accordingly makes use of rel="profile" link tags. The concept is further expanded at http://purl.org/ so, if IMDB, for example, switches to W3 like W3C did, then in the future this will minimize the impact on the application you're making right now. RDFa Dublin Core vocab's use of this is seen in the profile at http://www.w3.org/2011/rdfa-context/rdfa-1.1.html.
(For references) Applications serving general public or open initiatives such as academic support might be better served by these profiles, however when operating a site for commercial purposes, building application-specific "custom" profiles considering various legal matters identified, that should perform reliably with PURLs, might be advantageous to build credible reputation.
Finally, WHATWG considers prefixes too advanced and HTML5 for newbies only, so the support for W3's XHTML xmlns/RDFa prefix is dropped in microdata. This compels us to reuse long-form URLs for schema.org business/org/brand resources with microdata syntax. The "custom" profile then serves as mere good-will when picking up from where tasks are wrapped up, otherwise a more variety of items might appear in the content than actually intended, owing to mix-ups.
The good news is, Google supports schema.org usage as a vocab in RDFa syntax. So considering RDFa as an already "living" standard that originated in W3 spec, as per the (non-)commercial nature of application, defining PURL for scope namespaces, profiles exhibiting prefixes, and syntax (of official web-page or substitute IRIs) as per target processors is the way to go. Currently no vocab besides schema is processed as microdata, and schema in RDFa isn't supported by anybody but Google!
How do we know which vocabulary/namespace to use to describe data with RDFa?
I have seen a lot of examples that use xmlns:dcterms="http://purl.org/dc/terms/" or xmlns:sioc="http://rdfs.org/sioc/ns#" then there is this video that uses FOAF vocabulary.
This is all pretty confusing and I am not sure what these vocabularies mean or what is best to use for the data I am describing. Is there some trick I am missing?
There are many vocabularies. And you could create your own, too, of course (but you probably shouldn’t before you checked possible alternatives).
You’d have to look for vocabularies for your specific needs, for example
by browsing and searching on http://lov.okfn.org/dataset/lov/ (they collect and index open vocabularies),
on W3C’s RDFa Core Initial Context (it lists vocabularies that have pre-defined prefixes for use with RDFa), or
by browsing through http://prefix.cc/ (it’s a lookup for typically used namespaces, but you might get an overview by that).
After some time you get to know the big/broad ones: Schema.org, Dublin Core, FOAF, RSS, SKOS, SIOC, vCard, DOAP, Open Graph, Ontology for Media Resources, GoodRelations, DBpedia Ontology, ….
The simplest thing is to check if schema.org covers your needs. Schema.org is backed by Google and the other major search engines and generally pretty awesome.
If it doesn't suit your needs, then enter a few of the terms you need into a vocabulary search engine. My recommendation is LOV.
Another option is to just ask the community about the best vocabularies for the specific domain you need to represent. A good place is answers.semanticweb.com, which is like StackOverflow but with more RDF experts hanging out.
Things have changed quite a bit since that video was posted. First, like Richard said, you should check if schema.org fits your needs. Personally when I need to describe something that's not covered on schema.org, I check LOV as well. If, and only if I can't find anything in LOV, I will then consider creating a new type or property. A quick way to do this is to use http://open.vocab.org/
A newer version of RDFa was published since that video was released: RDFa 1.1 and RDFa Lite. If you want to use schema.org only, I'd recommend to check http://www.w3.org/TR/rdfa-lite/
Vocabularies are usually domain specific. The xmlns line is deprecated. The RDFa profile at http://www.w3.org/profile/rdfa-1.1 lists the vocabularies available as part of initial context. Sometimes vocabularies may overlap in the context of your data. Analogous to solving math prb by either Algebraic or Geometric or other technique, mixing up vocabularies is fine. Equal terms can be found using http://sameas.org/ For addressing your consumer base's favoritism amongst vocab recognition, skos:closeMatch and skos:exactMatch may be used, eg. "gr:Brand skos:closeMatch owl:Thing" with any terms you please. Prefix attribute can be used with vocabularies besides those covered by initial context like: prefix="fb: http://ogp.me/ns/fb# vocab2: path2 ..." For cross-cutting concern across different domain vocabularies such as customizing presentation in search results microdata using schema.org guidelines should be beneficial. However, as this has nothing to do with specialization in any peculiar domain, prefixes are unavailable in this syntax. RDFa vocab have been helpful in such specific domain contexts that content seems to appeal further to participative audience while microdata targets those who've lost their way. For tasks that are too simple to merit full-fledged vocab, but have semantic implications, try http://microformats.org/ Interchanging usage of REST profile URIs for vocabs amongst the 3 syntaxes is valid, but useless owing to lack of affordable manpower to implement alternative support for the vocabs on the Web scale. How & why schema.org vocab merited separate microdata syntax of its own is discussed by Google employee Ian Hickson a. k. a. Hixie- the editor of WHATWG HTML5 draft at http://logbot.glob.com.au/?c=freenode%23whatwg&s=28+Nov+2012&e=28+Nov+2012#c747855 or http://krijnhoetmer.nl/irc-logs/whatwg/20121128#l-1122 If only Google had smart enough employees to implement parser for 1 syntax whose WG included its own employee also, then RDFa Lite inside RDFa would have been another course like Core Java within Java, & no need of separate microdata named mocking rip-off, but alas- our's is an imperfect world!