= Relaton YAML

The following structure is in place for encoding bibitem as YAML objects, and is also used 
to represent bibliographic entries in Metanorma Asciidoctor. The structure has not yet been
generalised to `bibdata/ext`, the flavour specific extensions of relaton.

Any elements which are arrays can also be populated by a hash or single element. For example,
the following are equivalent:

[source,yaml]
....
title:
  - type: main
    content: Geographic information
title:
  type: main
  content: Geographic information
script:
  - Latn
script: Latn
....

In YAML, "on" is a reserved word, and thus cannot be used as a key. "value" is used as a synonym for
"on" in dates.

The structure below is given in YAML format:

[source,yaml]
....
# bibliographic item anchor, used to crossreference within document
id: ISO/TC211
# date record was created
fetched: 2019-06-30
# titles are an array, with a mandatory type and content, and optional format, language and script
title:
  - type: main
    content: Geographic information
  - type: subtitle
    content: Geographic information subtitle
    language: en
    script: Latn
    format: text/plain
# type of document
type: standard
# document identifiers are an array, with a mandatory type and id component
docid:
  type: ISO
  id: TC211
# document number
docnumber: 211
# edition
edition: 1
# language is an array
language:
  - en
  - fr
# script is an array
script:
  Latn
# version contains revision date and draft (as array)
version:
  revision_date: 2019-04-01
  draft: draft
# note is an array of type and content
biblionote:
  type: bibnote
  content: >
      Mark set a major league
      home run record in 1998.
# document status has stage, and optional substage and iteration
docstatus:
  stage: stage
  substage: substage
  iteration: iteration
# date is an array, with mandatory type, and either an "on" value or a "from" and optional "to" value
date:
  - type: issued
    value: 2014
  - type: published
    from: 2014-04
    to: 2014-05
  - type: accessed
    value: 2015-05-20
# abstract is an array, with content, and optional language, script, format
abstract:
  - content: >
      ISO 19115-1:2014 defines the schema required for ...
  - content: >
      L'ISO 19115-1:2014 définit le schéma requis pour ...
    language: fr
    script: Latn
    format: text/plain
# contributors are an array of entity/role pairs, where entity is either person or organization.
# The role is an array; if there is a more complete description, that is given as the second element 
# of an array, and is itself an array.
# Organisations have attributes name, url, abbreviation, subdivision, contacts, identifiers
# Persons have attributes name, affiliation, contacts
# Person names have attributes surname, completename, initials, forename, additions, prefixes.
# Initials, forename, additions, prefixes are arrays.
# Name field values are either strings, or hashes, with content and language and script attributes.
# The language and script attribute can also be given on the name.
# Contacts are an array, containing either addresses, or other fields. 
# Addresses are identified as hashes containing a city attribute; they can also contain a street 
# (which is an array), a postcode, a state, and a country. The other contact fields
# are phones, emails, uris; they contain a type giving the field name, and a value.
# Affiliations are an array, and they contains an organization, and an optional description. 
# The affiliation description can be a single string, or a hash of content, language, script, and format.
contributor:
  - organization:
      name: International Organization for Standardization
      url: www.iso.org
      abbreviation: ISO
      subdivision: division
    role: 
      - publisher
      - 
        - Publisher role
  - person:
      name:
        completename:
          content: A. Bierman
          language: en
      affiliation:
        - organization:
            name: IETF
            abbreviation: IETF
             identifier:      
               - type: uri
                 id: www.ietf.org
          description: Affiliation description
      contact:
        - street:
          - 8 Street St
          city: City
          postcode: 123456
          country: Country
          state: State
        - type: phone
          value: 223322
    role: author
  - person:
      name: IETF
      abbreviation: IETF
      identifier:
        - type: uri
          id: www.ietf.org
    role:
      publisher
  - person:
      name:
        language: en
        initial:
          - A.
        surname: Bierman
      affiliation:
        -  organization:
             name: IETF
             abbreviation: IETF
           description:
             content: Affiliation description
             language: en
             script: Latn
      identifier:
        - type: uri
          id: www.person.com
    role: 
      author
