Preprint ids in ArticleIdentifiers and publication_status in header and storage (preprint-ids decision 4)

README.md

@@ -181,6 +181,11 @@ What each side may rely on:
 
 - **One shape for every source.** PMC, Europe PMC, pubget, Elsevier, ACE and PDF all emit
   a `ParsedPaper`, so a consumer never branches on where a paper came from.
+- **A preprint is not its version of record.** The header's `doi`, `pmid` and `pmcid` name
+  the version of record. A preprint server's DOIs, each with its `PreprintServer`, and
+  PubMed's and PMC's records of the preprint are kept beside them in `preprint_dois`,
+  `preprint_pmid` and `preprint_pmcid`. `publication_status` states which the paper has
+  (`published` or `preprint`), and pondie copies it to `Study.publication_status`.
 - **Bibliography is copied, never extracted.** pondie fills the record's `Study.title`,
   `authors`, `doi`, `journal`, `publication_year`, `language` and `study_type` from
   `ParsedPaper.bibliography` and the header's identifiers (`transform: copy` in
@@ -320,7 +325,10 @@ so ingestion, pondie and neurostore read "Talairach & Tournoux 1988" the same wa
 **Examples.** `examples/` holds one paper and one run: a table whose ingestion parse is a
 single mixed-sign analysis, and pondie's revision that splits it by sign and adds the null
 result the text states. The tests read them through every model, JSON Schema and layout, and
-the checks must find nothing wrong with them.
+the checks must find nothing wrong with them. `examples/identifiers/` holds header
+identifiers for a preprint-only paper and for a published paper with a preprint DOI, and
+under `invalid/` two the models refuse: one without `publication_status`, one with a preprint
+DOI that names no server.
 
 **Storing coordinates.** The models say what a parse means, not how a corpus of them is
 kept. `study_schema.parquet` stores coordinate parses as three Parquet tables -- `parses`,

examples/corpus/x7Ex4mpleA01/parse/coordinate_parse.json

