From 9a333ff02d6b0eb26adb963934557529353de9a4 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 13 Oct 2021 12:44:10 -0700 Subject: guide updates for v0.4 schema changes --- guide/src/entity_container.md | 20 +++++++++++++++++--- guide/src/entity_fileset.md | 23 +++++++++++++++++++++-- guide/src/entity_release.md | 26 +++++++++++++++++++------- 3 files changed, 57 insertions(+), 12 deletions(-) (limited to 'guide') diff --git a/guide/src/entity_container.md b/guide/src/entity_container.md index ebfcc9dc..94201d90 100644 --- a/guide/src/entity_container.md +++ b/guide/src/entity_container.md @@ -10,16 +10,20 @@ below) - `container_type` (string): eg, journal vs. conference vs. book series. Controlled vocabulary is described below. +- `publication_status` (string): whether actively publishing, never published + anything, or discontinued. Controlled vocabularity is described below. - `publisher` (string): The name of the publishing organization. Eg, "Society of Curious Students". - `issnl` (string): an external identifier, with registration controlled by the [ISSN organization](http://www.issn.org/). Registration is relatively inexpensive and easy to obtain (depending on world region), so almost all serial publications have one. The ISSN-L ("linking ISSN") is one of either - the print ("ISSNp") or electronic ("ISSNe") identifiers for a serial + the print (`issp`) or electronic (`issne`) identifiers for a serial publication; not all publications have both types of ISSN, but many do, which can cause confusion. The ISSN master list is not gratis/public, but the ISSN-L mapping is. +- `issne` (string): Electronic ISSN ("ISSN-E") +- `issnp` (string): Print ISSN ("ISSN-P") - `wikidata_qid` (string): external linking identifier to a Wikidata entity. #### `extra` Fields @@ -31,8 +35,6 @@ sometimes a very terse, single-word truncated form of the name (eg, a pun). - `coden` (string): an external identifier, the [CODEN code][]. 6 characters, all upper-case. -- `issnp` (string): Print ISSN -- `issne` (string): Electronic ISSN - `default_license` (string, slug): short name (eg, "CC-BY-SA") for the default/recommended license for works published in this container - `original_name` (string): native name (if `name` is translated) @@ -50,6 +52,8 @@ - `region` (string, slug): continent/world-region (vocabulary is TODO) - `discipline` (string, slug): highest-level subject aread (vocabulary is TODO) - `urls` (array of strings): known homepage URLs for this container (first in array is default) +- `issnp` (deprecated; string): Print ISSN; deprecated now that there is a top-level field +- `issne` (deprecated; string): Electronic ISSN; deprecated now that there is a top-level field Additional fields used in analytics and "curration" tracking: @@ -98,3 +102,13 @@ preserved). - `trade` - `test` +#### `publication_status` Vocabulary + +- `active`: ongoing publication of new releases +- `suspended`: publication has stopped, but may continue in the future +- `discontinued`: publication has permanently ceased +- `vanished`: publication has stopped, and public traces have vanished (eg, + publisher website has disapeared with no notice) +- `never`: no works were ever published under this container +- `one-time`: releases were all published as a one-time even. for example, a + single instance of a conference, or a fixed-size book series diff --git a/guide/src/entity_fileset.md b/guide/src/entity_fileset.md index 7e5ac757..e1ac3e67 100644 --- a/guide/src/entity_fileset.md +++ b/guide/src/entity_fileset.md @@ -3,15 +3,17 @@ ## Fields -Warning: This schema is not yet stable. - - `manifest` (array of objects): each entry represents a file - `path` (string, required): relative path to file (including filename) - `size` (integer, required): in bytes - `md5` (string): MD5 hash in lower-case hex - `sha1` (string): SHA-1 hash in lower-case hex - `sha256` (string): SHA-256 hash in lower-case hex + - `mimetype` (string): Content type in MIME type schema - `extra` (object): any extra metadata about this specific file + - `original_url`: live web canonical URL to download this file (optional) + - `webarchive_url`: web archive capture of this file (optional) + - `platform_id`: platform-specific identifier for this file - `urls`: An array of "typed" URLs. Order is not meaningful, and may not be preserved. - `url` (string, required): @@ -19,3 +21,20 @@ Warning: This schema is not yet stable. - `rel` (string, required): Eg: "webarchive". - `release_ids` (array of string identifiers): references to `release` entities +- `extra` (object with string keys): additional metadata about this group of + files, including upstream platform-specific metadata and identifiers + +#### URL `rel` types + +- `repository`: URL of a live-web landing page or other location where content can be + found. May not be machine-reachable. +- `webarchive`: web archive version of `repository` +- `repository-bundle`: direct URL to a live-web "archive" file, such as `.zip`, + which contains all of the individual files in this fileset +- `webarchive-bundle`: web archive version of `repository-bundle` +- `archive-bundle`: file archive version of `repository-bundle` +- `repository-base`: live-web base URL/directory from which file `path` can be + appended to fetch individual files +- `archive-base`: base URL/directory from which file `path` can be appended to fetch + individual files + diff --git a/guide/src/entity_release.md b/guide/src/entity_release.md index 028d99fc..dd09b30b 100644 --- a/guide/src/entity_release.md +++ b/guide/src/entity_release.md @@ -144,11 +144,18 @@ complete or correct in more obscure cases. should *always* be stored will be needed. - `core` (string): external identifier for the [CORE] open access aggregator. These identifiers are integers, but stored in string format. -- `arxiv` (string) external identifier to a (version-specific) [arxiv.org][] +- `arxiv` (string): external identifier to a (version-specific) [arxiv.org][] work. For releases, must always include the `vN` suffix (eg, `v3`). -- `jstor` (string) external identifier for works in JSTOR. -- `ark` (string) ARK identifer -- `mag` (string) Microsoft Academic Graph identifier +- `jstor` (string): external identifier for works in JSTOR. +- `ark` (string): ARK identifer +- `mag` (deprecated; string): Microsoft Academic Graph identifier. Never used, + may be deleted in the future +- `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 +- `hdl` (string): [handle.net](https://handle.net) identifier. While DOIs are + technically handles, do not put DOIs in this field. Handles are transformed + to lower-case in database. [arxiv.org]: https://arxiv.org @@ -170,6 +177,10 @@ complete or correct in more obscure cases. should be referenced/indicated instead. Intended as a temporary hint until proper work-based search is implemented. As an example use, all arxiv release versions except for the most recent get this set. +- `is_work_alias` (boolean): if true, then this release is an alias or pointer to + the entire work, or the most recent version of the work. For example, some + data repositories have separate DOIs for each version of the dataset, then an + additional DOI that points to the "lastest" version/DOI. #### `release_type` Vocabulary @@ -199,7 +210,8 @@ with a small number of (proposed) extensions: - `post-weblog` for blog entries - `report` - `review`, for things like book reviews, not the "literature review" form of - `article-journal`, nor peer reviews (see `peer_review`) + `article-journal`, nor peer reviews (see `peer_review`). Note `review-book` + for book reviews specifically. - `speech` can be used for eg, slides and recorded conference presentations themselves, as distinct from `paper-conference` - `thesis` @@ -216,8 +228,8 @@ with a small number of (proposed) extensions: - `stub` (fatcat extension) for releases which have notable external identifiers, and thus are included "for completeness", but don't seem to represent a "full work". -- `component` (fatcat extension) for sub-components of a full paper (or other - work). Eg, figures or tables. +- `component` (fatcat extension) for sub-components of a full paper or other + work. Eg, tables, or individual files as part of a dataset. An example of a `stub` might be a paper that gets an extra DOI by accident; the primary DOI should be a full release, and the accidental DOI can be a `stub` -- cgit v1.2.3