.. _reference.json#/:

reference
=========

.. container:: title

 A reference to a cited document

This is structurally very similar to a Literature record, with unnecessary
fields removed.  For more information about the meaning of the different
fields, see the corresponding field in :ref:`hep.json#/`.

:type: ``object``

**Properties:** :ref:`reference.json#/properties/arxiv_eprint`, :ref:`reference.json#/properties/authors`, :ref:`reference.json#/properties/book_series`, :ref:`reference.json#/properties/collaborations`, :ref:`reference.json#/properties/document_type`, :ref:`reference.json#/properties/dois`, :ref:`reference.json#/properties/external_system_identifiers`, :ref:`reference.json#/properties/imprint`, :ref:`reference.json#/properties/isbn`, :ref:`reference.json#/properties/label`, :ref:`reference.json#/properties/misc`, :ref:`reference.json#/properties/persistent_identifiers`, :ref:`reference.json#/properties/publication_info`, :ref:`reference.json#/properties/report_numbers`, :ref:`reference.json#/properties/texkey`, :ref:`reference.json#/properties/title`, :ref:`reference.json#/properties/urls`


.. _reference.json#/properties/arxiv_eprint:

arxiv_eprint
++++++++++++

.. container:: title

 arXiv eprint number

:MARC: ``999C5r`` with ``arXiv:`` prefix
:example: ``1703.07274``

:type: ``string``

:pattern: ``^\d{4}.\d{4``, ``5}|[\w.]+(-[\w.]+)?/\d+$``

:minLength: ``1``


.. _reference.json#/properties/authors:

authors
+++++++

.. container:: title

 List of authors

:MARC: ``999C5h`` contains a comma-separated string with all
    authors, in ``first_name last_name`` order.

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **authors**  is:

:type: ``object``

**Properties:** :ref:`reference.json#/properties/authors/items/properties/full_name`, :ref:`reference.json#/properties/authors/items/properties/inspire_role`


.. _reference.json#/properties/authors/items/properties/full_name:

full_name
#########

Should be of the same form as
:ref:`hep.json#/properties/authors/items/properties/full_name`.

:example: ``Smith, John G.D.``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/authors/items/properties/inspire_role:

inspire_role
############

:MARC: ``999C5e`` for ``editor``

:type: ``string``

:minLength: ``1``

**Allowed values:** 

- author
- supervisor
- editor


.. _reference.json#/properties/book_series:

book_series
+++++++++++

:type: ``object``

**Properties:** :ref:`reference.json#/properties/book_series/properties/title`, :ref:`reference.json#/properties/book_series/properties/volume`


.. _reference.json#/properties/book_series/properties/title:

title
#####

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/book_series/properties/volume:

volume
######

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/collaborations:

collaborations
++++++++++++++

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **collaborations**  is:

:MARC: ``999C5c``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/document_type:

document_type
+++++++++++++

:MARC: conceptually similar to ``999C5d``, but allowed values
    differ.

:Reference: :ref:`document_type.json#/`


.. _reference.json#/properties/dois:

dois
++++

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **dois**  is:

:MARC: ``999C5a`` with prefix ``doi:``

:type: ``string``

:pattern: ``^10\.\d+(\.\d+)?/.+$``

:minLength: ``1``


.. _reference.json#/properties/external_system_identifiers:

external_system_identifiers
+++++++++++++++++++++++++++

:MARC: ``999C5u`` (as url)

List of identifiers of this document on external systems.

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **external_system_identifiers**  is:

:type: ``object``

:Required: :ref:`reference.json#/properties/external_system_identifiers/items/properties/schema`, :ref:`reference.json#/properties/external_system_identifiers/items/properties/value`

**Properties:** :ref:`reference.json#/properties/external_system_identifiers/items/properties/schema`, :ref:`reference.json#/properties/external_system_identifiers/items/properties/value`


.. _reference.json#/properties/external_system_identifiers/items/properties/schema:

schema
######

:MARC: ``999C5u`` (as url)

:type: ``string``

:pattern: ``^\w+$``

:minLength: ``1``


.. _reference.json#/properties/external_system_identifiers/items/properties/value:

value
#####

.. container:: title

 External identifier

:MARC: ``999C5u`` (as url)

:type: ``string``

:pattern: ``^\S+$``

:minLength: ``1``


.. _reference.json#/properties/imprint:

imprint
+++++++

:type: ``object``

**Properties:** :ref:`reference.json#/properties/imprint/properties/date`, :ref:`reference.json#/properties/imprint/properties/place`, :ref:`reference.json#/properties/imprint/properties/publisher`


.. _reference.json#/properties/imprint/properties/date:

date
####

:type: ``string``

:format: ``date``

:minLength: ``1``


.. _reference.json#/properties/imprint/properties/place:

place
#####

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/imprint/properties/publisher:

publisher
#########

:MARC: ``999C5p``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/isbn:

isbn
++++

:MARC: ``999C5i``

ISBN if the cited document is a book.

.. note::

    If the cited document is a book chapter, use
    :ref:`reference.json#/properties/publication_info/properties/parent_isbn` instead.

:type: ``string``

:pattern: ``^\d*[0-9X]$``

:minLength: ``1``


.. _reference.json#/properties/label:

label
+++++

:MARC: ``999C5o``

Label used to refer to the reference in the main text, and put in
front of the reference in the reference list. Often, this is a
number, found in square brackets. These brackets (or parentheses),
if present, should not be put here.

:example: ``42``
:example: ``Jones1995c``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/misc:

misc
++++

:MARC: ``999C5m``

Unrecognized information from the reference.

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **misc**  is:

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/persistent_identifiers:

persistent_identifiers
++++++++++++++++++++++

:MARC: ``999C5a`` (with prefix ``hdl:`` or ``urn:``)

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **persistent_identifiers**  is:

:type: ``object``

**Properties:** :ref:`reference.json#/properties/persistent_identifiers/items/properties/schema`, :ref:`reference.json#/properties/persistent_identifiers/items/properties/value`


.. _reference.json#/properties/persistent_identifiers/items/properties/schema:

schema
######

:type: ``string``

:minLength: ``1``

**Allowed values:** 

- HDL
- URN


.. _reference.json#/properties/persistent_identifiers/items/properties/value:

value
#####

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info:

publication_info
++++++++++++++++

:type: ``object``

**Properties:** :ref:`reference.json#/properties/publication_info/properties/artid`, :ref:`reference.json#/properties/publication_info/properties/cnum`, :ref:`reference.json#/properties/publication_info/properties/journal_issue`, :ref:`reference.json#/properties/publication_info/properties/journal_record`, :ref:`reference.json#/properties/publication_info/properties/journal_title`, :ref:`reference.json#/properties/publication_info/properties/journal_volume`, :ref:`reference.json#/properties/publication_info/properties/material`, :ref:`reference.json#/properties/publication_info/properties/page_end`, :ref:`reference.json#/properties/publication_info/properties/page_start`, :ref:`reference.json#/properties/publication_info/properties/parent_isbn`, :ref:`reference.json#/properties/publication_info/properties/parent_report_number`, :ref:`reference.json#/properties/publication_info/properties/parent_title`, :ref:`reference.json#/properties/publication_info/properties/year`


.. _reference.json#/properties/publication_info/properties/artid:

artid
#####

:MARC: last part of ``999C5s`` (if not a page)

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/cnum:

cnum
####

:MARC: ``999C5b``

:Reference: :ref:`cnum.json#/`


.. _reference.json#/properties/publication_info/properties/journal_issue:

journal_issue
#############

:MARC: ``999C5n``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/journal_record:

journal_record
##############

:Reference: :ref:`journal.json#/`


.. _reference.json#/properties/publication_info/properties/journal_title:

journal_title
#############

:MARC: first part of ``999C5s``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/journal_volume:

journal_volume
##############

:MARC: second part of ``999C5s``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/material:

material
########

:Reference: :ref:`material.json#/`


.. _reference.json#/properties/publication_info/properties/page_end:

page_end
########

:MARC: Last part of ``999C5s`` (if page-range)

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/page_start:

page_start
##########

:MARC: Last part of ``999C5s`` (if not article ID)

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/parent_isbn:

parent_isbn
###########

:MARC: ``999C5i``, but not distinguished from
    the :ref:`reference.json#/properties/isbn` of the
    cited document.

If the cited document is a book chapter, this is the ISBN
of the book.

:type: ``string``

:pattern: ``^\d*[0-9X]$``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/parent_report_number:

parent_report_number
####################

:MARC: ``999C5r`` but not distinguished from the cited
    document :ref:`reference.json#/properties/report_numbers`.

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/parent_title:

parent_title
############

:MARC: ``999C5q``

Title of the parent document, e.g. title of the book if the
cited document is a book chapter.

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/publication_info/properties/year:

year
####

:MARC: ``999C5y``

:type: ``integer``

:minimum: ``1000``

:maximum: ``2050``


.. _reference.json#/properties/report_numbers:

report_numbers
++++++++++++++

:MARC: ``999C5r``

.. note::

    If the cited document is only part of a report, use
    :ref:`reference.json#/properties/publication_info/properties/parent_report_number` instead.

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **report_numbers**  is:

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/texkey:

texkey
++++++

:MARC: ``999C5k``

Key that was used for this citation in the document. This may be
extracted if the document is a PDF generated from a LaTeX, and
possibly coincides with the one of the
:ref:`hep.json#/properties/texkeys` assigned to the cited document
by Inspire and made visible in the TeX export formats.

:example: ``Maldacena:1997re``

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/title:

title
+++++

:Reference: :ref:`title.json#/`

:MARC: ``999C5t``


.. _reference.json#/properties/urls:

urls
++++

:type: ``array``

:minItems: ``1``

.. container:: sub-title

 Every element of **urls**  is:

.. container:: title

 URL of related document

:MARC: ``999C5u``

:type: ``object``

:Required: :ref:`reference.json#/properties/urls/items/properties/value`

**Properties:** :ref:`reference.json#/properties/urls/items/properties/description`, :ref:`reference.json#/properties/urls/items/properties/value`


.. _reference.json#/properties/urls/items/properties/description:

description
###########

:type: ``string``

:minLength: ``1``


.. _reference.json#/properties/urls/items/properties/value:

value
#####

:type: ``string``

:minLength: ``1``