rust codegen

This re-ordered a lot of code, because several endpoints had their tags
changed, but should be no actual change in behavior/spec.

1 files changed, 830 insertions, 222 deletions

diff --git a/rust/fatcat-openapi/api/swagger.yaml b/rust/fatcat-openapi/api/swagger.yaml
index b4c5e657..296570af 100644
--- a/rust/fatcat-openapi/api/swagger.yaml
+++ b/rust/fatcat-openapi/api/swagger.yaml
@@ -1,21 +1,146 @@
 ---
 swagger: "2.0"
 info:
-  description: "A scalable, versioned, API-oriented catalog of bibliographic entities\
-    \ and file metadata"
+  description: "Fatcat is a scalable, versioned, API-oriented catalog of bibliographic\n\
+    entities and file metadata.\n\n<!-- STARTLONGDESCRIPTION -->\nThese API reference\
+    \ documents, along with client software libraries, are\ngenerated automatically\
+    \ from an OpenAPI 2.0 (\"Swagger\") definition file.\n\n## Introduction\n\n\n\
+    A higher-level introduction to the API, as well as a description of the\nfatcat\
+    \ data model, are available in [\"The Fatcat Guide\"](https://guide.fatcat.wiki/).\n\
+    The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)\n\
+    section demonstrating end-to-end tasks like creating entities as part of\neditgroups,\
+    \ or safely merging duplicate entities.\n\n### Expectations and Best Practices\n\
+    \nA test/staging QA API instance of fatcat is available at\n<https://api.qa.fatcat.wiki/v0>.\
+    \ The database backing this instance is\nseparate from the production interface,\
+    \ and is periodically rebuilt from\nsnapshots of the full production database,\
+    \ meaning that edits on the QA\nserver will *NOT* persist, and that semantics\
+    \ like the changelog index\nmonotonically increasing *MAY* be broken. Developers\
+    \ are expexcted to test\ntheir scripts and tools against the QA instance before\
+    \ running against\nproduction.\n\nFatcat is made available as a gratis (no cost)\
+    \ and libre (freedom\npreserving) service to the public, with limited funding\
+    \ and resources. We\nwelcome new and unforseen uses and contributions, but may\
+    \ need to impose\nrestrictions (like rate-limits) to keep the service functional\
+    \ for other\nusers, and in extreme cases reserve the option to block accounts\
+    \ and IP\nranges if necessary to keep the service operational.\n\nThe Internet\
+    \ Archive owns and operates it's own server equipment and data\ncenters, and operations\
+    \ are optimized for low-cost, not high-availability.\nUsers and partners should\
+    \ expect some downtime on the fatcat API, on the\norder of hours a month.\n\n\
+    Periodic metadata exports are available for batch processing, and database\nsnapshots\
+    \ can be used to create locally-hosted mirrors of the service for\nmore intensive\
+    \ and reliable querying.\n\n### Other Nitty Gritties\n\nCross-origin requests\
+    \ are allowed for the API service, to enable third\nparties to bulid in-browser\
+    \ applications.\n\nA metadata search service is available at <https://search.fatcat.wiki>\
+    \ (and\n<https://search.qa.fatcat.wiki>). The API is currently the raw\nelasticsearch\
+    \ API, with only GET (read) requests allowed. This public\nservice is experimental\
+    \ and may be removed or limited in the future.\n\n## Authentication\n\nThe API\
+    \ allows basic read-only \"GET\" HTTP requests with no authentication.\nProposing\
+    \ changes to the metadata, or other mutating requests (\"PUT\",\n\"POST\", \"\
+    DELETE\") all require authentication, and some operations require\nadditional\
+    \ account permissions.\n\nEnd-user account creation and login happens through\
+    \ the web interface. From\na logged-in editor profile page, you can generate a\
+    \ API token. Tokens are\n\"macaroons\", similar to JWT tokens, and are used for\
+    \ all API\nauthentication. The web interface includes macaroons in browser cookies\
+    \ and\npasses them through to the API to authenticate editor actions.\n\n<!--\
+    \ ReDoc-Inject: <security-definitions> -->\n<!-- ENDLONGDESCRIPTION -->\n"
   version: "0.3.0"
   title: "fatcat"
+  termsOfService: "https://guide.fatcat.wiki/policies.html"
+  contact:
+    name: "Internet Archive Web Group"
+    url: "https://fatcat.wiki"
+    email: "webservices@archive.org"
+  x-logo:
+    url: "https://fatcat.wiki/static/paper_man_confused.gif"
+    altText: "Confused Papers Man (Logo)"
+    backgroundColor: "#FFFFFF"
 host: "api.fatcat.wiki"
 basePath: "/v0"
 tags:
 - name: "containers"
+  description: "**Container** entities represent publication venues like journals,\
+    \  # TAGLINE\nconference proceedings, book series, or blogs. They group publications\
+    \  # TAGLINE\n(\"releases\").  # TAGLINE\n\nSee the \"Catalog Style Guide\" section\
+    \ of the guide for details and  # TAGLINE\nsemantics of what should be included\
+    \ in specific entity fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n[Container\
+    \ Entity Reference](https://guide.fatcat.wiki/entity_container.html).  # TAGLINE\n"
+  x-displayName: "Containers"
 - name: "creators"
+  description: "**Creator** entities represent individuals (or organizations, or other\
+    \  # TAGLINE\nagents) who contribute to the creation of specific releases  # TAGLINE\n\
+    (publications).  # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide\
+    \ for details and  # TAGLINE\nsemantics of what should be included in specific\
+    \ entity fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n[Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html).\
+    \  # TAGLINE\n"
+  x-displayName: "Creators"
 - name: "files"
+  description: "**File** entities represent unique digital files which are full  #\
+    \ TAGLINE\nmanifestations of specific releases (publications), such as fulltext\
+    \ PDF  # TAGLINE\nfiles, JATS XML documents, or video files. File entities also\
+    \ include a  # TAGLINE\nset of locations where they can be found on the public\
+    \ web.  # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide for\
+    \ details and  # TAGLINE\nsemantics of what should be included in specific entity\
+    \ fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n[File Entity Reference](https://guide.fatcat.wiki/entity_file.html).\
+    \  # TAGLINE\n"
+  x-displayName: "Files"
 - name: "filesets"
+  description: "**Fileset** entities represent sets of digital files, as well as locations\
+    \  # TAGLINE\nwhere they can be found on the public web. Filesets most commonly\
+    \  # TAGLINE\nrepresent datasets consisting of serveral data and metadata files.\
+    \  # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide for details\
+    \ and  # TAGLINE\nsemantics of what should be included in specific entity fields.\
+    \  # TAGLINE\nSpecifically, the  # TAGLINE\n[Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html).\
+    \  # TAGLINE\n"
+  x-displayName: "Filesets"
 - name: "webcaptures"
+  description: "**Web Capture** entities represent archival snapshots of web pages\
+    \ (or  # TAGLINE\nother web resources), which are usually complete manifestations\
+    \ of a  # TAGLINE\nspecific release entity. Web Captures also include a set of\
+    \ locations  # TAGLINE\n(wayback replay instances or WARC files) where the capture\
+    \ can be found.  # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide\
+    \ for details and  # TAGLINE\nsemantics of what should be included in specific\
+    \ entity fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n[Web Capture Entity\
+    \ Reference](https://guide.fatcat.wiki/entity_webcapture.html).  # TAGLINE\n"
+  x-displayName: "Webcaptures"
 - name: "releases"
+  description: "**Release** entities represent specific published versions of a research\
+    \  # TAGLINE\nwork, such as a pre-print, a journal article, a book (or chapter),\
+    \ or a  # TAGLINE\nscholarly blog post. Releases are always grouped together under\
+    \ Works;  # TAGLINE\nthey may be published in a specific Container; they may have\
+    \ known  # TAGLINE\nCreators; and there may exist known File/Fileset/WebCapture\
+    \ digital copies  # TAGLINE\nof the release.  # TAGLINE\n\nSee the \"Catalog Style\
+    \ Guide\" section of the guide for details and  # TAGLINE\nsemantics of what should\
+    \ be included in specific entity fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n\
+    [Release Entity Reference](https://guide.fatcat.wiki/entity_release.html).  #\
+    \ TAGLINE\n"
+  x-displayName: "Releases"
 - name: "works"
-- name: "edit-lifecycle"
+  description: "**Work** entities group several Release entities which are different\
+    \  # TAGLINE\nversions of the same abstract piece of research. For example, three\
+    \  # TAGLINE\nrelease entities representing the pre-print, published article,\
+    \ and  # TAGLINE\nretraction stages of the same journal paper would be grouped\
+    \ under a  # TAGLINE\nsingle work.  # TAGLINE\n\nSee the \"Catalog Style Guide\"\
+    \ section of the guide for details and  # TAGLINE\nsemantics of what should be\
+    \ included in specific entity fields.  # TAGLINE\nSpecifically, the  # TAGLINE\n\
+    [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html).  # TAGLINE\n"
+  x-displayName: "Works"
+- name: "editgroups"
+  description: "**Editgroups** are sets of changes, each to individual entities in\
+    \ the  # TAGLINE\ncatalog. Every edit must be part of an editgroup which is reviewed\
+    \ and  # TAGLINE\naccepted (merged) as a whole.  # TAGLINE\n"
+  x-displayName: "Editgroups"
+- name: "editors"
+  description: "**Editors** are human user accounts and bots that make changes to\
+    \ the  # TAGLINE\nFatcat catalog.  # TAGLINE\n\nThe API allows fetching (and updating)\
+    \ metadata about individual editors,  # TAGLINE\nas well as fetching editor's\
+    \ annotation and edit history.  # TAGLINE\n"
+  x-displayName: "Editors"
+- name: "changelog"
+  description: "The **Changelog** is the ordered feed of editgroups which have been\
+    \  # TAGLINE\naccepted into the catalog.  # TAGLINE\n"
+  x-displayName: "Changelog"
+- name: "auth"
+  description: "Helper methods and internal APIs for editor authentication.  # TAGLINE\n"
+  x-displayName: "Auth Methods"
 schemes:
 - "https"
 consumes:
