Jump to: navigation, search
Datatype to define on how values become type hinted
Table of Contents

Users can pick many datatypes for their data. Yet they do not specify the type for each value they write, but assign one global type to a property. This is slightly different from SMW's internal architecture, where dataypes influence a value's identity, whereas all properties are represented by values of a single type (class SMWPropertyValue). This is not a problem, it simply says that the type information that users provide for each property is interpreted as "management information" that SMW uses to interpret user inputs. The data model is still as described above, with types being part of the values (which is where they are mainly needed). Again: the typing approach in the user interface does not affect the data model but helps SMW to make sense of user input. One could equivalently dispense with the property-related types and require users to write the type for each input value instead. This would simply be cumbersome and would prevent some implementation optimizations that are now possible since we can assume that properties have values of only one type that we know.

Users refer to types by using natural language labels such as datatype Date. These labels are subject to internationalization. There can also be aliases for some types to allow multiple spellings in one language. To make SMW code independent from the selected language, SMW uses internal type IDs for referring to datatypes. These are short strings that typically start with "_" to avoid confusion with page titles. For example, '_dat' is the type ID for Type:Date. Developers should always use the internal type IDs. The correspondence of user labels and internal IDs is defined in language files, e.g. in the file SMW_LanguageEn.php.

How do type IDs relate to the subclasses of SMWDataValue that implement type-specific behavior? The answer is that one such class may take care of one or more type IDs. For example, the handling of URLs and Email addresses has many things in common, so there is just one class SMWURIValue that handles both. The datavalue object is told its type ID on creation, so it can adjust its behavior to suit more than one type.

The association of internal type IDs with the classes that should be used to represent their objects is done in the file SMW_DataValueFactory.php. The static class SMWDataValueFactory also introduces some hooks that can be used to extend and change these associations. So developers can add new types and even register their own implementations for existing types without patching SMW code. The factory class should therefore be used to create most data value objects in SMW, since otherwise the associations (that someone might have overwritten) would not be honored.

Note: Some datavalue classes provide special methods, e.g. for getting the year component of a date, and parts of SMW (extension) code that use such methods must first check if they are dealing with the right class (you cannot rely on the type ID to determine the class). This also means that developers who overwrite SMW implementations may want to subclass the existing classes to ensure that checks like ( $datavalue instanceof SMWTimeValue ) succeed (if not, a modified time class might not work with some time-specific features).
Note: Own datatypes should always use type IDs that start with "___" (three underscores) to avoid (future) name clashes with SMW types.

There are some exceptions where the use of the datavalue factory is not needed/recommended. In particular, properties are always represented by the SMWPropertyValue class and it does not make sense to do additional type ID lookups for each of the cases when a property is needed. But even there you would not use the normal class constructor and rather pick a static creator method that takes care of the full initialization that the datavalue factory may otherwise do. See the documentation of SMWPropertyValue for details.

Finally, there are some datatypes that are internal to SMW. They use IDs starting with two underscores, and are not assigned to any user label. So they cannot be named in a wiki and are only available to developers. The purpose of these types is usually to achieve a special handling when storing data. For example, values of Property:Subproperty of could be represented by datatype Page but subproperty_of uses a special internal type that ensures that the data can be stored separately and in a form that simplifies its use in query answering. A datatype that is added by an extension becomes internal if it is not given any user label. In this case, users cannot create properties with this type, but everything else works normally (in particular, SMW will not know anything special about internal extension types and will just treat them like any other extension type).

Register new datatype

\Hooks::register( 'SMW::DataType::initTypes', function ( $dataTypeRegistry ) {


	// Since 2.4

	return true;
class FooValue extends DataValue {

	 * @see DataValue::parseUserValue
	 * @note called by DataValue::setUserValue
	 * @param string $value
	protected function parseUserValue( $userValue ) {
		if ( $this->getOptionValueFor( 'settingRelevantForTheFactoryProcess' ) === 42 ) {

$fooValue = DataValueFactory::getInstance()->newTypeIdValue(



See also