summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2021-12-08 10:58:23 -0800
committerBryan Newbold <bnewbold@robocracy.org>2021-12-08 10:58:23 -0800
commit07b9dfe28b4732f0ca52dc4fd571ea238d953279 (patch)
tree39c31a865c7d95297ed9062ef126106a0b80ec57
parent2ee2a91df7a82d46e72657cb45f4524389e5d972 (diff)
downloadfatcat-07b9dfe28b4732f0ca52dc4fd571ea238d953279.tar.gz
fatcat-07b9dfe28b4732f0ca52dc4fd571ea238d953279.zip
updates to guide based on feedback
-rw-r--r--guide/src/data_model.md12
-rw-r--r--guide/src/entity_fields.md28
-rw-r--r--guide/src/entity_release.md4
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