@@ -27,6 +152,9 @@ paths:
     post:
       tags:
       - "containers"
+      description: "Create a single Container entity as part of an existing editgroup.\n\
+        \nEditgroup must be mutable (aka, not accepted) and editor must have\npermission\
+        \ (aka, have created the editgrou p or have `admin` role).\n"
       operationId: "create_container"
       parameters:
       - name: "editgroup_id"
@@ -117,6 +245,12 @@ paths:
     post:
       tags:
       - "containers"
+      description: "Create a set of Container entities as part of a new editgroup,\
+        \ and\naccept that editgroup in the same atomic request.\n\nThis method is\
+        \ mostly useful for bulk import of new entities by\ncarefully written bots.\
+        \ This method is more efficient than creating an\neditgroup, several entities,\
+        \ then accepting the editgroup, both in\nterms of API requests required and\
+        \ database load. Requires `admin`\nrole.\n"
       operationId: "create_container_auto_batch"
       parameters:
       - in: "body"
@@ -201,6 +335,7 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Fetches a single container entity from the catalog.\n"
       operationId: "get_container"
       parameters:
       - name: "ident"
@@ -271,6 +406,13 @@ paths:
     put:
       tags:
       - "containers"
+      description: "Updates an existing entity as part of a specific (existing) editgroup.\n\
+        The editgroup must be open for updates (aka, not accepted/merged), and\nthe\
+        \ editor making the requiest must have permissions (aka, must have\ncreated\
+        \ the editgroup or have `admin` role).\n\nThis method can also be used to\
+        \ update an existing entity edit as part\nof an editgroup. For example, if\
+        \ an entity was created in this\neditgroup, an editor could make changes to\
+        \ the new entity's metadata\nbefore merging.\n"
       operationId: "update_container"
       parameters:
       - name: "editgroup_id"
@@ -366,6 +508,9 @@ paths:
     delete:
       tags:
       - "containers"
+      description: "Creates a new \"deletion\" edit for a specific entity as part\
+        \ of an\nexisting editgroup.\n\nThis is not the method to use to remove an\
+        \ edit from an editgroup; for\nthat use `delete_container_edit`.\n"
       operationId: "delete_container"
       parameters:
       - name: "editgroup_id"
@@ -449,6 +594,11 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Fetches a specific entity revision. Note that the returned revision\n\
+        will not be associated with any particular fatcat identifier (even if\none\
+        \ or more identifiers do currently point to this revision). The\nrevision\
+        \ may even be part of an un-merged editgroup.\n\nRevisions are immutable and\
+        \ can not be deleted or updated.\n"
       operationId: "get_container_revision"
       parameters:
       - name: "rev_id"
@@ -463,16 +613,14 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For containers,\
-          \ none accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_container`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For containers,\
-          \ none accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_container`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -523,6 +671,8 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Fetches the history of accepted edits (changelog entries) for\
+        \ a\nspecific entity fatcat identifier.\n"
       operationId: "get_container_history"
       parameters:
       - name: "ident"
@@ -533,6 +683,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "limit"
         in: "query"
+        description: "Maximum number of changelog entries to return"
         required: false
         type: "integer"
         format: "int64"
@@ -586,6 +737,8 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Returns the set of entity identifiers which currently redirect\
+        \ to this\nidentifier.\n"
       operationId: "get_container_redirects"
       parameters:
       - name: "ident"
@@ -601,7 +754,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -647,6 +799,11 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Looks for an active entity with the given external identifier.\
+        \ If any\nsuch entity is found, returns a single complete entity. If multiple\n\
+        entities have the same external identifier, this is considered a soft\ncatalog\
+        \ error, and the behavior of which entity is returned is\nundefined.\n\nOne\
+        \ (and only one) external identifier should be specified per request.\n"
       operationId: "lookup_container"
       parameters:
       - name: "issnl"
@@ -661,19 +818,19 @@ paths:
       - name: "wikidata_qid"
         in: "query"
         required: false
+        type: "string"
         formatString: "{:?}"
         example: "Some(\"wikidata_qid_example\".to_string())"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response."
+        description: "List of sub-entities to expand in response. See `get_container`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For container, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_container`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -724,6 +881,8 @@ paths:
     get:
       tags:
       - "containers"
+      description: "Returns the entity edit object with the given identifier. This\
+        \ method\nis expected to be used rarely.\n"
       operationId: "get_container_edit"
       parameters:
       - name: "edit_id"
@@ -782,6 +941,11 @@ paths:
     delete:
       tags:
       - "containers"
+      description: "Removes a single edit from the specified editgroup. The editgroup\
+        \ must\nbe mutable (aka, not accepted/merged), and the editor making this\n\
+        request must have permission (aka, have created the editgroup or hold\nthe\
+        \ `admin` role).\n\nNot to be confused with the `delete_container` method,\
+        \ which *creates*\na new edit in the given editgroup.\n"
       operationId: "delete_container_edit"
       parameters:
       - name: "editgroup_id"
@@ -1061,8 +1225,8 @@ paths:
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For containers,\
-          \ none accepted (yet)."
+        description: "List of entity fields to elide in response. For creators, none\
+          \ accepted (yet)."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -1305,16 +1469,16 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For creators, none\
-          \ accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_creator`,\n\
+          though note that identifier-based expansions (like `releases`) will\nalways\
+          \ be empty for revisions.\n"
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For creators, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_creator`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -1428,6 +1592,8 @@ paths:
     get:
       tags:
       - "creators"
+      description: "Returns the set of Release entities having a `contrib` entry pointing\n\
+        to the creator entity.\n"
       operationId: "get_creator_releases"
       parameters:
       - name: "ident"
@@ -1438,8 +1604,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For creators, none\
-          \ implemented yet."
+        description: "List of entity fields to elide in response. See `get_release`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -1507,7 +1672,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -1557,6 +1721,7 @@ paths:
       parameters:
       - name: "orcid"
         in: "query"
+        description: "ORCiD (https://orcid.org) identifier"
         required: false
         type: "string"
         maxLength: 19
@@ -1567,19 +1732,19 @@ paths:
       - name: "wikidata_qid"
         in: "query"
         required: false
+        type: "string"
         formatString: "{:?}"
         example: "Some(\"wikidata_qid_example\".to_string())"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response."
+        description: "List of sub-entities to expand in response. See `get_creator`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For creator, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_creator`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -2211,16 +2376,14 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For files, none\
-          \ accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_file`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For files, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_file`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -2349,7 +2512,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -2399,6 +2561,7 @@ paths:
       parameters:
       - name: "md5"
         in: "query"
+        description: "MD5 hash of data, in hex encoding"
         required: false
         type: "string"
         maxLength: 32
@@ -2408,6 +2571,7 @@ paths:
         example: "Some(\"md5_example\".to_string())"
       - name: "sha1"
         in: "query"
+        description: "SHA-1 hash of data, in hex encoding"
         required: false
         type: "string"
         maxLength: 40
@@ -2417,6 +2581,7 @@ paths:
         example: "Some(\"sha1_example\".to_string())"
       - name: "sha256"
         in: "query"
+        description: "SHA-256 hash of data, in hex encoding"
         required: false
         type: "string"
         maxLength: 64
@@ -2426,15 +2591,14 @@ paths:
         example: "Some(\"sha256_example\".to_string())"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response."
+        description: "List of sub-entities to expand in response. See `get_file`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For files, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_file`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -3066,16 +3230,14 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For filesets, none\
-          \ accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_fileset`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For filesets, 'manifest'\
-          \ is accepted."
+        description: "List of entity fields to elide in response. See `get_fileset`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -3204,7 +3366,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -3831,16 +3992,14 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For webcaptures,\
-          \ none accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_webcapture`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For webcaptures,\
-          \ 'cdx' is accepted."
+        description: "List of entity fields to elide in response. See `get_webcapture`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -3969,7 +4128,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -4160,6 +4318,11 @@ paths:
     post:
       tags:
       - "releases"
+      description: "Create a single Release entity as part of an existing editgroup.\
+        \ If the\n`work_id` field is not set, a work entity will be created automatically\n\
+        and this field set pointing to the new work.\n\nEditgroup must be mutable\
+        \ (aka, not accepted) and editor must have\npermission (aka, have created\
+        \ the editgrou p or have `admin` role).\n"
       operationId: "create_release"
       parameters:
       - name: "editgroup_id"
@@ -4250,6 +4413,12 @@ paths:
     post:
       tags:
       - "releases"
+      description: "Create a set of Release entities as part of a new editgroup, and\n\
+        accept that editgroup in the same atomic request.\n\nThis method is mostly\
+        \ useful for bulk import of new entities by\ncarefully written bots. This\
+        \ method is more efficient than creating an\neditgroup, several entities,\
+        \ then accepting the editgroup, both in\nterms of API requests required and\
+        \ database load. Requires `admin`\nrole.\n"
       operationId: "create_release_auto_batch"
       parameters:
       - in: "body"
@@ -4334,6 +4503,7 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Fetches a single Release entity from the catalog.\n"
       operationId: "get_release"
       parameters:
       - name: "ident"
@@ -4344,16 +4514,16 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For releases, 'files',\
-          \ 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+        description: "List of sub-entities to expand in response. For releases, 'files',\n\
+          'filesets, 'webcaptures', 'container', and 'creators' are valid.\n"
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For releases, 'abstracts',\
-          \ 'refs', and 'contribs' are valid."
+        description: "List of entity fields to elide in response (for efficiency).\
+          \ For\nreleases, 'abstracts', 'refs', and 'contribs' are valid.\n"
         required: false
         type: "string"
         formatString: "{:?}"
@@ -4404,6 +4574,13 @@ paths:
     put:
       tags:
       - "releases"
