diff options
| -rw-r--r-- | guide/src/data_model.md | 12 | ||||
| -rw-r--r-- | guide/src/entity_fields.md | 28 | ||||
| -rw-r--r-- | guide/src/entity_release.md | 4 |
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 |