updates to guide based on feedback

3 files changed, 35 insertions, 9 deletions

diff --git a/guide/src/data_model.md b/guide/src/data_model.md
index a72b885d..8ee3eaa1 100644
--- a/guide/src/data_model.md
+++ b/guide/src/data_model.md
@@ -54,12 +54,12 @@ the same regardless of type.
 
 A specific version of any entity in the catalog is called a "revision".
 Revisions are generally immutable (do not change and are not editable), and are
-not normally referred to directly. Instead, persistent "fatcat identifiers" can
-be created, which "point to" a single revision at a time. This distinction
-means that entities referred to by an identifier can change over time (as
-metadata is corrected and expanded). Revision objects do not "point" back to
-specific identifiers, so they are not the same as a simple "version number" for
-an identifier.
+not normally referred to directly. Instead, persistent "fatcat identifiers"
+(`ident`) can be created, which "point to" a single revision at a time. This
+distinction means that entities referred to by an identifier can change over
+time (as metadata is corrected and expanded). Revision objects do not "point"
+back to specific identifiers, so they are not the same as a simple "version
+number" for an identifier.
 
 Identifiers also have the ability to be merged (by redirecting one identifier
 to another) and "deleted" (by pointing the identifier to no revision at all).
diff --git a/guide/src/entity_fields.md b/guide/src/entity_fields.md
index dfded89a..86821f73 100644
--- a/guide/src/entity_fields.md
+++ b/guide/src/entity_fields.md
@@ -2,7 +2,7 @@
 
 All entities have:
 
-- `extra`: free-form JSON metadata
+- `extra` (dict, optional): free-form JSON metadata
 
 The "extra" field is an "escape hatch" to include extra fields not in the
 regular schema. It is intended to enable gradual evolution of the schema, as
@@ -10,3 +10,29 @@ well as accommodating niche or field-specific content. Reasonable care should
 be taken with this extra metadata: don't include large text or binary fields,
 hundreds of fields, duplicate metadata, etc.
 
+All full entities (distinct from revisions) also have the following fields:
+
+- `state` (string, read-only): summarizes the status of the entity in the
+  catalog. One of a small number of fixed values, see vocabulary below.
+- `ident` (string, Fatcat identifier, read-only): the Fatcat entity identifier
+- `revision` (string, UUID): the current revision record that this entity
+  `ident` points to
+- `redirect` (string, Fatcat identifier, optional): if set, this entity ident
+  has been redirected to the `redirect` one. This is a mechanism of merging or
+  "deduplicating" entities.
+- `edit_extra` (dict, optional): not part of the bibliographic schema, but can
+  be included when creating or updating entities using the API, and the
+  contents of field will be included in the entity's edit history.
+
+
+## `state` Vocabulary
+
+- `active`: entity exists in the catalog
+- `redirect`: the entity `ident` exists in the catalog, but is a redirect to
+  another entity ident.
+- `deleted`: an entity with the `ident` did exist in the catalog previously,
+  but it was deleted. The `ident` is retained as a "tombstone" record (aka,
+  there is a record that an entity *did* exist previously).
+- `wip` ("Work in Progress"): an entity identifier has been created as part of
+  an editgroup, but that editgroup has not been accepted yet into the catalog,
+  and there is no previous/current version of the entity.
diff --git a/guide/src/entity_release.md b/guide/src/entity_release.md
index ea67c5b5..3815a544 100644
--- a/guide/src/entity_release.md
+++ b/guide/src/entity_release.md
@@ -148,8 +148,8 @@ complete or correct in more obscure cases.
   work. For releases, must always include the `vN` suffix (eg, `v3`).
 - `jstor` (string): external identifier for works in JSTOR.
 - `ark` (string): ARK identifier
-- `mag` (deprecated; string): Microsoft Academic Graph identifier. Never used,
-  may be deleted in the future
+- `mag` (DEPRECATED; string): Microsoft Academic Graph (MAG) identifier. As of
+  December 2021, no entities in the catalog have a value for this field.
 - `doaj` (string): [DOAJ](https://doaj.org) article-level identifier
 - `dblp` (string): [dblp](https://dblp.org) article-level identifier
 - `oai` (string): OAI-PMH record id. Only use if no other identifier is available