+      description: "Updates an existing entity as part of a specific (existing) editgroup.\n\
+        The editgroup must be open for updates (aka, not accepted/merged), and\nthe\
+        \ editor making the requiest must have permissions (aka, must have\ncreated\
+        \ the editgroup or have `admin` role).\n\nThis method can also be used to\
+        \ update an existing entity edit as part\nof an editgroup. For example, if\
+        \ an entity was created in this\neditgroup, an editor could make changes to\
+        \ the new entity's metadata\nbefore merging.\n"
       operationId: "update_release"
       parameters:
       - name: "editgroup_id"
@@ -4499,6 +4676,9 @@ paths:
     delete:
       tags:
       - "releases"
+      description: "Creates a new \"deletion\" edit for a specific entity as part\
+        \ of an\nexisting editgroup.\n\nThis is not the method to use to remove an\
+        \ edit from an editgroup; for\nthat use `delete_release_edit`.\n"
       operationId: "delete_release"
       parameters:
       - name: "editgroup_id"
@@ -4582,6 +4762,11 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Fetches a specific entity revision. Note that the returned revision\n\
+        will not be associated with any particular fatcat identifier (even if\none\
+        \ or more identifiers do currently point to this revision). The\nrevision\
+        \ may even be part of an un-merged editgroup.\n\nRevisions are immutable and\
+        \ can not be deleted or updated.\n"
       operationId: "get_release_revision"
       parameters:
       - name: "rev_id"
@@ -4596,16 +4781,16 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For releases, none\
-          \ accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_release`,\
+          \ though note that identifier-based exapansions like `file` will always\
+          \ be empty for revisions."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For releases, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_release`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -4656,6 +4841,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Fetches the history of accepted edits (changelog entries) for\
+        \ a\nspecific entity fatcat identifier.\n"
       operationId: "get_release_history"
       parameters:
       - name: "ident"
@@ -4719,6 +4906,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Returns the set of File entities that have a `release_id` pointing\
+        \ to\nthis release entity.\n"
       operationId: "get_release_files"
       parameters:
       - name: "ident"
@@ -4729,8 +4918,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For files, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_file`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -4783,6 +4971,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Returns the set of Fileset entities that have a `release_id` pointing\
+        \ to\nthis release entity.\n"
       operationId: "get_release_filesets"
       parameters:
       - name: "ident"
@@ -4793,8 +4983,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For filesets, 'manifest'\
-          \ is valid."
+        description: "List of entity fields to elide in response. See `get_fileset`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -4847,6 +5036,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Returns the set of Web Capture entities that have a `release_id`\n\
+        pointing to this release entity.\n"
       operationId: "get_release_webcaptures"
       parameters:
       - name: "ident"
@@ -4857,8 +5048,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For webcaptures,\
-          \ 'cdx' is valid."
+        description: "List of entity fields to elide in response. See `get_webcapture`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -4911,6 +5101,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Returns the set of entity identifiers which currently redirect\
+        \ to this\nidentifier.\n"
       operationId: "get_release_redirects"
       parameters:
       - name: "ident"
@@ -4926,7 +5118,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -4972,6 +5163,11 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Looks for an active entity with the given external identifier.\
+        \ If any\nsuch entity is found, returns a single complete entity. If multiple\n\
+        entities have the same external identifier, this is considered a soft\ncatalog\
+        \ error, and the behavior of which entity is returned is\nundefined.\n\nOne\
+        \ (and only one) external identifier should be specified per request.\n"
       operationId: "lookup_release"
       parameters:
       - name: "doi"
@@ -5036,15 +5232,14 @@ paths:
         example: "Some(\"mag_example\".to_string())"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response."
+        description: "List of sub-entities to expand in response. See `get_release`."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of sub-entities to expand in response. For releases, 'files',\
-          \ 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+        description: "List of sub-entities to elide in response. See `get_release`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -5095,6 +5290,8 @@ paths:
     get:
       tags:
       - "releases"
+      description: "Returns the entity edit object with the given identifier. This\
+        \ method\nis expected to be used rarely.\n"
       operationId: "get_release_edit"
       parameters:
       - name: "edit_id"
@@ -5153,6 +5350,11 @@ paths:
     delete:
       tags:
       - "releases"
+      description: "Removes a single edit from the specified editgroup. The editgroup\
+        \ must\nbe mutable (aka, not accepted/merged), and the editor making this\n\
+        request must have permission (aka, have created the editgroup or hold\nthe\
+        \ `admin` role).\n\nNot to be confused with the `delete_container` method,\
+        \ which *creates*\na new edit in the given editgroup.\n"
       operationId: "delete_release_edit"
       parameters:
       - name: "editgroup_id"
@@ -5239,7 +5441,7 @@ paths:
   /editgroup/{editgroup_id}/work:
     post:
       tags:
-      - "releases"
+      - "works"
       operationId: "create_work"
       parameters:
       - name: "editgroup_id"
@@ -5676,16 +5878,16 @@ paths:
         example: "\"rev_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For works, none\
-          \ accepted (yet)."
+        description: "List of sub-entities to expand in response. See `get_work`,\
+          \ though note that identifier-based expansions like `releases` will always\
+          \ be empty for revisions."
         required: false
         type: "string"
         formatString: "{:?}"
         example: "Some(\"expand_example\".to_string())"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For works, none\
-          \ accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_work`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -5814,7 +6016,6 @@ paths:
             type: "array"
             items:
               type: "string"
-              example: "q3nouwy3nnbsvo3h5klxsx4a7y"
               description: "base32-encoded unique identifier"
               minLength: 26
               maxLength: 26
@@ -5860,6 +6061,8 @@ paths:
     get:
       tags:
       - "works"
+      description: "Returns the set of release entities that are part of this work\
+        \ (aka,\nhave `work_id` pointing to this work entity).\n"
       operationId: "get_work_releases"
       parameters:
       - name: "ident"
@@ -5870,8 +6073,7 @@ paths:
         example: "\"ident_example\".to_string()"
       - name: "hide"
         in: "query"
-        description: "List of entity fields to elide in response. For works, none\
-          \ implemented yet."
+        description: "List of entity fields to elide in response. See `get_release`."
         required: false
         type: "string"
         formatString: "{:?}"
@@ -6067,6 +6269,10 @@ paths:
       httpmethod: "delete"
   /editor/{editor_id}:
     get:
+      tags:
+      - "editors"
+      description: "Returns an editor object, including metadata such as the username,\n\
+        type, and role of editor.\n"
       operationId: "get_editor"
       parameters:
       - name: "editor_id"
@@ -6118,6 +6324,12 @@ paths:
       HttpMethod: "Get"
       httpmethod: "get"
     put:
+      tags:
+      - "editors"
+      description: "Allows metadata changes to some editor fields, such as the username.\n\
+        \nChanges require authentication and permissions. An editor can change\ntheir\
+        \ own username; changes to role flags require the `admin` role by\nthe editor\
+        \ making the request.\n"
       operationId: "update_editor"
       parameters:
       - name: "editor_id"
@@ -6206,6 +6418,10 @@ paths:
       noClientExample: true
   /editor/{editor_id}/editgroups:
     get:
+      tags:
+      - "editors"
+      description: "Returns a set of editgroups created by the given editor, regardless\
+        \ of\nthe status (accepted/submitted) of the editgroups.\n"
       operationId: "get_editor_editgroups"
       parameters:
       - name: "editor_id"
@@ -6223,6 +6439,9 @@ paths:
         example: "Some(789)"
       - name: "before"
         in: "query"
+        description: "Return only editgroups created *before* the given timestamp\
+          \ (not\ninclusive). Editgroups will be sorted by creation time in\ndescending\
+          \ order (most recent first). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6230,6 +6449,9 @@ paths:
         example: "None"
       - name: "since"
         in: "query"
+        description: "Return only editgroups created *after* the given timestamp (not\n\
+          inclusive). Editgroups will be sorted by creation time in ascending\norder\
+          \ (most recent last). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6282,7 +6504,8 @@ paths:
   /editor/{editor_id}/annotations:
     get:
       tags:
-      - "edit-lifecycle"
+      - "editors"
+      description: "Fetches a list of annotations made by a particular editor.\n"
       operationId: "get_editor_annotations"
       parameters:
       - name: "editor_id"
@@ -6297,6 +6520,7 @@ paths:
         example: "\"editor_id_example\".to_string()"
       - name: "limit"
         in: "query"
+        description: "Maximum number (count) of annotations to return in response"
         required: false
         type: "integer"
         format: "int64"
@@ -6304,6 +6528,9 @@ paths:
         example: "Some(789)"
       - name: "before"
         in: "query"
+        description: "Return only annotations made *before* the given timestamp (not\n\
+          inclusive). Annotations will be sorted by creation time in\ndescending order\
+          \ (most recent first). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6311,6 +6538,9 @@ paths:
         example: "None"
       - name: "since"
         in: "query"
+        description: "Return only annotations made *after* the given timestamp (not\n\
+          inclusive). Annotations will be sorted by creation time in\nascending order\
+          \ (most recent last). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6384,7 +6614,9 @@ paths:
   /editgroup:
     post:
       tags:
-      - "edit-lifecycle"
+      - "editgroups"
+      description: "Creates a new editgroup. By default the editor making this request\
+        \ will\nbe the author of the editgroup.\n"
       operationId: "create_editgroup"
       parameters:
       - in: "body"
@@ -6468,7 +6700,11 @@ paths:
   /editgroup/{editgroup_id}:
     get:
       tags:
-      - "edit-lifecycle"
+      - "editgroups"
+      description: "Returns a single editgroup object.\n\nUnlike some similar methods,\
+        \ this method will return a full/expanded\neditgroup object, which includes\
+        \ edit lists of each entity type (though\nwill not include the complete entity\
+        \ objects).\n"
       operationId: "get_editgroup"
       parameters:
       - name: "editgroup_id"
@@ -6524,6 +6760,12 @@ paths:
       HttpMethod: "Get"
       httpmethod: "get"
     put:
+      tags:
+      - "editgroups"
+      description: "Updates metadata for a single editgroup object. Note that only\
+        \ metadata\nfields such as the `description` or `extra` metadata can be changed\n\
+        with this method; it does not allow adding or removing edits to the\neditgroup\
+        \ (for that use the individual entity create/update/delete\nmethods).\n"
       operationId: "update_editgroup"
       parameters:
       - name: "editgroup_id"
@@ -6623,7 +6865,10 @@ paths:
   /editgroup/{editgroup_id}/accept:
     post:
       tags:
-      - "edit-lifecycle"
+      - "editgroups"
+      description: "Accept (\"merge\") the given editgroup into the catalog. The editgroup\n\
+        must be open (not already accepted), and the editor making this request\n\
+        must have the `admin` role.\n"
       operationId: "accept_editgroup"
       parameters:
       - name: "editgroup_id"
@@ -6713,7 +6958,8 @@ paths:
   /editgroup/{editgroup_id}/annotations:
     get:
       tags:
-      - "edit-lifecycle"
+      - "editgroups"
+      description: "Returns a list of annotations made to a specific editgroup."
       operationId: "get_editgroup_annotations"
       parameters:
       - name: "editgroup_id"
@@ -6728,7 +6974,7 @@ paths:
         example: "\"editgroup_id_example\".to_string()"
       - name: "expand"
         in: "query"
-        description: "List of sub-entities to expand in response. For editgroups:\
+        description: "List of sub-entities to expand in response. For editgroup annotations:\
           \ 'editors'"
         required: false
         type: "string"
@@ -6802,7 +7048,10 @@ paths:
   /editgroup/{editgroup_id}/annotation:
     post:
       tags:
-      - "edit-lifecycle"
+      - "editgroups"
+      description: "Submits a new annotation to the specified editgroup.\n\nThe editgroup\
+        \ must be open (not already accepted). The annotation will\nautomatically\
+        \ have authorship of the editor making this request.\n"
       operationId: "create_editgroup_annotation"
       parameters:
       - name: "editgroup_id"
@@ -6895,6 +7144,11 @@ paths:
       noClientExample: true
   /editgroup/reviewable:
     get:
+      tags:
+      - "editgroups"
+      description: "Returns a set of editgroups which have been submitted but not\
+        \ yet accepted.\n\nQuery parameters can be used to sort and paginate the list\
+        \ returned.\n"
       operationId: "get_editgroups_reviewable"
       parameters:
       - name: "expand"
@@ -6907,6 +7161,7 @@ paths:
         example: "Some(\"expand_example\".to_string())"
       - name: "limit"
         in: "query"
+        description: "Maximum number of reviewable editgroups to return in response"
         required: false
         type: "integer"
         format: "int64"
@@ -6914,6 +7169,9 @@ paths:
         example: "Some(789)"
       - name: "before"
         in: "query"
+        description: "Return only reviewable editgroups submitted *before* the given\n\
+          timestamp (not inclusive). Editgroups will be sorted by submission\ntime\
+          \ in descending order (most recent first). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6921,6 +7179,9 @@ paths:
         example: "None"
       - name: "since"
         in: "query"
+        description: "Return only reviewable editgroups submitted *after* the given\n\
+          timestamp (not inclusive). Editgroups will be sorted by submission\ntime\
+          \ in ascending order (most recent last). For use in pagination.\n"
         required: false
         type: "string"
         format: "date-time"
@@ -6973,11 +7234,22 @@ paths:
   /changelog:
     get:
       tags:
-      - "edit-lifecycle"
+      - "changelog"
+      description: "Returns a list of the most recent changelog entries accepted (merged)\n\
+        into the catalog.\n\nList is sorted by changelog index in descending order.\
+        \ Note that the\naccepted timestamp roughly corresponds to order, but not\
+        \ strictly;\nthere exist out-of-order timestamps on the order of several seconds.\n\
+        \nAs a known database issue, it is technically possible for there to be a\n\
+        gap in changelog index numbers (aka, a missing changelog entry). There\nare\
+        \ no currently known gaps and this is considered a bug that will be\naddressed.\n\
+        \nThere are millions of entries; to paginate through all of them, use\nthis\
+        \ method to discover the highest existing entry number, then request\nthe\
+        \ entries using `get_changelog_entry` one at a time.\n"
       operationId: "get_changelog"
       parameters:
       - name: "limit"
         in: "query"
+        description: "Maximum count of changelog entries to return in response"
         required: false
         type: "integer"
         format: "int64"
@@ -7021,11 +7293,16 @@ paths:
   /changelog/{index}:
     get:
       tags:
-      - "edit-lifecycle"
+      - "changelog"
+      description: "Returns a single changelog entry.\n\nAs a known database issue,\
+        \ it is technically possible for there to be a\ngap in changelog index numbers\
+        \ (aka, a missing changelog entry). There\nare no currently known gaps and\
+        \ this is considered a bug that will be\naddressed.\n"
       operationId: "get_changelog_entry"
       parameters:
       - name: "index"
         in: "path"
+        description: "Changelog index of entry to return"
         required: true
         type: "integer"
         format: "int64"
@@ -7075,6 +7352,15 @@ paths:
       httpmethod: "get"
   /auth/oidc:
     post:
+      tags:
+      - "auth"
+      description: "Login or create editor account using OIDC metadata (internal method).\n\
+        \nThis method is used by privileged front-end tools (like the web\ninterface\
+        \ service) to process editor logins using OpenID Connect (OIDC)\nand/or OAuth.\
+        \ Most accounts (including tool and bot accounts) do not\nhave sufficient\
+        \ privileges to call this method, which requires the\n`admin` role.\n\nThe\
+        \ method returns an API token; the HTTP status code indicates whether\nan\
+        \ existing account was logged in, or a new account was created.\n"
       operationId: "auth_oidc"
       parameters:
       - in: "body"
@@ -7166,6 +7452,11 @@ paths:
       noClientExample: true
   /auth/check:
     get:
+      tags:
+      - "auth"
+      description: "Verify that authentication (API token) is working as expected.\
+        \ The\noptional `role` parameter can be used to verify that the current\n\
+        account (editor) has permissions for the given role.\n"
       operationId: "auth_check"
       parameters:
       - name: "role"
@@ -7232,6 +7523,18 @@ paths:
       httpmethod: "get"
 securityDefinitions:
   Bearer:
+    description: "The only current API authentication mechanism is HTTP bearer\nauthentication\
+      \ using the `Authorization` HTTP header. The header should\nbe formatted as\
+      \ the string \"Bearer\", then a space, then API token (in the\nusual base64\
+      \ string encoding).\n\nAn example HTTP request would look on the wire like:\n\
+      \n    GET /v0/auth/check HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip,\
+      \ deflate\n    Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\n\
+      \    Connection: keep-alive\n    Host: api.qa.fatcat.wiki\n    User-Agent: HTTPie/0.9.8\n\
+      \nHeaders can be passed on the command line using `http` (HTTPie) like:\n\n\
+      \    http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:\"Bearer\
+      \ AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\
+      \n\nOr with `curl`:\n\n    curl -H \"Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\
+      \ https://qa.fatcat.wiki/v0/auth/check\n"
     type: "apiKey"
     name: "Authorization"
     in: "header"
@@ -7245,8 +7548,10 @@ definitions:
     properties:
       success:
         type: "boolean"
+        example: false
       error:
         type: "string"
+        example: "unexpected-thing"
       message:
         type: "string"
         example: "A really confusing, totally unexpected thing happened"
@@ -7259,6 +7564,7 @@ definitions:
     properties:
       success:
         type: "boolean"
+        example: true
       message:
         type: "string"
         example: "The computers did the thing successfully!"
@@ -7271,26 +7577,38 @@ definitions:
     properties:
       wikidata_qid:
         type: "string"
+        example: "Q42812"
       issnl:
         type: "string"
         example: "1234-5678"
+        description: "Linking ISSN number (ISSN-L). Should be valid and registered\
+          \ with issn.org"
         minLength: 9
         maxLength: 9
         pattern: "\\d{4}-\\d{3}[0-9X]"
       publisher:
         type: "string"
         example: "Society of Curious Students"
+        description: "Name of the organization or entity responsible for publication.\
+          \ Not\nthe complete imprint/brand.\n"
       container_type:
         type: "string"
-        description: "Eg, 'journal'"
+        example: "journal"
+        description: "Type of container, eg 'journal' or 'proceedings'. See Guide\
+          \ for list of valid types."
       name:
         type: "string"
         example: "Journal of Important Results"
-        description: "Required for valid entities"
+        description: "Name of the container (eg, Journal title). Required for entity\
+          \ creation."
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       redirect:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7314,6 +7632,7 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7323,12 +7642,12 @@ definitions:
       redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
       extra: "{}"
-      container_type: "container_type"
+      container_type: "journal"
       name: "Journal of Important Results"
       publisher: "Society of Curious Students"
       issnl: "1234-5678"
-      wikidata_qid: "wikidata_qid"
-      state: "wip"
+      wikidata_qid: "Q42812"
+      state: "active"
       edit_extra: "{}"
       revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
     upperCaseName: "CONTAINER_ENTITY"
@@ -7337,22 +7656,31 @@ definitions:
     properties:
       wikidata_qid:
         type: "string"
+        example: "Q42812"
+        description: "Wikidata entity QID"
       orcid:
         type: "string"
         example: "0000-0002-1825-0097"
+        description: "ORCiD (https://orcid.org) identifier"
         minLength: 19
         maxLength: 19
         pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
       surname:
         type: "string"
+        description: "In English commonly the last, or family name, but ordering is\
+          \ context\nand culture specific.\n"
       given_name:
         type: "string"
+        description: "In English commonly the first name, but ordering is context\
+          \ and\nculture specific.\n"
       display_name:
         type: "string"
         example: "Grace Hopper"
-        description: "Required for valid entities"
+        description: "Name as should be displayed in web interface or in author lists\
+          \ (not\nindex/sorted). Required for valid entities.\n"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7381,16 +7709,20 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
     example:
       redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
       surname: "surname"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
       extra: "{}"
       orcid: "0000-0002-1825-0097"
-      wikidata_qid: "wikidata_qid"
-      state: "wip"
+      wikidata_qid: "Q42812"
+      state: "active"
       given_name: "given_name"
       display_name: "Grace Hopper"
       edit_extra: "{}"
