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 < jeroended...@gmail.com > * @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 <daniel.kinz...@wikimedia.de> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits