Modul:Sandlådan/SM5POR/Qutil/dok

Introduction

This Lua module is inspired by the apparent need for uniform interpretation and use of Wikidata items and properties in Wikipedia and other Wikimedia Foundation projects, as well as in independent, third-party applications.

The aim is to codify standard procedures as established by the Wikidata project, and to make them easily accessible for Wikipedia editors, Lua programmers and others using information from Wikidata for any purpose, be it to create a multilingual, online encyclopedia on any topic conceivable, or to build a highly specialized database application combining data from or about different fields of science, organizations, cultures, countries, languages, communities, individuals, or simply all possible walks of life.

Module status

The Qutil module is not (yet, July 2020) part of an official Wikimedia Foundation project, but should be considered the author's attempt to voluntarily contribute something that could possibly be useful to other Wikipedia or Wikidata editors. There may already be other modules available that implement more or less the same functionality; if so, this module may be seen as an independent effort to verify the correctness of earlier code, to compare performance, or simply as an educational tool.

The module may also include experimental implementations of procedures not yet confirmed as official Wikidata standard; where this is the case, the corresponding functions will be marked Experimental or Unofficial as appropriate in the documentation, and their future redesign, deprecation or removal should not be entirely ruled out.

Language

This module is intended to provide language-independent functionality, not restricted to any particular natural (or constructed) human language, writing system, visual layout, or target audience. For practical reasons though, the Lua code is written using English-language function and variable names, inline commentary, and diagnostic messages (used for development only); the same applies to this module documentation. For the benefit of end-users, a separate Lutil module is planned to present any message, factual statement, or other verbal information in the end-user's preferred languages.

Basic concepts

Ontology

A fundamental part of the Wikidata database is its implementation of a generic ontology relating different database items (objects by convention named using the letter 'Q' and a natural number, hence the name of this module) to each other via a limited set of property objects.

Transitive properties

Corporate transitivity

Experimental

Inheritable properties

Experimental

Technical reference

Exported variables

While implemented as variables, these are meant to be used as constants or flags in your Lua code. As they are used also internally by the Qutil module, changing them may lead to unpredictable or erratic results, and is thus not recommended.

Constants

asymmetricPropertyClass

qutil.asymmetricPropertyClass

The class of asymmetric Wikidata properties.

classRoot

qutil.classRoot

The root of the Wikidata class tree, of which every other Wikidata class is supposed to be a subclass (direct or indirect).

disambiguationClass

qutil.disambiguationClass

The class of Wikipedia pages detailing the possible alternatives for interpreting an ambiguous word of expression.

To be moved to the Wutil module when it's created.

transitiveOverProperty

qutil.transitiveOverProperty

The property deefining valid inheritance paths.

transitivePropertyClass

qutil.transitivePropertyClass

The class of transitive Wikidata properties.

Flags

A number of flags meant to be selectively ORed together into a binary integer are exported to be used with the getClaims function, and is documented with that function.

Exported functions

context

qutil.context( frame )

getClaims

qutil.getClains( entity, properties, flags )

Fetch values of listed properties for entity. Exact access methods and data returned, including different kinds of metadata, depend on flags specified.

entity

Wikidata Item (Q), Property (P) or Lexeme (L) entity id for which the property values are to be fetched; a string.

properties

A list of property ids to be processed in parallel; a table.

flags

A set of flags to control the details of the function, ORed together as an integer.

By default, with no flags set, getClaims will return a list with the same length as that of the list of properties given in the call, each cell holding the result from retrieving the main values of the corresponding property, either as explicitly assigned to the entity, or as implicitly inherited from other entities along a defined path of transitivity.

Flags

flgNoInherit

When set, retrieve only property values explicitly assigned to the entity itself, not those inherited via paths of transitivity.

flgQualifiers

When set, retrieve any qualifiers with their values accompanying the main statements.

flgRank

When set, retrieve all statements stored regardless of rank.

flgReferences

When set, retrieve any reference statements provided in support of the main statements.

Example

local result = qutil.getClaim("Q34", {"P1442"}, qutil.flgQualifiers)

getInheritedProperties

qutil.getInheritedProperties( item, props, prop0, propt, propf ) Experimental

Fetch requested property values props for item by tracing them along the inheritance path defined by prop0, propt, and propf.

item

Wikidata Item (Q) or Property (P) object id for which the properties are to be fetched; a string.

props

A list of property retrieval paths (format described below) to be processed in parallel; either a table or nil (a shorthand representation for the unconditional, additive null property path, used to trace the entire inheritance tree between item and the applicable root).

prop0

First-step parental Property object id to initiate inheritance path traversal; either a string or nil (in which case inheritance path traversal will begin with propt).

propt

Primary Property object id to use repeatedly for successive retrieval of parental object ids; a string or nil (in which case traversal will immediately make use of propf, if available, and otherwise terminate). Should be transitive to yield meaningful results.

propf

Final Property to be used once after a prop0 or propt request fails to yield a single useable parent id (taking specified constraints into account); a string or nil (in which case no further parent id request will be made).

Property retrieval path format

A table with up to three fields as follows:

1. A list of Property id strings, possibly empty (indicating a null path); a table (must not be nil).
2. A flag word indicating what type of inheritance to apply; a number.
3. A list of conditions to apply to either the Property value obtained or to the parental object found; a table (further described below).

Property retrieval condition format

(to be further defined)

Example

local result = qutil.getInheritedProperties("Q34", {{{"P1442"}}}, "P31", "P279", nil)

Future development

See also

• Wikidata:User:SM5POR

Compatible modules

• The Butil module (bibliographic context relations)
• The Cutil module (corporate context relations)
• The Dutil module (database management)
• The Futil module (file handling)
• The Gutil module (graphical processing)
• The Hutil module (historical context relations)
• The Jutil module (juvenile context relations)
• The Lutil module (language processing)
• The Mutil module (map processing)
• The Nutil module (network management)
• The Putil module (property management)
• The Rutil module (robot management)
• The Sutil module (scientific context relations)
• The Tutil module (tabular processing)
• The Vutil module (visualization processing)
• The Wutil module (Wikimedia project relations)

Application ideas

These are so far merely proposed names and content descriptions for anticipated laborative end-user application modules. For electrical sheep, paranoid androids and the technological singularity, see the Ilab module. To design a planet from core to stratosphere, or a galactic cluster populated and colonized by various intellectual property lawyer species, use the Ulab module.

• The Alab module (art laboratory environment)
• The Elab module (education laboratory environment)
• The Ilab module (intelligence laboratory environment)
• The Olab module (organization laboratory environment)
• The Ulab module (universe laboratory environment)
• The Ylab module (youth laboratory environment)

License

The software module described here, as well as this documentation, is available under CC0 (effectively public domain). To avoid confusion and duplicated work due to multiple forks or versions being distributed simultaneously, you are still both welcome and encouraged to contact the author to discuss potential coordination or cooperation.