@@ -7401,11 +7733,15 @@ definitions:
     properties:
       releases:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Full release entities, included in GET responses when `releases`\n\
+          included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
         items:
           $ref: "#/definitions/release_entity"
       release_ids:
         type: "array"
+        description: "Set of identifier of release entities this file represents a\
+          \ full\nmanifestation of. Usually a single release, but some files contain\n\
+          content of multiple full releases (eg, an issue of a journal).\n"
         items:
           type: "string"
           example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7423,18 +7759,21 @@ definitions:
       sha256:
         type: "string"
         example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+        description: "SHA-256 hash of data, in hex encoding"
         minLength: 64
         maxLength: 64
         pattern: "[a-f0-9]{64}"
       sha1:
         type: "string"
         example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+        description: "SHA-1 hash of data, in hex encoding"
         minLength: 40
         maxLength: 40
         pattern: "[a-f0-9]{40}"
       md5:
         type: "string"
         example: "1b39813549077b2347c0f370c3864b40"
+        description: "MD5 hash of data, in hex encoding"
         minLength: 32
         maxLength: 32
         pattern: "[a-f0-9]{32}"
@@ -7442,10 +7781,15 @@ definitions:
         type: "integer"
         format: "int64"
         example: 1048576
+        description: "Size of file in bytes. Non-zero."
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       redirect:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7469,6 +7813,7 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7484,14 +7829,14 @@ definitions:
       revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
       sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
       urls:
-      - rel: "webarchive"
+      - rel: "web"
         url: "https://example.edu/~frau/prcding.pdf"
-      - rel: "webarchive"
+      - rel: "web"
         url: "https://example.edu/~frau/prcding.pdf"
       size: 1048576
       extra: "{}"
       mimetype: "application/pdf"
-      state: "wip"
+      state: "active"
       release_ids:
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7508,11 +7853,15 @@ definitions:
         type: "string"
         format: "url"
         example: "https://example.edu/~frau/prcding.pdf"
+        description: "URL/URI pointing directly to a machine retrievable copy of this\
+          \ exact\nfile.\n"
       rel:
         type: "string"
-        example: "webarchive"
+        example: "web"
+        description: "Indicates type of host this URL points to. Eg, \"publisher\"\
+          ,\n\"repository\", \"webarchive\". See guide for list of acceptable values.\n"
     example:
-      rel: "webarchive"
+      rel: "web"
       url: "https://example.edu/~frau/prcding.pdf"
     upperCaseName: "FILE_URL"
   fileset_entity:
@@ -7520,11 +7869,14 @@ definitions:
     properties:
       releases:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Full release entities, included in GET responses when `releases`\n\
+          included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
         items:
           $ref: "#/definitions/release_entity"
       release_ids:
         type: "array"
+        description: "Set of identifier of release entities this fileset represents\
+          \ a full\nmanifestation of. Usually a single release.\n"
         items:
           type: "string"
           example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7542,6 +7894,7 @@ definitions:
           $ref: "#/definitions/fileset_file"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7570,8 +7923,12 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
     example:
       redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
       urls:
@@ -7594,7 +7951,7 @@ definitions:
         md5: "1b39813549077b2347c0f370c3864b40"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
       extra: "{}"
-      state: "wip"
+      state: "active"
       release_ids:
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7617,6 +7974,8 @@ definitions:
       rel:
         type: "string"
         example: "webarchive"
+        description: "Indicates type of host this URL points to. See guide for list\
+          \ of\nacceptable values.\n"
     example:
       rel: "webarchive"
       url: "https://example.edu/~frau/prcding.pdf"
@@ -7630,30 +7989,38 @@ definitions:
       path:
         type: "string"
         example: "img/cat.png"
+        description: "Path name of file within this fileset (eg, directory)\n"
       size:
         type: "integer"
         format: "int64"
         example: 1048576
+        description: "File size in bytes"
       md5:
         type: "string"
         example: "1b39813549077b2347c0f370c3864b40"
+        description: "MD5 hash of data, in hex encoding"
         minLength: 32
         maxLength: 32
         pattern: "[a-f0-9]{32}"
       sha1:
         type: "string"
         example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+        description: "SHA-1 hash of data, in hex encoding"
         minLength: 40
         maxLength: 40
         pattern: "[a-f0-9]{40}"
       sha256:
         type: "string"
         example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+        description: "SHA-256 hash of data, in hex encoding"
         minLength: 64
         maxLength: 64
         pattern: "[a-f0-9]{64}"
       extra:
         type: "object"
+        description: "Free-form additional metadata about this specific file in the\
+          \ set.\nEg, `mimetype`. See guide for nomative (but unenforced) schema\n\
+          fields.\n"
     example:
       sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
       path: "img/cat.png"
@@ -7667,11 +8034,14 @@ definitions:
     properties:
       releases:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Full release entities, included in GET responses when `releases`\n\
+          included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
         items:
           $ref: "#/definitions/release_entity"
       release_ids:
         type: "array"
+        description: "Set of identifier of release entities this fileset represents\
+          \ a full\nmanifestation of. Usually a single release.\n"
         items:
           type: "string"
           example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7682,13 +8052,14 @@ definitions:
       timestamp:
         type: "string"
         format: "date-time"
-        description: "same format as CDX line timestamp (UTC, etc). Corresponds to\
-          \ the overall capture timestamp. Can be the earliest or average of CDX timestamps\
-          \ if that makes sense."
+        description: "Same format as CDX line timestamp (UTC, etc). Corresponds to\
+          \ the\noverall capture timestamp. Should generally be the timestamp of\n\
+          capture of the primary resource URL.\n"
       original_url:
         type: "string"
         format: "url"
         example: "http://asheesh.org"
+        description: "Base URL of the primary resource this is a capture of"
       archive_urls:
         type: "array"
         items:
@@ -7699,8 +8070,12 @@ definitions:
           $ref: "#/definitions/webcapture_cdx_line"
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       redirect:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7724,6 +8099,7 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7756,7 +8132,7 @@ definitions:
         timestamp: "2016-09-19T17:20:24Z"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
       extra: "{}"
-      state: "wip"
+      state: "active"
       release_ids:
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
       - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7778,34 +8154,45 @@ definitions:
       surt:
         type: "string"
         example: "org,asheesh)/apus/ch1/node15.html"
+        description: "\"Sortable URL\" format. See guide for details.\n"
       timestamp:
         type: "string"
         format: "date-time"
         example: "2016-09-19T17:20:24Z"
-        description: "UTC, 'Z'-terminated, second (or better) precision"
+        description: "Date and time of capture, in ISO format. UTC, 'Z'-terminated,\
+          \ second\n(or better) precision.\n"
       url:
         type: "string"
         example: "http://www.asheesh.org:80/APUS/ch1/node15.html"
+        description: "Full URL/URI of resource captured.\n"
       mimetype:
         type: "string"
         example: "text/html"
+        description: "Mimetype of the resource at this URL. May be the Content-Type\
+          \ header,\nor the actually sniffed file type.\n"
       status_code:
         type: "integer"
         format: "int64"
         example: 200
+        description: "HTTP status code. Should generally be 200, especially for the\
+          \ primary\nresource, but may be 3xx (redirect) or even error codes if embedded\n\
+          resources can not be fetched successfully.\n"
       size:
         type: "integer"
         format: "int64"
         example: 1048576
+        description: "Resource (file) size in bytes"
       sha1:
         type: "string"
         example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+        description: "SHA-1 hash of data, in hex encoding"
         minLength: 40
         maxLength: 40
         pattern: "[a-f0-9]{40}"
       sha256:
         type: "string"
         example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+        description: "SHA-256 hash of data, in hex encoding"
         minLength: 64
         maxLength: 64
         pattern: "[a-f0-9]{64}"
@@ -7829,9 +8216,13 @@ definitions:
         type: "string"
         format: "url"
         example: "https://web.archive.org/web/"
+        description: "URL/URI pointing to archive of this web resource.\n"
       rel:
         type: "string"
         example: "wayback"
+        description: "Type of archive endpoint. Usually `wayback` (WBM replay of primary\n\
+          resource), or `warc` (direct URL to a WARC file containing all\nresources\
+          \ of the capture). See guide for full list.\n"
     example:
       rel: "wayback"
       url: "https://web.archive.org/web/"
@@ -7855,85 +8246,143 @@ definitions:
           $ref: "#/definitions/release_contrib"
       license_slug:
         type: "string"
-        description: "Short version of license name. Eg, 'CC-BY'"
+        example: "CC-BY"
+        description: "Short string (slug) name of license under which release is openly\n\
+          published (if applicable).\n"
       language:
         type: "string"
-        description: "Two-letter RFC1766/ISO639-1 language code, with extensions"
+        example: "en"
+        description: "Primary language of the content of the full release. Two-letter\n\
+          RFC1766/ISO639-1 language code, with some custom\nextensions/additions.\
+          \ See guide.\n"
       publisher:
         type: "string"
+        example: "Elsevier"
+        description: "Name, usually English, of the entity or institution responsible\
+          \ for\npublication of this release. Not necessarily the imprint/brand. See\n\
+          guide.\n"
       version:
         type: "string"
+        example: "3"
+        description: "For, eg, updated technical reports or software packages, where\n\
+          the version string may be the only field disambiguating between\nreleases.\n"
       number:
         type: "string"
+        example: "RFC1337"
+        description: "For, eg, technical reports, which are published in series or\n\
+          assigned some other institutional or container-specific identifier.\n"
       pages:
         type: "string"
+        example: "340-345"
+        description: "Either a single page number (\"first page\") or a range of pages\n\
+          separated by a dash (\"-\"). See guide for details.\n"
       issue:
         type: "string"
         example: "12"
+        description: "Issue number of volume/container that this release was published\
+          \ in.\nSometimes coresponds to a month number in the year, but can be any\n\
+          string. See guide.\n"
       volume:
         type: "string"
+        example: "3"
+        description: "Volume number of container that this release was published in.\
+          \ Often\ncorresponds to the \"Nth\" year of publication, but can be any\
+          \ string.\nSee guide.\n"
       ext_ids:
