Publishing Vocabulary Datasets as HTML/RDFa
There are many different ways to provide machine readable representations of xAPI vocabulary data by using RDF and content negotiation. One way to provide both human and machine readability from a single data source is by using HTML/RDFa. RDFa enables RDF data to be embedded in HTML documents, which makes it very useful for providing RDF in contexts where web publishing is limited to or focused on publishing datasets as HTML. HTML is a commonly understood format and even familiar to those people who are only moderately technical. Many search engine and social web companies are already serious about indexing RDFa content as well. In other words, RDFa is useful for not only exposing semantic data among xAPI vocabulary servers and registries, but also web search engines that can discover RDFa.
In the specific use case of xAPI, vocabulary authors should at least support generating HTML documents for human readability. Simply adding RDF inside of HTML attributes is the easiest path for empowering vocabulary authors to publish their vocabulary datasets in both a human and machine readable manner. It is expected that the xAPI Vocabulary Server, or other registry interfaces, will make this process more automated in the future through web-based forms and publishing tools.
Currently, if a new vocabulary is to be published, the developer or CoP should first generate the minimal metadata for each term using the recommended classes and properties defined in this specification. The vocabulary metadata for each vocabulary term and vocabulary (dataset) should be at least represented as both HTML and RDF by using RDFa. A basic example of this is provided in Appendix A. For more specific guidelines on manually generating the RDFa, read the steps below:
Basic Steps
The following steps are universally applicative regardless of whether the vocabulary is being hosted on a privately-owned web server or a public xAPI community resource (e.g., vocabulary server or registry).
- Generate the list of the vocabulary terms, definitions, and other relevant metadata in a spreadsheet or some type of word processing document for collaboration and documentation purposes.
- Determine the identifier scheme for the vocabulary and each vocabulary term by adopting stable IRI design approaches as presented in the Recommended IRI Design Practices section of this document.
- Once the CoP or vocabulary authoring participants have agreed upon and refined the vocabulary definitions and metadata, these can be transferred into an HTML file. Appendix A provides an example of some HTML that contains embedded RDFa. Vocabularies published as HTML/RDFa can also be visually customized using Bootstrap Themes and other presentation options or layouts as desired. For example, such a layout has been applied to the ADL Vocabulary to improve user navigation and readability,
https://w3id.org/xapi/adl. - Validate the HTML and RDFa by using the W3C’s RDFa Validator or other tools based on the requirements provided in RDFa 1.1.
- Upload the HTML file(s) to the target web server where the vocabulary will be hosted.
- Follow the steps for Maintaining the IRI provided in this document, and add a rewrite rule that redirects to the IRI to the target server URL where the HTML is hosted. See Appendix B for an example of rewrite rules provided in an .htaccess file for an Apache web server.