@@ -1,12 +1,16 @@
 {
   "header": {
     "artifact_kind": "coordinate_parse",
-    "schema_version": "0.6.0",
+    "schema_version": "0.7.0",
     "article_id": "art-000001",
     "identifiers": {
       "pmid": "00000000",
       "pmcid": null,
       "doi": null,
+      "preprint_dois": null,
+      "preprint_pmid": null,
+      "preprint_pmcid": null,
+      "publication_status": "published",
       "neurostore_base_study_id": "x7Ex4mpleA01"
     },
     "producer": {

examples/corpus/x7Ex4mpleA01/parse/parsed_paper.json

@@ -1,12 +1,16 @@
 {
   "header": {
     "artifact_kind": "parsed_paper",
-    "schema_version": "0.6.0",
+    "schema_version": "0.7.0",
     "article_id": "art-000001",
     "identifiers": {
       "pmid": "00000000",
       "pmcid": null,
       "doi": null,
+      "preprint_dois": null,
+      "preprint_pmid": null,
+      "preprint_pmcid": null,
+      "publication_status": "published",
       "neurostore_base_study_id": "x7Ex4mpleA01"
     },
     "producer": {

examples/identifiers/invalid/missing_publication_status.json

@@ -0,0 +1,14 @@
+{
+  "pmid": "31863619",
+  "pmcid": null,
+  "doi": "10.1111/desc.12933",
+  "preprint_dois": [
+    {
+      "doi": "10.31234/osf.io/5m87x",
+      "server": "psyarxiv"
+    }
+  ],
+  "preprint_pmid": null,
+  "preprint_pmcid": null,
+  "neurostore_base_study_id": null
+}

examples/identifiers/invalid/preprint_doi_without_server.json

@@ -0,0 +1,14 @@
+{
+  "pmid": "31863619",
+  "pmcid": null,
+  "doi": "10.1111/desc.12933",
+  "preprint_dois": [
+    {
+      "doi": "10.31234/osf.io/5m87x"
+    }
+  ],
+  "preprint_pmid": null,
+  "preprint_pmcid": null,
+  "publication_status": "published",
+  "neurostore_base_study_id": null
+}

examples/identifiers/preprint_only.json

@@ -0,0 +1,15 @@
+{
+  "pmid": null,
+  "pmcid": null,
+  "doi": null,
+  "preprint_dois": [
+    {
+      "doi": "10.1101/2025.05.13.653896",
+      "server": "biorxiv"
+    }
+  ],
+  "preprint_pmid": "40462995",
+  "preprint_pmcid": "PMC12132522",
+  "publication_status": "preprint",
+  "neurostore_base_study_id": null
+}

examples/identifiers/published_with_preprint.json

@@ -0,0 +1,15 @@
+{
+  "pmid": "31863619",
+  "pmcid": null,
+  "doi": "10.1111/desc.12933",
+  "preprint_dois": [
+    {
+      "doi": "10.31234/osf.io/5m87x",
+      "server": "psyarxiv"
+    }
+  ],
+  "preprint_pmid": null,
+  "preprint_pmcid": null,
+  "publication_status": "published",
+  "neurostore_base_study_id": null
+}

examples/run/revisions/x7Ex4mpleA01.coordinate_parse.json

@@ -1,12 +1,16 @@
 {
   "header": {
     "artifact_kind": "coordinate_parse",
-    "schema_version": "0.6.0",
+    "schema_version": "0.7.0",
     "article_id": "art-000001",
     "identifiers": {
       "pmid": "00000000",
       "pmcid": null,
       "doi": null,
+      "preprint_dois": null,
+      "preprint_pmid": null,
+      "preprint_pmcid": null,
+      "publication_status": "published",
       "neurostore_base_study_id": "x7Ex4mpleA01"
     },
     "producer": {

src/study_schema/jsonschema/coordinate-parse.schema.json

@@ -93,9 +93,10 @@
     },
     "ArticleIdentifiers": {
       "additionalProperties": false,
-      "description": "Every identifier known for the paper when the artifact was written. Carried whole, so no consumer has to choose between them or look one up.",
+      "description": "Every identifier known for the paper when the artifact was written. Carried whole, so no consumer has to choose between them or look one up. `doi`, `pmid` and `pmcid` name the version of record; a preprint's identifiers are kept beside them in the `preprint_` fields, so a paper and its preprint are one article.",
       "properties": {
         "doi": {
+          "description": "The DOI of the version of record. Never a preprint server's DOI, which is in `preprint_dois`.",
           "type": [
             "string",
             "null"
@@ -109,18 +110,51 @@
           ]
         },
         "pmcid": {
+          "description": "PubMed Central's copy of the version of record. Never PMC's copy of a preprint, which is `preprint_pmcid`.",
           "type": [
             "string",
             "null"
           ]
         },
         "pmid": {
+          "description": "PubMed's record of the version of record. Never PubMed's record of a preprint, which is `preprint_pmid`.",
           "type": [
             "string",
             "null"
           ]
+        },
+        "preprint_dois": {
+          "description": "Every DOI a preprint server registered for the paper. A server that registers each version separately, such as Research Square's `/v2`, gives one entry per version, each kept as registered.",
+          "items": {
+            "$ref": "#/$defs/PreprintDoi"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
+        "preprint_pmcid": {
+          "description": "PubMed Central's copy of the preprint.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "preprint_pmid": {
+          "description": "PubMed's record of the preprint, which PubMed types `Preprint`.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "publication_status": {
+          "$ref": "#/$defs/PublicationStatus",
+          "description": "`preprint` when a `preprint_` field is set and `doi`, `pmid` and `pmcid` are all empty, `published` otherwise. The producer states it so that no consumer re-derives it."
         }
       },
+      "required": [
+        "publication_status"
+      ],
       "title": "ArticleIdentifiers",
       "type": "object"
     },
@@ -1430,6 +1464,63 @@
       "title": "PolaritySemantics",
       "type": "string"
     },
+    "PreprintDoi": {
+      "additionalProperties": false,
+      "description": "A DOI a preprint server registered, with the server that registered it.",
+      "properties": {
+        "doi": {
+          "type": "string"
+        },
+        "server": {
+          "$ref": "#/$defs/PreprintServer",
+          "description": "Named by the producer from the DOI, so that no consumer needs a table of preprint servers' DOI patterns."
+        }
+      },
+      "required": [
+        "doi",
+        "server"
+      ],
+      "title": "PreprintDoi",
+      "type": "object"
+    },
+    "PreprintServer": {
+      "description": "The preprint server that registered a DOI. A server hosted on the Open Science Framework is named by its provider, which has a DOI prefix of its own. A server is added here when a producer learns to recognise its DOIs.",
+      "enum": [
+        "biorxiv",
+        "medrxiv",
+        "arxiv",
+        "researchsquare",
+        "osf_preprints",
+        "arabixiv",
+        "metaarxiv",
+        "engrxiv",
+        "focus_archive",
+        "frenxiv",
+        "ina_rxiv",
+        "lawarxiv",
+        "lis_scholarship_archive",
+        "marxiv",
+        "mindrxiv",
+        "nutrixiv",
+        "paleorxiv",
+        "psyarxiv",
+        "socarxiv",
+        "sportrxiv",
+        "africarxiv",
+        "mediarxiv",
+        "bodoarxiv",
+        "edarxiv",
+        "biohackrxiv",
+        "ssrn",
+        "preprints_org",
+        "authorea",
+        "techrxiv",
+        "chemrxiv",
+        "jmir_preprints"
+      ],
+      "title": "PreprintServer",
+      "type": "string"
+    },
     "Prespecification": {
       "description": "Whether a contrast was planned before the data were seen. A preregistered primary contrast and a post-hoc sweep from the same paper are not equivalent evidence, and a synthesis that cannot tell them apart cannot address selective reporting.",
       "enum": [
@@ -1479,6 +1570,15 @@
       "title": "Producer",
       "type": "object"
     },
+    "PublicationStatus": {
+      "description": "Whether a paper's version of record is known, or only its preprint.",
+      "enum": [
+        "published",
+        "preprint"
+      ],
+      "title": "PublicationStatus",
+      "type": "string"
+    },
     "Reference": {
       "additionalProperties": false,
       "description": "One entry of a paper's reference list.",
@@ -2192,5 +2292,5 @@
   ],
   "title": "neuroimaging-paper-parse",
   "type": "object",
-  "version": "0.6.0"
+  "version": "0.7.0"
 }