Serialization (JSON)

Table of Contents

This documentation is work in progress. Little of it has been updated since it was first written (2013) and some sections were not finished yet.

Specification

This guide applies for result printers compatible with Semantic MediaWiki 1.9.0Released on 3 January 2014 and compatible with MW 1.19.0 - 1.22.x. and later.

Printrequests

The printrequests array will contain:

• label -> string for labeling results, contains no markup
• typeid -> id of the datatype of the printed objects, if applicable
• mode -> type of print request
• format -> output format string for formatting results, if applicable

Results

The results array will contain:

• subject (like File:Foo.jpg)
• printouts specifed by
  • printrequests label (queried property)
  • printrequests value
• fulltext -> subject fulltext name
• fullurl -> subject url
• namespace -> subject namespace number
• exists -> boolean if the subject exists (red vs. blue link)

Meta

• hash -> md5 hash key of the result array (mostly used for comparison on the client side via JS etc.)
• count -> count of the results arrays
• offset -> set by the query (count + offset result in total of available results)

Meta array is only relevant for the SMW API, the result format "JSON"Outputs results in JSON-based serialisations. will only export the count number of the related query.

Example

{
"printrequests": [
    {
        "label": "",
        "typeid": "_wpg",
        "mode": 2,
        "format": "",
    },
    {
        "label": "Modification date",
        "typeid": "_dat",
        "mode": 1,
        "fomat": "",
    }
],
"results": {
    "File:Foo.jpg": {
        "printouts": {
            "Modification date": [
                "1360064258"
            ]
        },
        "fulltext": "File:Foo.jpg",
        "fullurl": "http:\/\/localhost\/mw\/index.php\/File:Foo.jpg",
        "namespace": 6,
        "exists": true
    },
    "Bar": {
        "printouts": {
            "Modification date": [
                "1358906761"
            ]
        },
        "fulltext": "Bar",
        "fullurl": "http:\/\/localhost\/mw\/index.php\/Bar",
        "namespace": 0,
        "exists": true
    },

JavaScript and SMW JSON serialization

Currently available result printers that use the SMW API and result serialization are DataTables and EventCalendar. Both are part of the Extension "Semantic Result Formats" extension.

The smw.Data.factory() (normally only called during smw.Api.parse/fetch) will map result objects that were serialized by /SMW\Serializers\QueryResultSerializer (previously SMW\DISerializer) and generate type hinting objects similar to the dataitems/datavalues in PHP. TypeId is used as a reference map to assign each of its objects to a corresponding smw.dataItem/smw.dataValue object.

• '_wpg' -> smw.dataItem.wikiPage
• '_uri' -> smw.dataItem.uri
• '_dat' -> smw.dataItem.time
• smw.dataItem.property

 * Structure is similar to
 *
 * Subject (if exists is of type smw.dataItem.wikiPage otherwise a simple object)
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.wikiPage
 *         |--> ...
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.uri
 *         |--> ...
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.time
 *         |--> ...

Access serialized objects via Api

var smwApi = new smw.Api();
smwApi.parse( data ) returns typed objects

// Collect query information
var conditions = data.query.ask.conditions,
	printouts = data.query.ask.printouts,
	parameters = {
		'limit' : data.query.ask.parameters.limit,
		'offset': data.query.ask.parameters.offset
	};

// Stringify the query
var query = new smw.Query( printouts, parameters, conditions ).toString();

// Fetch data via Ajax/SMWAPI
smwApi.fetch( query )
.done( function ( result ) {
...
} )
.fail( function ( error ) {
...
} );

Parse serialized objects

This is an example and only should give a glipmse in "how easy" it is to parse SMW typed objects in JS.

function getResults( parameters, results ) {
	...
	$.each( results, function( subjectName, subject ) {
		...
		// Subject
		if ( subject instanceof smw.dataItem.wikiPage ) {
			url = parameters.link === 'none' ? null : subject.getUri();
			title = subject.getFullText();
		}

		if ( $.inArray( 'printouts', subject ) ) {
			$.each ( subject.printouts, function( property, values ) {

				$.map ( values, function( value ) {
					var D = {};

					// Time type properties
					if ( value instanceof smw.dataItem.time ) {
						D.date = value.getDate().toISOString();
					// Page type properties
					} else if ( value instanceof smw.dataItem.wikiPage ) {
						D.title = value.getFullText();
					}
					...
				} )
			} )
		} );
	} );

	return { ... };
}

See also

• Result format "JSON"Outputs results in JSON-based serialisations.
• Writing result printers
• Writing javascript result printers
• Serializers documentation (Github)
• SemanticMediaWiki/tree/master/res/smw/api (Github)