summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2018-09-21 12:52:49 -0700
committerBryan Newbold <bnewbold@robocracy.org>2018-09-21 12:52:49 -0700
commitd495df1f76c44b7e09db2fb8b93615ffcdf6b818 (patch)
treed92ad9a0e3d1fae382e7cd62e1e997ec65389ba8
parent1915c7b885641a34191efeee2cc8525a6ad27b9f (diff)
downloadfatcat-d495df1f76c44b7e09db2fb8b93615ffcdf6b818.tar.gz
fatcat-d495df1f76c44b7e09db2fb8b93615ffcdf6b818.zip
clean up entity fields page
-rw-r--r--guide/src/entity_fields.md121
1 files changed, 54 insertions, 67 deletions
diff --git a/guide/src/entity_fields.md b/guide/src/entity_fields.md
index 0d0b2d6f..99ff1e73 100644
--- a/guide/src/entity_fields.md
+++ b/guide/src/entity_fields.md
@@ -71,35 +71,23 @@ guide.
## Releases
-- `title: (required)
- type: string
-- `work_id:
- type: string
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-- `container:
- $ref: "#/definitions/container_entity"
- description: "Optional; GET-only"
-- `files:
- description: "Optional; GET-only"
- type: array
- items:
- $ref: "#/definitions/file_entity"
-- `container_id:
- type: string
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-- `release_type:
- type: string
- example: "book"
-- `release_status:
- type: string
- example: "preprint"
-- `release_date:
- type: string
- format: date
-- `doi:
- type: string
- #format: custom
- example: "10.1234/abcde.789" See the "External Identifiers" section of style guide.
+- `title` (required): the title of the release.
+- `work_id` (fatcat identifier; required): the (single) work that this release
+ is grouped under. If not specified in a creation (`POST`) action, the API
+ will auto-generate a work.
+- `container_id` (fatcat identifier): a (single) container that this release is
+ part of. When expanded the `container` field contains the full `container`
+ entity.
+- `release_type` (string, controlled set): represents the medium or form-factor
+ of this release; eg, "book" versus "journal article". Not necessarily
+ consistent across all releases of a work. See definitions below.
+- `release_status` (string, controlled set): represents the publishing/review
+ lifecycle status of this particular release of the work. See definitions
+ below.
+- `release_date` (string, date format): when this release was first made
+ publicly available
+- `doi` (string): full DOI number, lower-case. Example: "10.1234/abcde.789".
+ See the "External Identifiers" section of style guide.
- `isbn13` (string): external identifer for books. ISBN-9 and other formats
should be converted to canonical ISBN-13. See the "External Identifiers"
section of style guide.
@@ -158,27 +146,27 @@ guide.
can only be linked to a specific target release (not a work), though it may
be ambugious which release of a work is being referenced if the citation is
not specific enough. Reference fields include:
- - index:
- type: integer
- format: int64
- - target_release_id:
- type: string
- #format: ident
- - extra:
- type: object
- additionalProperties: {}
- - key:
- type: string
- - year:
- type: integer
- format: int64
- - container_title:
- type: string
- - title:
- type: string
- - locator:
- type: string
- example: "p123"
+ - `index` (integer, optional): reference lists and bibliographies almost
+ always have an implicit order. Zero-indexed. Note that this is distinct
+ from the `key` field.
+ - `target_release_id` (fatcat identifier): if known, and the release
+ exists, a cross-reference to the fatcat entity
+ - `extra` (JSON, optional): additional citation format metadata can be
+ stored here, particularly if the citation schema does not align. Common
+ fields might be "volume", "authors", "issue", "publisher", "url", and
+ external identifers ("doi", "isbn13").
+ - `key` (string): works often reference works with a short slug or index
+ number, which can be captured here. For example, "[BROWN2017]". Keys
+ generally supercede the `index` field, though both can/should be
+ supplied.
+ - `year` (integer): year of publication of the cited release.
+ - `container_title` (string): if applicable, the name of the container of
+ the release being cited, as written in the citation (usually an
+ abbreviation).
+ - `title` (string): the title of the work/release being cited, as written.
+ - `locator` (string): a more specific reference into the work/release being
+ cited, for example the page number(s). For web reference, store the URL
+ in "extra", not here.
Controlled vocabulary for `release_type` is derived from the Crossref `type`
vocabulary:
@@ -282,22 +270,21 @@ Current "extra" fields, flags, and content:
[arxiv.org]: https://arxiv.org
-abstracts:
- type: array
- items:
- type: object
- properties:
- sha1:
- type: string
- example: "3f242a192acc258bdfdb151943419437f440c313"
- content:
- type: string
- example: "<jats:p>Some abstract thing goes here</jats:p>"
- mimetype:
- type: string
- example: "application/xml+jats"
- lang:
- type: string
- example: "en"
+### Abstracts
+
+Abstract *contents* (in raw string form) are stored in their own table, and are
+immutable (not editable), but there is release-specific metadata as part of
+`release` entities.
+
+- `sha1` (string, hex, required): reference to the abstract content (string).
+ Example: "3f242a192acc258bdfdb151943419437f440c313"
+- `content` (string): The abstract raw content itself. Example: `<jats:p>Some
+ abstract thing goes here</jats:p>`
+- `mimetype` (string): not formally required, but should effectively always get
+ set. `text/plain` if the abstract doesn't have a structured format
+- `lang` (string, controlled set): the human language this abstract is in. See
+ the `lang` field of release for format and vocabulary.
+
## Works
+Works have no field! They just group releases.