# copyright consists of an owner (a hash containing the fields of an organisation),
# a "from" date, and an optional "to" date
copyright:
   owner:
     name: International Organization for Standardization
     abbreviation: ISO
     url: www.iso.org
   from: 2014
   to: 2020
# link is an array of URIs, with a type and content
link:
  - type: src
    content: https://www.iso.org/standard/53798.html
  - type: obp
    content: https://www.iso.org/obp/ui/#!iso:std:53798:en
  - type: rss
    content: https://www.iso.org/contents/data/standard/05/37/53798.detail.rss
# relations are an array of type, bibitem, and bib_locality.
# bibitem contains any of the attributes of a bibliographic item.
# bib_locality is an array that contains a type, a reference_from, and optionally a reference_to
relation:
  - type: updates
    bibitem:
      formattedref: ISO 19115:2003
    bib_locality:
      type: page
      reference_from: 7
      reference_to: 10
  - type: updates
    bibitem:
      type: standard
      formattedref: ISO 19115:2003/Cor 1:2006
# series are an array, containing a type, and either a formattedref, or:
# a title, a place, an organization (string),
# an abbreviation, a from, a to, a number, and a partnumber.
# The series title, like the titles of bibliographic items, contains a type,
# content, and optional language, script, and format attributes.
# The abbreviation and formattedref are either a string, 
# or a hash containing content, language, and script.
series:
  - type: main
    title:
      type: original
      content: ISO/IEC FDIS 10118-3
      language: en
      script: Latn
      format: text/plain
    place: Serie's place
    organization: Serie's organization
    abbreviation:
      content: ABVR
      language: en
      script: Latn
    from: 2009-02-01
    to: 2010-12-20
    number: serie1234
    partnumber: part5678
  - type: alt
    formattedref: 
      content: serieref
      language: en
      script: Latn
# medium contains a form, a size, and a scale
medium:
  form: medium form
  size: medium size
  scale: medium scale
# place is an array of strings
place: bib place
# extent is an array, containing type, a reference_from, and an optional reference_to
extent:
  type: section
  reference_from: 7
# accesslocation is an array of strings
accesslocation:
  - accesslocation1
  - accesslocation2
# classification is an array of type and value
classification:
  type: type
  value: value
# validity contains a begins date, an ends date, and a revision date
validity:
  begins: 2010-10-10 12:21
  ends: 2011-02-03 18:30
  revision: 2011-03-04 09:00
....

The Metanorma Asciidoctor representation of this hash structure
in a bibliography
is as a definition list, with nested definition lists for nested structures.
Repeating elements in a hash can be realised as ordered or unordered lists.
However, given how awkward lists of definition lists are in Asciidoctor,
Metanorma Asciidoctor also supports representing repeating elements 
by repeating the key for that entry.

Each Relaton entry in a bibliography is represented in Metanorma Asciidoctor
through a subclause with option attribute `[%bibitem]`. Any title given to the
subclause is treated as the title for the bibliographic entry, with language `en`,
script `Latn`, format `text/plain`, and type `main`. If there is no such title
for the entry, the subclause title should be left as `{blank}`.

So the following is a very simple reference in Metanorma Asciidoctor:

[source,asciidoctor]
----
[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid:: 
  type::: ISO
  id::: ISO 123
docid::
  type::: ABC
  id::: 32784
type:: standard
----

The anchor crossreference for the bibliographic entry may be encoded as the
`id` entry in the definition list, or as the normal Asciidoctor anchor on the
subclause, which takes priority over it:

[source,asciidoctor]
----
[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
docid:: 
  type::: ISO
  id::: ISO 123
type:: standard
----

Asciidoctor does not currently cope with definition lists more than four levels
deep. If deeper nesting is needed, you will need to attach a new definition
list with a list continuation:

[source,asciidoctor]
----
[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
docid:: 
  type::: ISO
  id::: ISO 123
type:: standard
contributor::
  role::: author
  person:::
    name::::
+
--
completename::
  language::: en
  content::: Fred
--
----

The most heavily nested parts of a Relaton entry are the contributors,
series, and relations. To prevent excessive depth of nesting for such
entries, they can be marked up as subclauses within the entry, with the clause
titles "contributor", "series", and "relation". Each subclause contains
a new definition list, with its definition list reset to zero depth;
the subclauses can be repeated for multiple instances of the same subentity.

The following is Metanorma Asciidoctor markup corresponding to the YAML
given above:


[source,asciidoc]
....
[[ISO/TC211]]
[%bibitem]
=== {blank}
fetched:: 2019-06-30
title::
  type::: main
  content::: Geographic information
title::
  type::: subtitle
  content::: Geographic information subtitle
  language::: en
  script::: Latn
  format::: text/plain
type:: standard
docid::
  type::: ISO
  id::: TC211
docnumber:: 211
edition:: 1
language::
  * en
  * fr
script:: Latn
version::
  revision_date::: 2019-04-01
  draft::: draft
biblionote::
  type::: bibnote
  content::: 
+
---
Mark set a major league
home run record in 1998.
---
docstatus::
  stage::: stage
  substage::: substage
  iteration::: iteration
date::
  type::: issued
  value::: 2014
date::
  type::: published
  from::: 2014-04
  to::: 2014-05
date::
  type::: accessed
  value::: 2015-05-20
abstract::
  content::: 
+
---
      ISO 19115-1:2014 defines the schema required for ...
---
abstract::
  content::: L'ISO 19115-1:2014 définit le schéma requis pour ...
  language::: fr
  script::: Latn
  format::: text/plain
copyright::
   owner:::
     name:::: International Organization for Standardization
     abbreviation:::: ISO
     url:::: www.iso.org
   from::: 2014
   to::: 2020
link::
  type::: src
  content::: https://www.iso.org/standard/53798.html
link::
  type::: obp
  content::: https://www.iso.org/obp/ui/#!iso:std:53798:en
link::
  type::: rss
  content::: https://www.iso.org/contents/data/standard/05/37/53798.detail.rss
medium::
  form::: medium form
  size::: medium size
  scale::: medium scale
place:: bib place
extent::
  type::: section
  reference_from::: 7
accesslocation::
  * accesslocation1
  * accesslocation2
classification::
  type::: type
  value::: value
validity::
  begins::: 2010-10-10 12:21
  ends::: 2011-02-03 18:30


==== Contributor
person::
  name::: International Organization for Standardization
  url::: www.iso.org
  abbreviation::: ISO
  subdivision::: division
role::
  * publisher
  * 
  ** Publisher role

==== Contributor
person::
  name:::
    completename::::
      content::::: A. Bierman
      language::::: en
  affiliation:::
    organization::::
      name::::: IETF
      abbreviation::::: IETF
      identifier:::::
+
---
type:: uri
id:: www.ietf.org
---
    description:::: Affiliation description
  contact:::
    street::::
      * 8 Street St
    city:::: City
    postcode:::: 123456
    country:::: Country
    state:::: State
  contact:::
    type:::: phone
    value:::: 223322
role:: author

==== Contributor
person::
  name::: IETF
  abbreviation::: IETF
  identifier:::
    type:::: uri
    id:::: www.ietf.org
role:: publisher

==== Contributor
person::
  name:::
    language:::: en
    initial:::: A.
    surname:::: Bierman
  affiliation:::
    organization::::
      name::::: IETF
      abbreviation::::: IETF
    description::::
      content::::: Affiliation description
      language::::: en
      script::::: Latn
  identifier:::
    type:::: uri
    id:::: www.person.com
role:: author

==== Relation
type:: updates
bibitem::
  formattedref::: ISO 19115:2003
  bib_locality:::
    type:::: page
    reference_from:::: 7
    reference_to:::: 10

==== Relation
type::: updates
bibitem:::
  type::: standard
  formattedref::: ISO 19115:2003/Cor 1:2006

==== Series
type:: main
title::
  type::: original
  content::: ISO/IEC FDIS 10118-3
  language::: en
  script::: Latn
  format::: text/plain
place:: Serie's place
organization:: Serie's organization
abbreviation::
  content::: ABVR
  language::: en
  script::: Latn
from:: 2009-02-01
to:: 2010-12-20
number:: serie1234
partnumber:: part5678

==== Series
type:: alt
formattedref::
  content::: serieref
  language::: en
  script::: Latn
....