+        description: "Set of external identifiers for this release.\n"
         $ref: "#/definitions/release_ext_ids"
       withdrawn_year:
         type: "integer"
         format: "int64"
         example: 2014
+        description: "Year corresponding with `withdrawn_date` like\n`release_year`/`release_date`.\n"
       withdrawn_date:
         type: "string"
         format: "date"
+        description: "Full date when this release was formally withdrawn (if applicable).\n\
+          ISO format, like `release_date`.\n"
       withdrawn_status:
         type: "string"
+        example: "retracted"
+        description: "Type of withdrawl or retraction of this release, if applicable.\
+          \ If\nrelease has not been withdrawn, should be `null` (aka, not set, not\n\
+          the string \"null\" or an empty string).\n"
       release_year:
         type: "integer"
         format: "int64"
         example: 2014
+        description: "Year when this release was formally published. Must match\n\
+          `release_date` if that field is set; this field exists because\nsometimes\
+          \ only the year is known.\n"
       release_date:
         type: "string"
         format: "date"
+        description: "Full date when this release was formally published. ISO format,\
+          \ like\n`2019-03-05`. See guide for semantics.\n"
       release_stage:
         type: "string"
-        example: "preprint, retracted"
+        example: "preprint"
+        description: "The stage of publication of this specific release. See guide\
+          \ for\nvalid values and semantics.\n"
       release_type:
         type: "string"
         example: "book"
+        description: "\"Type\" or \"medium\" that this release is published as. See\
+          \ guide for\nvalid values.\n"
       container_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: "Used to link this release to a container entity that the release\
+          \ was\npublished as part of.\n"
       webcaptures:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Complete webcapture entities identified by `webcapture_ids`\
+          \ field.\nOnly included in GET responses when `webcaptures` included in\
+          \ `expand`\nparameter; ignored in PUT or POST requests.\n"
         items:
           $ref: "#/definitions/webcapture_entity"
       filesets:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Complete file entities identified by `filesets_ids` field. Only\n\
+          included in GET responses when `filesets` included in `expand`\nparameter;\
+          \ ignored in PUT or POST requests.\n"
         items:
           $ref: "#/definitions/fileset_entity"
       files:
         type: "array"
-        description: "Optional; GET-only"
+        description: "Complete file entities identified by `file_ids` field. Only\n\
+          included in GET responses when `files` included in `expand` parameter;\n\
+          ignored in PUT or POST requests.\n"
         items:
           $ref: "#/definitions/file_entity"
       container:
-        description: "Optional; GET-only"
+        description: "Complete container entity identified by `container_id` field.\
+          \ Only\nincluded in GET reponses when `container` included in `expand`\n\
+          parameter; ignored in PUT or POST requests.\n"
         $ref: "#/definitions/container_entity"
       work_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: "Identifier of work this release is part of. In creation (POST)\n\
+          requests, a work entity will be created automatically if this field\nis\
+          \ not set.\n"
       original_title:
         type: "string"
-        description: "Title in original language (or, the language of the full text\
-          \ of this release)"
+        description: "Title in original language if `title` field has been translated.\
+          \ See\nguide for details.\n"
       subtitle:
         type: "string"
-        description: "Avoid this field if possible, and merge with title; usually\
-          \ English"
+        description: "Subtitle of release. In many cases, better to merge with title\
+          \ than\ninclude as separate field (unless combined title would be very long).\n\
+          See guide for details.\n"
       title:
         type: "string"
         description: "Required for valid entities. The title used in citations and\
-          \ for display; usually English"
+          \ for\ndisplay. Sometimes the English translation of title e even if release\n\
+          content is not English.\n"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -7962,19 +8411,23 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
     example:
       container:
         redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
-        container_type: "container_type"
+        container_type: "journal"
         name: "Journal of Important Results"
         publisher: "Society of Curious Students"
         issnl: "1234-5678"
-        wikidata_qid: "wikidata_qid"
-        state: "wip"
+        wikidata_qid: "Q42812"
+        state: "active"
         edit_extra: "{}"
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
       webcaptures:
@@ -8004,7 +8457,7 @@ definitions:
           timestamp: "2016-09-19T17:20:24Z"
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8040,7 +8493,7 @@ definitions:
           timestamp: "2016-09-19T17:20:24Z"
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8051,8 +8504,8 @@ definitions:
         timestamp: "2000-01-23T04:56:07.000+00:00"
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
-      withdrawn_status: "withdrawn_status"
-      language: "language"
+      withdrawn_status: "retracted"
+      language: "en"
       title: "title"
       contribs:
       - raw_affiliation: "raw_affiliation"
@@ -8062,19 +8515,19 @@ definitions:
           ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
           extra: "{}"
           orcid: "0000-0002-1825-0097"
-          wikidata_qid: "wikidata_qid"
-          state: "wip"
+          wikidata_qid: "Q42812"
+          state: "active"
           given_name: "given_name"
           display_name: "Grace Hopper"
           edit_extra: "{}"
           revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-        raw_name: "raw_name"
-        role: "role"
-        surname: "surname"
+        raw_name: "Jane K. Doe"
+        role: "author"
+        surname: "Doe"
         extra: "{}"
         creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        index: 1
-        given_name: "given_name"
+        index: 0
+        given_name: "Jane"
       - raw_affiliation: "raw_affiliation"
         creator:
           redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8082,23 +8535,23 @@ definitions:
           ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
           extra: "{}"
           orcid: "0000-0002-1825-0097"
-          wikidata_qid: "wikidata_qid"
-          state: "wip"
+          wikidata_qid: "Q42812"
+          state: "active"
           given_name: "given_name"
           display_name: "Grace Hopper"
           edit_extra: "{}"
           revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-        raw_name: "raw_name"
-        role: "role"
-        surname: "surname"
+        raw_name: "Jane K. Doe"
+        role: "author"
+        surname: "Doe"
         extra: "{}"
         creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        index: 1
-        given_name: "given_name"
-      number: "number"
-      pages: "pages"
+        index: 0
+        given_name: "Jane"
+      number: "RFC1337"
+      pages: "340-345"
       extra: "{}"
-      state: "wip"
+      state: "active"
       edit_extra: "{}"
       withdrawn_year: 2014
       redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8116,43 +8569,43 @@ definitions:
         content: "<jats:p>Some abstract thing goes here</jats:p>"
       release_year: 2014
       release_type: "book"
-      version: "version"
+      version: "3"
       revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-      volume: "volume"
+      volume: "3"
       ext_ids:
         core: "core"
         mag: "mag"
         jstor: "jstor"
         isbn13: "isbn13"
         arxiv: "arxiv"
-        wikidata_qid: "wikidata_qid"
+        wikidata_qid: "Q42812"
         ark: "ark"
-        pmid: "pmid"
-        pmcid: "pmcid"
+        pmid: "482132"
+        pmcid: "PMC7391"
         doi: "10.1234/abcde.789"
-      release_stage: "preprint, retracted"
-      license_slug: "license_slug"
+      release_stage: "preprint"
+      license_slug: "CC-BY"
       withdrawn_date: "2000-01-23"
       refs:
       - target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
         container_name: "container_name"
-        year: 6
+        year: 1972
         extra: "{}"
         index: 0
         title: "title"
         locator: "p123"
-        key: "key"
+        key: "SMITH2016"
       - target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
         container_name: "container_name"
-        year: 6
+        year: 1972
         extra: "{}"
         index: 0
         title: "title"
         locator: "p123"
-        key: "key"
+        key: "SMITH2016"
       release_date: "2000-01-23"
       subtitle: "subtitle"
-      publisher: "publisher"
+      publisher: "Elsevier"
       files:
       - redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
         sha256: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
@@ -8163,14 +8616,14 @@ definitions:
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
         sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
         urls:
-        - rel: "webarchive"
+        - rel: "web"
           url: "https://example.edu/~frau/prcding.pdf"
-        - rel: "webarchive"
+        - rel: "web"
           url: "https://example.edu/~frau/prcding.pdf"
         size: 1048576
         extra: "{}"
         mimetype: "application/pdf"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8185,14 +8638,14 @@ definitions:
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
         sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
         urls:
-        - rel: "webarchive"
+        - rel: "web"
           url: "https://example.edu/~frau/prcding.pdf"
-        - rel: "webarchive"
+        - rel: "web"
           url: "https://example.edu/~frau/prcding.pdf"
         size: 1048576
         extra: "{}"
         mimetype: "application/pdf"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8220,7 +8673,7 @@ definitions:
           md5: "1b39813549077b2347c0f370c3864b40"
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8250,7 +8703,7 @@ definitions:
           md5: "1b39813549077b2347c0f370c3864b40"
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
-        state: "wip"
+        state: "active"
         release_ids:
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
         - "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8267,34 +8720,49 @@ definitions:
       doi:
         type: "string"
         example: "10.1234/abcde.789"
+        description: "Digital Object Identifier (DOI), mostly for published papers\
+          \ and\ndatasets. Should be registered and resolvable via https://doi.org/\n"
       wikidata_qid:
         type: "string"
+        example: "Q42812"
+        description: "Wikidata entity QID"
       isbn13:
         type: "string"
+        description: "ISBN-13, for books. Usually not set for chapters. ISBN-10 should\
+          \ be\nconverted to ISBN-13.\n"
       pmid:
         type: "string"
+        example: "482132"
+        description: "PubMed Identifier"
       pmcid:
         type: "string"
+        example: "PMC7391"
+        description: "PubMed Central Identifier"
       core:
         type: "string"
+        description: "CORE (https://core.ac.uk) identifier"
       arxiv:
         type: "string"
+        description: "arXiv (https://arxiv.org) identifier; must include version"
       jstor:
         type: "string"
+        description: "JSTOR work identifier"
       ark:
         type: "string"
+        description: "ARK identifier"
       mag:
         type: "string"
+        description: "Microsoft Academic Graph identifier"
     example:
       core: "core"
       mag: "mag"
       jstor: "jstor"
       isbn13: "isbn13"
       arxiv: "arxiv"
