git.iko.soy/typeable/pandoc
on 2.14 help sign in
typeable/pandoc/doc/jats.md
414 lines 18 kB history raw
1---
2title: JATS
3author: Albert Krewinkel
4---
6This document describes pandoc's handling of JATS.
8Metadata Values
9===============
11`abstract`
12: Article summary. Added via the document's front matter via the
13 [`<abstract>`][elem:abstract] element.
15`author`
16: list of article contributors. Each author should have a surname
17 and a given name listed in the entry; if the author has no
18 `surname` value, then the item will be used as the contributors
19 [`string-name`][elem:string-name].
21 `orcid`
22 : the contributor's ORCID identifier.
24 `surname`
25 : surname of the contributor. Usually the family name in
26 western names.
28 See [`<surname>`][elem:surname].
30 `given-names`
31 : personal names of the contributor; this includes middle
32 names (if any) in western-style names.
34 See [`<given-names>`][elem:given-names].
36 `name`
37 : full name of the author; included only as a fallback if
38 `author.surname` is not available. Tagged with
39 [`<string-name>`][elem:string-name].
41 `email`
42 : the contributor's email address.
44 Used as the contents of the [`<email>`][elem:given-names]
45 element.
47 `affiliation`
48 : list of affiliation identifiers; marks the organizations
49 with which an author is affiliated. Each identifier in this
50 list must also occur as the `id` of an affiliation listed in
51 the top-level `affiliation` list.
53 `equal-contrib`
54 : boolean attribute used to mark authors who contributed
55 equally to the work. The
56 [`equal-contrib`][attr:equal-contrib] attribute is added
57 to the author's [`<contrib>`] element if this is set to a
58 truthy value.
60 `cor-id`
61 : identifier linking to the contributor's correspondence
62 information. The info itself must be stored in as an item in
63 `article.author-notes.corresp`. If the `cor-id` value is
64 then, an [`<xref>`][elem:xref] link of
65 [`ref-type`][attr:ref-type] `corresp` is added. The
66 [`rid`][attr:rid] attribute is set to `cor-<ID>`, where
67 `<ID>` is the stringified value of this attribute.
69`affiliation`
70: the list of organizations with which contributors are
71 affiliated. Each institution is added as an [`<aff>`] element to
72 the author's contrib-group.
74 The fields are given in the order in which they are included in
75 the output.
77 `id`
78 : internal identifier; used as the [`<aff>`] element's `id`
79 value, prefixed with `aff-`.
81 `group`
82 : name of the research group or other low-level organizational
83 structure; used as value of an [`<institution>`] element with
84 [`content-type`][attr:content-type] set to `group`.
86 `department`
87 : name of the department or other mid-level organizational
88 structure; used as value of an [`<institution>`] element with
89 [`content-type`][attr:content-type] set to `dept`.
91 `organization`
92 : name of the company, university, or other top-level
93 organizational structure; used as value of an
94 [`<institution>`] element. The institution element is wrapped
95 in an [`<institution-wrap>`] element; any identifiers, like
96 `ringgold` or `ror`, are added to the wrapper and must hence
97 belong to this organization (not the department or group).
99 `isni`
100 : International Standard Name Identifier of the organization.
101 Added via an [`<institution-id>`] element with
102 [`institution-id-type`](attr:institution-id-type) set to
103 `ISNI`.
105 `ringgold`
106 : [Ringgold] identifier of the organization. Added via an
107 [`<institution-id>`] element with
108 [`institution-id-type`](attr:institution-id-type) set to
109 `Ringgold`.
111 `ror`
112 : Research Organization Registry identifier of the
113 organization. Added via an [`<institution-id>`] element with
114 [`institution-id-type`](attr:institution-id-type) set to
115 `ROR`.
117 `pid`
118 : Array of persistent identifiers which are added as
119 [`<institution-id>`] elements. Each item must contain a map
120 with keys `type`, used as
121 [`institution-id-type`](attr:institution-id-type), and `id`,
122 used as element content.
124 `street-address`
125 : The organization's street address; each list item is wrapped
126 in an [`<addr-line>`] element, separated by a comma and
127 space (`, `).
129 `city`
130 : City in which the organization is located; used only if
131 `street-address` is not given, in which case the value is
132 wrapped in a [`<city>`] element.
134 `country`
135 : Country in which the organization is located; used as the
136 value of a [`<country>`] element.
138 `country-code`
139 : Two letter ISO-3166-1 country identifier; used as the
140 [`country`][attr:country] attribute in element [`<country>`]
141 (if the latter is present).
143`copyright`
144: Licensing and copyright information. This information is
145 rendered via the [`<permissions>`][elem:permissions] element.
147 The variables `type`, `link`, and `text` should always be used
148 together.
150 `statement`
151 : the year of copyright; used as content of the
152 [`<copyright-statement>`][elem:copyright-statement]
154 `year`
155 : the year of copyright; used as content of the
156 [`<copyright-year>`][elem:copyright-year]
158 `holder`
159 : the copyright holder; included via the
160 [`<copyright-holder>`][elem:copyright-holder] element.
162 `text`
163 : inline text setting the license under which the text is
164 published; included via the
165 [`<license-p>`][elem:copyright-holder] element.
167 `type`
168 : type of the license; used as value of the
169 [`license-type`][attr:license-type] attribute.
171 `link`
172 : external link describing the license; used as value of a
173 `xlink:href` attribute in the `<license>` element.
175`date`
176: publication date. This value should usually be a string
177 representation of a date. Pandoc will parse and deconstruct the
178 date into the components given below. It is also possible to
179 pass these components directly.
181 The publication date is recorded in the document via the
182 [`<pub-date>`] element and its sub-elements. The
183 [`publication-format`][attr:publication-format] attribute is
184 always set to `electronic`.
186 `iso-8601`
187 : ISO-8601 representation of the publication date. Used as the
188 value of the [`<pub-date>`] element's
189 [`iso-8601-date`][attr:iso-8601-date] attribute.
191 This value is set automatically if pandoc can parse the
192 `date` value as a date.
194 `day`, `month`, `year`
195 : Day, month, and year of the publication date. Only the
196 publication year is required. The values are used as the
197 contents of the elements with the respective names.
199 The values are set automatically if pandoc can parse the
200 `date` value as a date.
202 `type`
203 : The type of event marked by this date. The value is set as
204 the [`date-type`][attr:date-type] attribute on the
205 [`<pub-date>`] element and defaults to "pub" if not
206 specified.
208`article`
209: information concerning the article that identifies or describes
210 it. The key-value pairs within this map are typically used
211 within the [`<article-meta>`][elem:article-meta] element.
213 `publisher-id`
214 : external article identifier assigned by the publisher. Used
215 as the content of the [`<article-id>`][elem:article-id]
216 element with attribute [`pub-id-type`][attr:pub-id-type] set
217 to `publisher-id`.
219 `doi`
220 : Digital Object Identifier (DOI) assigned to the article.
221 Used as the content of the [`<article-id>`][elem:article-id]
222 element with attribute [`pub-id-type`][attr:pub-id-type] set
223 to `doi`.
225 `pmid`
226 : PubMed Identifier (PubMed ID) assigned to the article. Used
227 as the content of the [`<article-id>`][elem:article-id]
228 element with attribute [`pub-id-type`][attr:pub-id-type] set
229 to `pmid`.
231 `pmcid`
232 : PubMed Central Identifier assigned to the article. Used as
233 the content of the [`<article-id>`][elem:article-id] element
234 with attribute [`pub-id-type`][attr:pub-id-type] set to
235 `pmcid`.
237 `art-access-id`
238 : generic article accession identifier. Used as the content of
239 the [`<article-id>`][elem:article-id] element with attribute
240 [`pub-id-type`][attr:pub-id-type] set to `art-access-id`.
242 `heading`
243 : name of a subject or topic describing the article. Used as
244 the content of the [`<subject>`][elem:subject] element,
245 nested in a [`<subj-group>`][elem:subj-group] element which
246 has `heading` as its
247 [`subj-group-type`][attr:subj-group-type] attribute.
249 `categories`
250 : list a subject or topic describing the article. Items are
251 each used as the content a the [`<subject>`][elem:subject]
252 element, grouped in a single
253 [`<subj-group>`][elem:subj-group] element with its
254 [`subj-group-type`][attr:subj-group-type] attribute set to
255 `categories`.
257 `author-notes`
258 : Additional information about authors, like conflict of
259 interest statements and corresponding author contact info.
260 Wrapped in an [`<author-notes>`][elem:author-notes] element.
262 `conflict`
263 : Conflict of interest statement. Rendered as a footnote
264 ([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type)
265 `conflict`.
267 `con`
268 : Contributed-by information. Rendered as a footnote
269 ([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type) `con`.
271 `corresp`
272 : Correspondence information. This must be a list of
273 contributor correspondence items, where each item must
274 have the properties `id` and `email`. The info is then
275 rendered via a [`<corresp>`][elem:corresp] element.
277 `funding-statement`
278 : Prose describing the funding. Added to the article's
279 frontmatter via the
280 [`funding-statement`][elem:funding-statement] element.
282`journal`
283: information on the journal in which the article is published.
284 This must be a map; the following key/value pairs are
285 recognized.
287 `publisher-id`
288 : journal identifier assigned by the publisher. Used as
289 content of element [`<journal-id>`][elem:journal-id] with
290 attribute [`journal-id-type`][attr:journal-id-type] set to
291 `publisher-id`.
293 `nlm-ta`
294 : journal identifier assigned by PubMed. Used as content of
295 element [`<journal-id>`][elem:journal-id] with attribute
296 [`journal-id-type`][attr:journal-id-type] set to `nlm-ta`.
298 `pmc`
299 : journal identifier assigned by PubMed Central. Used as
300 content of element [`<journal-id>`][elem:journal-id] with
301 attribute [`journal-id-type`][attr:journal-id-type] set to
302 `pmc`.
304 `title`
305 : full title of the journal in which the article is published.
306 Used as content of the
307 [`<journal-title>`][elem:journal-title] element.
309 `abbrev-title`
310 : short form of the journal title. Used as content of the
311 [`<abbrev-journal-title>`][elem:abbrev-journal-title]
312 element.
314 `pissn`
315 : ISSN identifier of the publication's print version. Used as
316 content of the [`<issn>`][elem:issn] element with the
317 [`publication-format`][attr:publication-format] attribute
318 set to `print`.
320 `eissn`
321 : ISSN identifier of the publication's electronic version.
322 Used as content of the [`<issn>`][elem:issn] element with
323 the [`publication-format`][attr:publication-format]
324 attribute set to `electronic`.
326 `publisher-name`
327 : name of the publishing entity (person, company, or other).
328 Used as the content of the
329 [`<publisher-name>`][elem:publisher-name] element.
331 `publisher-loc`
332 : place of publication. Used as the content of the
333 [`<publisher-loc>`][elem:publisher-loc] element.
335`notes`
336: Additional notes concerning the whole article. Added to the
337 article's frontmatter via the [`<notes>`][elem:notes] element.
339`tags`
340: list of keywords. Items are used as contents of the
341 [`<kwd>`][elem:kwd] element; the elements are grouped in a
342 [`<kwd-group>`][elem:kwd-group] with the
343 [`kwd-group-type`][attr:kwd-group-type] value `author`.
345Required Metadata
346-----------------
348Pandoc will try to generate a valid JATS document even when
349information is missing, filling in placeholders or using empty
350values. This circumvents the intend to ensure a minimum set of
351information being present in documents of a certain tag set. It is
352hence recommended to always provide the information listed below.
354### Publishing Tag Set
356Required metadata values:
358- One or more of `journal.publisher-id`, `journal.nlm-ta`,
359 `journal.pmc`.
360- One or more of `journal.pissn`, `journal.eissn`.
362[Ringgold]: https://ringgold.com/
363[attr:content-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/content-type.html
364[attr:date-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/date-type.html
365[attr:equal-contrib]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/equal-contrib.html
366[attr:fn-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/fn-type.html
367[attr:institution-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/institution-id-type.html
368[attr:iso-8601-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/iso-8601-date.html
369[attr:journal-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/journal-id-type.html
370[attr:kwd-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/kwd-group-type.html
371[attr:license-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/license-type.html
372[attr:pub-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-id-type.html
373[attr:publication-format]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/publication-format.html
374[attr:ref-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/ref-type.html
375[attr:rid]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/rid.html
376[attr:subj-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/subj-group-type.html
377[elem:abbrev-journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abbrev-journal-title.html
378[elem:abstract]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abstract.html
379[elem:article-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-id.html
380[elem:article-meta]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-meta.html
381[elem:copyright-holder]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-holder.html
382[elem:copyright-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-statement.html
383[elem:copyright-year]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-year.html
384[elem:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/corresp.html
385[elem:email]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/email.html
386[elem:fn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html
387[elem:funding-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/funding-statement.html
388[elem:given-names]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/given-names.html
389[elem:issn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/issn.html
390[elem:journal-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-id.html
391[elem:journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-title.html
392[elem:kwd-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd-group.html
393[elem:kwd]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd.html
394[elem:license-p]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license-p.html
395[elem:license]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license.html
396[elem:notes]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/notes.html
397[elem:permissions]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/permissions.html
398[elem:publisher-loc]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-loc.html
399[elem:publisher-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-name.html
400[elem:string-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/string-name.html
401[elem:subj-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subj-group.html
402[elem:subject]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subject.html
403[elem:surname]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/surname.html
404[elem:xref]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/xref.html
406[`<addr-line>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/addr-line.html
407[`<aff>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/aff.html
408[`<city>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/city.html
409[`<contrib>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/contrib.html
410[`<country>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/country.html
411[`<institution-id>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-id.html
412[`<institution-wrap>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html
413[`<institution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html
414[`<pub-date>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html