Daniel Kinzler has uploaded a new change for review. (
https://gerrit.wikimedia.org/r/395815 )
Change subject: Document entity storage on wiki pages.
......................................................................
Document entity storage on wiki pages.
This clarifies the relationship between entity revisions and page revisions,
among other things.
Change-Id: If6d1b62a1acd39491f377c83f68eb3f7788a46cb
---
A docs/entity-storage.wiki
M lib/includes/Store/EntityRevision.php
M repo/includes/Content/EntityContent.php
M repo/includes/Store/Sql/WikiPageEntityStore.php
M repo/includes/Store/WikiPageEntityStorePermissionChecker.php
5 files changed, 55 insertions(+), 4 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Wikibase
refs/changes/15/395815/1
diff --git a/docs/entity-storage.wiki b/docs/entity-storage.wiki
new file mode 100644
index 0000000..6d26ce9
--- /dev/null
+++ b/docs/entity-storage.wiki
@@ -0,0 +1,34 @@
+This page describes how wikibase entities are represented and stored inside
MediaWiki.
+
+
+== Storage ==
+
+Entities (or more precisely, entity description documents) are stored as
MediaWiki page content, serialized according to JSON binding of the Wikibase
data model. The JSON structure encodes an EntityDocument, EntityContent and
EntityHandler provide the necessary glue to allow MediaWIki to handle
EntityDocument as page content.
+
+In order to store entities on wiki pages, a mapping between entity IDs and
page titles is required. In the simplest case, the entity ID is used as the
page title directly, with the appropriate namespace prefix. For this purpose,
and entity type is associated with a namespace. Since entity IDs encode the
entity type, this in principle allows multiple entity types to share the same
namespace. However, support for multiple entity types sharing the same
namespace directly is currently not implemented,at least not for top-level
entities (see below for details).
+
+In some cases, it may be desirable to store multiple entities on the same page
- conceptually, this may be interpreted as a top-level entity containing
several sub-entities (or "inner" entities) which are similar to the idea of
sections in MediaWiki. Just as with sections, the ID of such an inner entity
has to contain the ID of the parent (top level) entity, so it can be used as an
address for finding the inner entity in the database.
+
+This implies that the relationship between entity IDs and page titles is
unique only in one direction: each entity ID is associated with a single page,
but multiple entity IDs can map to the same page (or sections of the same page,
depending on interpretation). The same is true for the relationship between
entity types and mediaWiki namespaces.
+
+
+== Enumeration ==
+
+As a consequence of the above principles, efficient enumeration of all entity
IDs can be achieved by enumerating all titles in a namespace, but this is only
possible for top-level entities. In order to enumerate sub-entities contained
within top-level entities, it may be required to load each top-level entity.
+
+
+== Redirects ==
+
+Some entity types may support redirects. A MediaWiki redirect from one page
title to another shall be interpreted as the two entity IDs referring to the
same entity (indeed, the same entity as well as the same entity description).
The titles of redirect pages correspond to secondary IDs of the entity, while
the title of the page that actually contains the entity description corresponds
to the canonical entity ID. The entity description will typically only contain
the canonical ID.
+
+
+== Versioning ==
+
+Wikibase supports the concepts of versioning through EntityRevisions. These
roughly correspond to MediaWiki page revisions, with one notable difference:
the revision ID is considered to be unique only relative to a given entity ID,
not globally, as in MediaWiki.
+
+In particular, updating a single sub-entity will create a new revision of the
page that contains that sub-entity. This implies that it also creates a new
revision for every other entity contained on that page, including the top level
entity. These "incidental" entity revisions correspond to the concept of "null
revisions" in MediaWiki: between the new revision and its parent, only the
(sub-)entities touched by the intentional edit change; all other entities on
the page remain unchanged between the old and the new revision.
+
+
+== Permissions ==
+
+The permission to perform actions on entities are mapped to MediaWiki page
permissions by an EntityPermissionChecker. This means that the same permissions
apply to all entities on a page, and page protection (restrictions) aso apply
to all entities. However, the same operation (like changing a label) can be
mapped to different actions for different entity types (e.g. item-term and
property-term), which in effect allows permissions and restrictions to be
managed per entity type on a page (but not per individual entity).
diff --git a/lib/includes/Store/EntityRevision.php
b/lib/includes/Store/EntityRevision.php
index fdc3950..4e09311 100644
--- a/lib/includes/Store/EntityRevision.php
+++ b/lib/includes/Store/EntityRevision.php
@@ -6,7 +6,14 @@
use Wikibase\DataModel\Entity\EntityDocument;
/**
- * Represents a revision of a Wikibase entity.
+ * An EntityRevision identifies some revision of the description of an entity.
+ * A revision of an entity is uniquely identified by the tuple ( entity-id,
revision-id ).
+ *
+ * Note that the revision ID alone is not guaranteed to be unique unique, and
cannot be relied
+ * upon to identify an entity. In particular, revisions of two different
entitites may have the
+ * same revision id.
+ *
+ * For more information, see docs/entity-storage.txt
*
* @license GPL-2.0+
* @author Daniel Kinzler
@@ -57,7 +64,10 @@
}
/**
- * @see Revision::getId
+ * The ID of the revision of the given entity.
+ *
+ * Note that this number is not guaranteed to be globally unique, nor
to be increasing over
+ * time.
*
* @return int
*/
@@ -66,7 +76,7 @@
}
/**
- * @see Revision::getTimestamp
+ * The revision's timestamp. This is furely informational, it does not
identify the revision.
*
* @return string in MediaWiki format or an empty string
*/
diff --git a/repo/includes/Content/EntityContent.php
b/repo/includes/Content/EntityContent.php
index da186ac..a94904d 100644
--- a/repo/includes/Content/EntityContent.php
+++ b/repo/includes/Content/EntityContent.php
@@ -38,6 +38,9 @@
/**
* Abstract content object for articles representing Wikibase entities.
*
+ * For more information on the relationship between entities and wiki pages,
+ * see docs/entity-storage.txt
+ *
* @license GPL-2.0+
* @author Jeroen De Dauw < [email protected] >
* @author Daniel Kinzler
diff --git a/repo/includes/Store/Sql/WikiPageEntityStore.php
b/repo/includes/Store/Sql/WikiPageEntityStore.php
index 4465678..376de77 100644
--- a/repo/includes/Store/Sql/WikiPageEntityStore.php
+++ b/repo/includes/Store/Sql/WikiPageEntityStore.php
@@ -26,7 +26,8 @@
/**
* EntityStore implementation based on WikiPage.
*
- * @todo: move the actual implementation of the storage logic from
EntityContent into this class.
+ * For more information on the relationship between entities and wiki pages,
+ * see docs/entity-storage.txt
*
* @license GPL-2.0+
* @author Daniel Kinzler
diff --git a/repo/includes/Store/WikiPageEntityStorePermissionChecker.php
b/repo/includes/Store/WikiPageEntityStorePermissionChecker.php
index 710501b..151d34e 100644
--- a/repo/includes/Store/WikiPageEntityStorePermissionChecker.php
+++ b/repo/includes/Store/WikiPageEntityStorePermissionChecker.php
@@ -14,6 +14,9 @@
/**
* Checks permissions to perform actions on the entity based on MediaWiki page
permissions.
*
+ * For more information on the relationship between entities and wiki pages,
+ * see docs/entity-storage.txt
+ *
* @license GPL-2.0+
*/
class WikiPageEntityStorePermissionChecker implements EntityPermissionChecker {
--
To view, visit https://gerrit.wikimedia.org/r/395815
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: If6d1b62a1acd39491f377c83f68eb3f7788a46cb
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Wikibase
Gerrit-Branch: master
Gerrit-Owner: Daniel Kinzler <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
