== Abstract ==

Entities as defined by Wikibase have a unique identifier and a type. As Wikibase is an extension of
MediaWiki, every entity object is stored on its own page in a given namespace that can hold entities
of one type.

The EntityDocument interface describes this construct and adds some methods around it that allow
getting the type, getting and setting the id, creating a copy and checking if an entity has content
and whether two entities are equal. It is important that the identifier does not count as content
and neither affects emptiness nor equality.

All entities must implement this interface. The two entity types 'item' and 'property' are defined
in Wikibase by default. They can be enabled by defining their namespace.

The actual content of an entity can be anything. However, Wikibase defines some basic structures
including labels, descriptions, aliases and statements. If an entity holds one of these structures,
it has to implement the corresponding provider interface (eg. LabelsProvider).

== Entity type definitions ==

To support an entity type, additionally to defining the entity itself, the following services need
to be implemented and registered:

* Serializers and Deserializers must be defined to convert the entity into native data structures
  that can be (de-)serialized as json. These classes have to implement the DispatchableSerializer
  respectively the DispatchableDeserializer interfaces from the serialization compoment.
* Each entity needs a view to provide an HTML representation to the user. Each view has to extend
  the abstract EntityView class from the WikibaseView component.
* MediaWiki bindings are needed by defining a content class extending EntityContent and a handler
  class extending EntityHandler. Furthermore, the handler has to be globally registered in
  $wgWBRepoEntityTypes. It is used to create instances of the content class.

Entity types are defined in the global $wgWBRepoEntityTypes and $wgWBClientEntityTypes arrays,
respectively. These arrays are constructed at bootstrap time in Wikibase.php and
WikibaseClient.php based on the information returned when including the WikibaseLib.entitytypes.php
file.

These globals are associative arrays mapping entity type identifiers to a set of callbacks that
act as factory methods. The structure of this set is defined as follows, where each string key is
associated with a function having the dedicated signature:

; serializer-factory-callback (repo and client)
: a callable that returns a DispatchableSerializer instance, with the first and only argument being
  a SerialierFactory
; deserializer-factory-callback (repo and client)
: a callable that returns a DispatchableDeserializer instance, with the first and only argument
  being a DeserializerFactory
; entity-id-builder-pair (repo and client)
: an array with two elements: First a regular expression that matches serialized entity ids,
  second a callable that returns an EntityId instance for a given entity id serialization
; view-factory-callback (repo only)
: a callable that returns an EntityView instance, with the arguments being a language code, a
  LabelDescriptionLookup, a LanguageFallbackChain and an EditSectionGenerator
; content-model-id (repo only)
: a string representing the id of the content model
; content-handler-factory-callback (repo only)
: a callable that returns an EntityHandler instance supporting this entity type
; entity-factory-callback (repo only)
: a callback for creating an empty entity of this type
; js-deserializer-factory-function (repo only)
: a string representing a resource loader module that, when `require`d, returns a function returning
  a `wikibase.serialization.Deserializer` instance supporting this entity type

Extensions that wish to register an entity type should use the WikibaseRepoEntityTypes respectively
WikibaseClientEntityTypes hooks to provide additional entity type definitions.

== Programmatic Access ==

Information about entity types can be accessed programmatically using the appropriate service
objects. The entity type definitions themselves are wrapped by the EntityTypeDefinitions class.