-      wikidata_qid: "wikidata_qid"
+      wikidata_qid: "Q42812"
       ark: "ark"
-      pmid: "pmid"
-      pmcid: "pmcid"
+      pmid: "482132"
+      pmcid: "PMC7391"
       doi: "10.1234/abcde.789"
     upperCaseName: "RELEASE_EXT_IDS"
   release_abstract:
@@ -8303,18 +8771,25 @@ definitions:
       sha1:
         type: "string"
         example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+        description: "SHA-1 hash of data, in hex encoding"
         minLength: 40
         maxLength: 40
         pattern: "[a-f0-9]{40}"
       content:
         type: "string"
         example: "<jats:p>Some abstract thing goes here</jats:p>"
+        description: "Abstract content. May be encoded, as per `mimetype` field, but\
+          \ only\nstring/text content may be included.\n"
       mimetype:
         type: "string"
         example: "application/xml+jats"
+        description: "Mimetype of abstract contents. `text/plain` is the default if\
+          \ content\nisn't encoded.\n"
       lang:
         type: "string"
         example: "en"
+        description: "ISO language code of the abstract. Same semantics as release\
+          \ `language` field.\n"
     example:
       sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
       mimetype: "application/xml+jats"
@@ -8326,8 +8801,12 @@ definitions:
     properties:
       edit_extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with specific entity\
+          \ edits\n(eg, creation/update/delete).\n"
       extra:
         type: "object"
+        description: "Free-form JSON metadata that will be stored with the other entity\n\
+          metadata. See guide for (unenforced) schema conventions.\n"
       redirect:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8351,6 +8830,7 @@ definitions:
         pattern: "[a-zA-Z2-7]{26}"
       state:
         type: "string"
+        example: "active"
         enum:
         - "wip"
         - "active"
@@ -8360,7 +8840,7 @@ definitions:
       redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
       ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
       extra: "{}"
-      state: "wip"
+      state: "active"
       edit_extra: "{}"
       revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
     upperCaseName: "WORK_ENTITY"
@@ -8380,10 +8860,10 @@ definitions:
     example:
       editgroup:
         editor:
-          is_admin: true
+          is_admin: false
           is_active: true
           editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-          is_bot: true
+          is_bot: false
           username: "zerocool93"
         changelog_index: 1048576
         submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8500,10 +8980,10 @@ definitions:
         annotations:
         - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
           editor:
-            is_admin: true
+            is_admin: false
             is_active: true
             editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-            is_bot: true
+            is_bot: false
             username: "zerocool93"
           created: "2000-01-23T04:56:07.000+00:00"
           extra: "{}"
@@ -8512,10 +8992,10 @@ definitions:
           comment_markdown: "comment_markdown"
         - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
           editor:
-            is_admin: true
+            is_admin: false
             is_active: true
             editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-            is_bot: true
+            is_bot: false
             username: "zerocool93"
           created: "2000-01-23T04:56:07.000+00:00"
           extra: "{}"
@@ -8534,10 +9014,10 @@ definitions:
       changelog_entry:
         editgroup:
           editor:
-            is_admin: true
+            is_admin: false
             is_active: true
             editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-            is_bot: true
+            is_bot: false
             username: "zerocool93"
           changelog_index: 1048576
           submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8654,10 +9134,10 @@ definitions:
           annotations:
           - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
             editor:
-              is_admin: true
+              is_admin: false
               is_active: true
               editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-              is_bot: true
+              is_bot: false
               username: "zerocool93"
             created: "2000-01-23T04:56:07.000+00:00"
             extra: "{}"
@@ -8666,10 +9146,10 @@ definitions:
             comment_markdown: "comment_markdown"
           - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
             editor:
-              is_admin: true
+              is_admin: false
               is_active: true
               editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-              is_bot: true
+              is_bot: false
               username: "zerocool93"
             created: "2000-01-23T04:56:07.000+00:00"
             extra: "{}"
@@ -8691,42 +9171,45 @@ definitions:
       edit_id:
         type: "string"
         example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-        description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+        description: "Unique UUID for this specific edit object.\n"
         minLength: 36
         maxLength: 36
         pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
       ident:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Fatcat identifier of the entity this edit is mutating.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       revision:
         type: "string"
         example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-        description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+        description: "Entity revision that this edit will set the entity to. May be\n\
+          `null` in the case of deletions.\n"
         minLength: 36
         maxLength: 36
         pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
       prev_revision:
         type: "string"
         example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-        description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+        description: "Revision of entity just before this edit. May be used in the\
+          \ future\nto prevent edit race conditions.\n"
         minLength: 36
         maxLength: 36
         pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
       redirect_ident:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "When an edit is to merge entities (redirect one to another),\
+          \ this\nis the entity fatcat identifier for the target entity.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       editgroup_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Editgroup identifier that this edit is part of.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
@@ -8749,24 +9232,35 @@ definitions:
       editor_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Fatcat identifier for the editor. Can not be changed.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       username:
         type: "string"
         example: "zerocool93"
+        description: "Username/handle (short slug-like string) to identify this editor.\
+          \ May\nbe changed at any time by the editor; use the `editor_id` as a\n\
+          persistend identifer.\n"
       is_admin:
         type: "boolean"
+        example: false
+        description: "Whether this editor has the `admin` role.\n"
       is_bot:
         type: "boolean"
+        example: false
+        description: "Whether this editor is a bot (as opposed to a human making manual\n\
+          edits)\n"
       is_active:
         type: "boolean"
+        example: true
+        description: "Whether this editor's account is enabled (if not API tokens\
+          \ and web\nlogins will not work).\n"
     example:
-      is_admin: true
+      is_admin: false
       is_active: true
       editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-      is_bot: true
+      is_bot: false
       username: "zerocool93"
     upperCaseName: "EDITOR"
   editgroup:
@@ -8775,45 +9269,60 @@ definitions:
       editgroup_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Fatcat identifier for this editgroup. Assigned on creation.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       editor_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Fatcat identifer of editor that created this editgroup.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       editor:
+        description: "Complete editor object identified by `container_id` field. Only\n\
+          included in GET responses.\n"
         $ref: "#/definitions/editor"
       changelog_index:
         type: "integer"
         format: "int64"
         example: 1048576
+        description: "For accepted/merged editgroups, the changelog index that the\
+          \ accept\noccured at. WARNING: not populated in all contexts that an editgroup\n\
+          could be included in a response.\n"
       created:
         type: "string"
         format: "date-time"
+        description: "Timestamp when this editgroup was first created.\n"
       submitted:
         type: "string"
         format: "date-time"
+        description: "Timestamp when this editgroup was most recently submitted for\
+          \ review.\nIf withdrawn, or never submitted, will be `null`.\n"
       description:
         type: "string"
+        description: "Comment describing the changes in this editgroup. Can be updated\
+          \ with\nPUT request.\n"
       extra:
         type: "object"
+        description: "Free-form JSON metadata attached to this editgroup. Eg, metadata\n\
+          provenance, or script user-agent details. See guide for (unenforced)\nschema\
+          \ norms.\n"
       annotations:
         type: "array"
+        description: "Only included in GET responses, and not in all contexts. Do\
+          \ not\ninclude this field in PUT or POST requests.\n"
         items:
           $ref: "#/definitions/editgroup_annotation"
       edits:
         $ref: "#/definitions/editgroup_edits"
     example:
       editor:
-        is_admin: true
+        is_admin: false
         is_active: true
         editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        is_bot: true
+        is_bot: false
         username: "zerocool93"
       changelog_index: 1048576
       submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8930,10 +9439,10 @@ definitions:
       annotations:
       - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
         editor:
-          is_admin: true
+          is_admin: false
           is_active: true
           editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-          is_bot: true
+          is_bot: false
           username: "zerocool93"
         created: "2000-01-23T04:56:07.000+00:00"
         extra: "{}"
@@ -8942,10 +9451,10 @@ definitions:
         comment_markdown: "comment_markdown"
       - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
         editor:
-          is_admin: true
+          is_admin: false
           is_active: true
           editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-          is_bot: true
+          is_bot: false
           username: "zerocool93"
         created: "2000-01-23T04:56:07.000+00:00"
         extra: "{}"
@@ -8967,33 +9476,39 @@ definitions:
       editgroup_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Editgroup that this annotation applies to. Set automatically\
+          \ in\ncreations based on URL parameter.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       editor_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Defaults to editor created the annotation via POST request.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       editor:
+        description: "Only included in GET responses; ignored in PUT or POST requests.\n"
         $ref: "#/definitions/editor"
       created:
         type: "string"
         format: "date-time"
+        description: "Timestamp when annotation was first created.\n"
       comment_markdown:
         type: "string"
       extra:
         type: "object"
+        description: "Additional free-form JSON metadata that can be included as part\
+          \ of\nthe annotation (or even as the primary annotation itself). See guide\n\
+          for details.\n"
     example:
       annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
       editor:
-        is_admin: true
+        is_admin: false
         is_active: true
         editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        is_bot: true
+        is_bot: false
         username: "zerocool93"
       created: "2000-01-23T04:56:07.000+00:00"
       extra: "{}"
@@ -9011,21 +9526,24 @@ definitions:
       index:
         type: "integer"
         format: "int64"
+        description: "Monotonically increasing sequence number of this changelog entry.\n"
       editgroup_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: "Identifier of editgroup accepted/merged in this changelog entry.\n"
       timestamp:
         type: "string"
         format: "date-time"
+        description: "Date and time when the editgroup was accpeted.\n"
       editgroup:
         $ref: "#/definitions/editgroup"
     example:
       editgroup:
         editor:
-          is_admin: true
+          is_admin: false
           is_active: true
           editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-          is_bot: true
+          is_bot: false
           username: "zerocool93"
         changelog_index: 1048576
         submitted: "2000-01-23T04:56:07.000+00:00"
@@ -9142,10 +9660,10 @@ definitions:
         annotations:
         - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
           editor:
-            is_admin: true
+            is_admin: false
             is_active: true
             editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-            is_bot: true
+            is_bot: false
             username: "zerocool93"
           created: "2000-01-23T04:56:07.000+00:00"
           extra: "{}"
@@ -9154,10 +9672,10 @@ definitions:
           comment_markdown: "comment_markdown"
         - annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
           editor:
-            is_admin: true
+            is_admin: false
             is_active: true
             editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-            is_bot: true
+            is_bot: false
             username: "zerocool93"
           created: "2000-01-23T04:56:07.000+00:00"
           extra: "{}"
@@ -9175,36 +9693,54 @@ definitions:
       index:
         type: "integer"
         format: "int64"
+        description: "Zero-indexed sequence number of this reference in the list of\n\
+          references. Assigned automatically and used internally; don't confuse\n\
+          with `key`.\n"
       target_release_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "Optional, fatcat identifier of release entity that this reference\
+          \ is\nciting.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       extra:
         type: "object"
+        description: "Additional free-form JSON metadata about this citation. Generally\n\
+          follows Citation Style Language (CSL) JSON schema. See guide for\ndetails.\n"
       key:
         type: "string"
+        example: "SMITH2016"
+        description: "Short string used to indicate this reference from within the\
+          \ release\ntext; or numbering of references as typeset in the release itself.\n\
+          Optional; don't confuse with `index` field.\n"
       year:
         type: "integer"
         format: "int64"
+        example: 1972
+        description: "Year that the cited work was published in.\n"
       container_name:
         type: "string"
+        description: "Name of the container (eg, journal) that the citation work was\n\
+          published as part of. May be an acronym or full name.\n"
       title:
         type: "string"
+        description: "Name of the work being cited."
       locator:
         type: "string"
         example: "p123"
+        description: "Page number or other indicator of the specific subset of a work\
+          \ being\ncited. Not to be confused with the first page (or page range) of\
+          \ an\nentire paper or chapter being cited.\n"
     example:
       target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
       container_name: "container_name"
-      year: 6
+      year: 1972
       extra: "{}"
       index: 0
       title: "title"
       locator: "p123"
-      key: "key"
+      key: "SMITH2016"
     upperCaseName: "RELEASE_REF"
   release_contrib:
     type: "object"
@@ -9212,29 +9748,47 @@ definitions:
       index:
         type: "integer"
         format: "int64"
+        example: 0
+        description: "Internally assigned zero-indexed sequence number of contribution.\n\
+          Authors should come first; this encodes the order of attriubtion.\n"
       creator_id:
         type: "string"
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        description: "base32-encoded unique identifier"
+        description: "If known, indicates the creator entity this contribution was\
+          \ made by.\n"
         minLength: 26
         maxLength: 26
         pattern: "[a-zA-Z2-7]{26}"
       creator:
-        description: "Optional; GET-only"
+        description: "Complete creator entity. Only returned in GET responses, and\
+          \ only if\n`contribs` included in the `expand` query parameter.\n"
         $ref: "#/definitions/creator_entity"
       raw_name:
         type: "string"
+        example: "Jane K. Doe"
+        description: "Full name of the contributor as typeset in the release.\n"
       given_name:
         type: "string"
+        example: "Jane"
+        description: "In English commonly the first name, but ordering is context\
+          \ and\nculture specific.\n"
       surname:
         type: "string"
+        example: "Doe"
+        description: "In English commonly the last, or family name, but ordering is\
+          \ context\nand culture specific.\n"
       role:
         type: "string"
+        example: "author"
+        description: "Short string (slug) indicating type of contribution (eg, \"\
+          author\",\n\"translator\"). See guide for list of accpeted values.\n"
       raw_affiliation:
         type: "string"
         description: "Raw affiliation string as displayed in text"
       extra:
         type: "object"
+        description: "Additional free-form JSON metadata about this\ncontributor/contribution.\
+          \ See guide for normative schema.\n"
     example:
       raw_affiliation: "raw_affiliation"
       creator:
@@ -9243,19 +9797,19 @@ definitions:
         ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
         extra: "{}"
         orcid: "0000-0002-1825-0097"
-        wikidata_qid: "wikidata_qid"
-        state: "wip"
+        wikidata_qid: "Q42812"
+        state: "active"
         given_name: "given_name"
         display_name: "Grace Hopper"
         edit_extra: "{}"
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
-      raw_name: "raw_name"
-      role: "role"
-      surname: "surname"
+      raw_name: "Jane K. Doe"
+      role: "author"
+      surname: "Doe"
       extra: "{}"
       creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-      index: 1
-      given_name: "given_name"
+      index: 0
+      given_name: "Jane"
     upperCaseName: "RELEASE_CONTRIB"
   container_auto_batch:
     type: "object"
@@ -9358,12 +9912,24 @@ definitions:
     properties:
       provider:
         type: "string"
+        example: "orcid"
+        description: "Fatcat-specific short name (slug) for remote service being used\
+          \ for\nauthentication.\n"
       sub:
         type: "string"
+        example: "https://orcid.org"
+        description: "`SUB` from OIDC protocol. Usually a URL."
       iss:
         type: "string"
+        example: "0000-0002-8593-9468"
+        description: "`ISS` from OIDC protocol. Usually a stable account username,\
+          \ number, or identifier."
       preferred_username:
         type: "string"
+        example: "bnewbold"
+        description: "What it sounds like; returned by OIDC, and used as a hint when\n\
+          creating new editor accounts. Fatcat usernames are usually this\nstring\
+          \ with the `provider` slug as a suffix, though some munging may\noccur.\n"
     upperCaseName: "AUTH_OIDC"
   auth_oidc_result:
     type: "object"
@@ -9375,14 +9941,15 @@ definitions:
         $ref: "#/definitions/editor"
       token:
         type: "string"
+        example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
     example:
       editor:
-        is_admin: true
+        is_admin: false
         is_active: true
         editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
-        is_bot: true
+        is_bot: false
         username: "zerocool93"
-      token: "token"
+      token: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
     upperCaseName: "AUTH_OIDC_RESULT"
   editgroup_edits:
     properties:
@@ -9414,6 +9981,8 @@ definitions:
         type: "array"
         items:
           $ref: "#/definitions/entity_edit"
+    description: "Only included in GET responses, and not in all contexts. Do not\n\
+      include this field in PUT or POST requests.\n"
     example:
       works:
       - ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -9521,50 +10090,84 @@ definitions:
         prev_revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
         revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
     upperCaseName: "EDITGROUP_EDITS"
+x-servers:
+- url: "https://api.fatcat.wiki/v0"
+  description: "Production Server"
+- url: "https://api.qa.fatcat.wiki/v0"
+  description: "QA Server"
+x-tagGroups:
+- name: "Entities"
+  tags:
+  - "containers"
+  - "creators"
+  - "files"
+  - "filesets"
+  - "webcaptures"
+  - "releases"
+  - "works"
+- name: "Editing"
+  tags:
+  - "editors"
+  - "editgroups"
+  - "changelog"
+- name: "Other"
+  tags:
+  - "auth"
 x-fatcat-ident:
   type: "string"
-  example: "q3nouwy3nnbsvo3h5klxsx4a7y"
   pattern: "[a-zA-Z2-7]{26}"
   minLength: 26
   maxLength: 26
   description: "base32-encoded unique identifier"
+x-fatcat-ident-example:
+  example: "q3nouwy3nnbsvo3h5klxsx4a7y"
 x-fatcat-uuid:
   type: "string"
-  example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
   pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
   minLength: 36
   maxLength: 36
   description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+x-fatcat-uuid-example:
+  example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
 x-issn:
   type: "string"
-  example: "1234-5678"
   pattern: "\\d{4}-\\d{3}[0-9X]"
   minLength: 9
   maxLength: 9
+x-issn-example:
+  example: "1234-5678"
 x-orcid:
   type: "string"
-  example: "0000-0002-1825-0097"
   pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
   minLength: 19
   maxLength: 19
+  description: "ORCiD (https://orcid.org) identifier"
+x-orcid-example:
+  example: "0000-0002-1825-0097"
 x-md5:
   type: "string"
-  example: "1b39813549077b2347c0f370c3864b40"
   pattern: "[a-f0-9]{32}"
   minLength: 32
   maxLength: 32
+  description: "MD5 hash of data, in hex encoding"
+x-md5-example:
+  example: "1b39813549077b2347c0f370c3864b40"
 x-sha1:
   type: "string"
-  example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
   pattern: "[a-f0-9]{40}"
   minLength: 40
   maxLength: 40
+  description: "SHA-1 hash of data, in hex encoding"
+x-sha1-example:
+  example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
 x-sha256:
   type: "string"
-  example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
   pattern: "[a-f0-9]{64}"
   minLength: 64
   maxLength: 64
+  description: "SHA-256 hash of data, in hex encoding"
+x-sha256-example:
+  example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
 x-entity-props:
   state:
     type: "string"
@@ -9573,32 +10176,37 @@ x-entity-props:
     - "active"
     - "redirect"
     - "deleted"
+    example: "active"
   ident:
+    example: "q3nouwy3nnbsvo3h5klxsx4a7y"
     description: "base32-encoded unique identifier"
     maxLength: 26
     minLength: 26
     pattern: "[a-zA-Z2-7]{26}"
-    example: "q3nouwy3nnbsvo3h5klxsx4a7y"
     type: "string"
   revision:
+    example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
     description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
     maxLength: 36
     minLength: 36
     pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
-    example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
     type: "string"
   redirect:
-    type: "string"
     example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+    type: "string"
     pattern: "[a-zA-Z2-7]{26}"
     minLength: 26
     maxLength: 26
     description: "base32-encoded unique identifier"
   extra:
     type: "object"
+    description: "Free-form JSON metadata that will be stored with the other entity\n\
+      metadata. See guide for (unenforced) schema conventions.\n"
     additionalProperties: {}
   edit_extra:
     type: "object"
+    description: "Free-form JSON metadata that will be stored with specific entity\
+      \ edits\n(eg, creation/update/delete).\n"
     additionalProperties: {}
 x-auth-responses:
   401: