Relaton YAML

YAML

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

If an element in Relaton XML has attributes, the content of the element is represented in YAML with a content key:

<title type="main">Geographic information</title>

title:
  type: main
  content: Geographic information

Any elements with a cardinality of many can be represented as arrays, but they can also be populated by a hash or single element. For example, a Relaton title can have multiple titles, and multiple scripts; so the following are equivalent:

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:

# 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 of type and description; it can be a an array of just string, which are treated
# as the type.
# Organisations have attributes name, url, abbreviation, subdivision, contacts, identifiers
# Persons have attributes name, affiliation, contacts
# Person names have attributes, given, surname, additions, prefixes or completename.
# Given has formatted_initials or forename.
# 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:
        content: International Organization for Standardization
      url: www.iso.org
      abbreviation:
        content: ISO
      subdivision: division
    role:
      type: publisher
      description: Publisher role
  - person:
      name:
        completename:
          content: A. Bierman
          language: en
      affiliation:
        - organization:
            name:
              content: IETF
            abbreviation:
              content: IETF
            identifier:
              - type: uri
                id: www.ietf.org
          description: Affiliation description
      contact:
        - address:
            street:
              - 8 Street St
            city: City
            postcode: '123456'
            country: Country
            state: State
        - phone: '223322'
    role: author
  - organization:
      name:
        content: Internet Engineering Task Force
      abbreviation:
        content: IETF
      identifier:
        - type: uri
          id: www.ietf.org
    role:
      publisher
  - person:
      name:
        given:
          forename:
            initial: A
            language: en
          formatted_initials:
            content: A.
        surname:
          content: Bierman
      affiliation:
        - organization:
            name:
              content: IETF
            abbreviation:
              content: 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:
      content: International Organization for Standardization
     abbreviation:
      content: 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:
        content: ISO 19115:2003
    bib_locality:
      type: page
      reference_from: '7'
      reference_to: '10'
  - type: updates
    bibitem:
      type: standard
      formattedref:
        content: 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'

Metanorma structure (AsciiBib): nested definition list

The Metanorma AsciiDoc representation of the Relaton hash structure in a bibliography is as a definition list of element name and element contents, with nested definition lists for nested structures. If a nested definition is given for an element, the element itself has a blank definition.

As with the YAML representation, if an element in Relaton XML has attributes, the content of the element is represented in YAML with a content key:

<title type="main">Geographic information</title>

title::
  type::: main
  content::: Geographic information

Likewise, as with the YAML representation, Repeating elements in a hash can be realised as ordered or unordered lists.

language::
  . en
  . fr

Metanorma AsciiDoc also supports representing repeating elements by repeating the key for that entry. This will almost always be more straightforward to use in AsciiDoc:

language:: en
language:: fr

Each Relaton entry in a bibliography is represented in Metanorma AsciiDoc 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.

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

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

If there is no such title for the entry, the subclause title should be left as , and the desired title should be given in the hash body:

[%bibitem]
=== {blank}
id:: iso123
title::
language::: fr
script::: Latn
format::: text/plain
type::: alt
content::: Latex de caoutchouc -- Échantillonnage

Note the use of content as a key to represent the contents of the title tag.

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

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

Repeating elements in a hash can be realised as ordered or unordered lists.

[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
docid::
  type::: ISO
  id::: ISO 123
language::
  . en
  . fr

Metanorma AsciiDoc also supports representing repeating elements by repeating the key for that entry. This will almost always be more straightforward to use in AsciiDoc:

[[iso123]]
[%bibitem]
=== Rubber latex -- Sampling
docid::
  type::: ISO
  id::: ISO 123
language:: en
language:: fr

AsciiDoc does not recognise 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, with the definition list depth reset back to one:

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

(This is very awkward, and JSON Path style definition lists provides a workaround.)

The most heavily nested parts of a Relaton entry are the contributors, series, and relations. Each of these 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.

AsciiBib citations can be combined with other AsciiDoc citations in the same Metanorma document; but any AsciiDoc citations need be precede AsciiBib citations. Each AsciiBib citations constitutes a subclause of its own, and Metanorma will (unsuccessfully) attempt to incorporate any trailing material in the subclause, including AsciiDoc citations, into the current AsciiBib citation.

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

[[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
organization::
  name::: International Organization for Standardization
  url::: www.iso.org
  abbreviation::: ISO
  subdivision::: division
role::
  type::: publisher
  description::: 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
organization::
  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

JSON Path style definition lists

The foregoing structure requires frequent breakouts into open blocks, to deal with the limitation on AsciiDoc nested definition lists. An alternative is to represent the nested structure of Relaton records in a simple, one-level definition list, and to use the key for each key-value pair to represent the hierarchical nesting of entries, as a dot-delimited path of keys. For example,

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

can instead be represented as:

[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid.type:: ISO
docid.id:: ISO 123

Whenever part of the key is repeated between entries, the entries are assumed to attach to the same parent. If an array of hashes is needed, a blank entry is required for the key of each repeating element: For example,

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

can instead be represented as:

[%bibitem]
=== Rubber latex -- Sampling
id:: iso123
docid::
docid.type:: ISO
docid.id:: ISO 123
docid::
docid.type:: ABC
docid.id:: 32784

Embedded elements can also repeat:

[%bibitem]
...
==== Contributor
person::
  contact:::
    street::::
      . 8 Street St
    city:::: City
    postcode:::: 123456
    country:::: Country
    state:::: State
  contact:::
    type:::: phone
    value:::: 223322

can instead be represented as:

[%bibitem]
...
contributor.person.contact::
contributor.person.contact.street:: 8 Street St
contributor.person.contact.city:: City
contributor.person.contact.postcode:: 123456
contributor.person.contact.country:: Country
contributor.person.contact.state:: State
contributor.person.contact::
contributor.person.contact.type:: phone
contributor.person.contact.value:: 223322

The following is Metanorma AsciiDoc markup corresponding to the YAML given above, using JSON Path style definition lists instead of nested definition lists:

[[ISO/TC211]]
[%bibitem]
=== {blank}
fetched:: 2019-06-30
title::
title.type:: main
title.content:: Geographic information
title::
title.type:: subtitle
title.content:: Geographic information subtitle
title.language:: en
title.script:: Latn
title.format:: text/plain
type:: standard
docid::
docid.type:: ISO
docid.id:: TC211
docnumber:: 211
edition:: 1
language:: en
language:: fr
script:: Latn
version.revision_date:: 2019-04-01
version.draft:: draft
biblionote.type:: bibnote
biblionote.content::
+
--
Mark set a major league
home run record in 1998.
--
docstatus.stage:: stage
docstatus.substage:: substage
docstatus.iteration:: iteration
date::
date.type:: issued
date.value:: 2014
date::
date.type:: published
date.from:: 2014-04
date.to:: 2014-05
date::
date.type:: accessed
date.value:: 2015-05-20
abstract::
abstract.content::
+
--
ISO 19115-1:2014 defines the schema required for ...
--
abstract::
abstract.content:: L'ISO 19115-1:2014 définit le schéma requis pour ...
abstract.language:: fr
abstract.script:: Latn
abstract.format:: text/plain
copyright.owner.name:: International Organization for Standardization
copyright.owner.abbreviation:: ISO
copyright.owner.url:: www.iso.org
copyright.from:: 2014
copyright.to:: 2020
link::
link.type:: src
link.content:: https://www.iso.org/standard/53798.html
link::
link.type:: obp
link.content:: https://www.iso.org/obp/ui/#!iso:std:53798:en
link::
link.type:: rss
link.content:: https://www.iso.org/contents/data/standard/05/37/53798.detail.rss
medium::
medium.form:: medium form
medium.size:: medium size
medium.scale:: medium scale
place:: bib place
extent.type:: section
extent.reference_from:: 7
accesslocation:: accesslocation1
accesslocation:: accesslocation2
classification.type:: type
classification.value:: value
validity.begins:: 2010-10-10 12:21
validity.ends:: 2011-02-03 18:30
contributor::
contributor.organization.name:: International Organization for Standardization
contributor.organization.url:: www.iso.org
contributor.organization.abbreviation:: ISO
contributor.organization.subdivision:: division
contributor.role.type:: publisher
contributor.role.description:: Publisher role
contributor::
contributor.person.name.completename.content:: A. Bierman
contributor.person.name.completename.language:: en
contributor.person.affiliation.organization.name:: IETF
contributor.person.affiliation.organization.abbreviation:: IETF
contributor.person.affiliation.organization.identifier.type:: uri
contributor.person.affiliation.organization.identifier.id:: www.ietf.org
contributor.person.affiliation.description:: Affiliation description
contributor.person.contact::
contributor.person.contact.street:: 8 Street St
contributor.person.contact.city:: City
contributor.person.contact.postcode:: 123456
contributor.person.contact.country:: Country
contributor.person.contact.state:: State
contributor.person.contact::
contributor.person.contact.type:: phone
contributor.person.contact.value:: 223322
contributor.role:: author
contributor::
contributor.organization.name:: IETF
contributor.organization.abbreviation:: IETF
contributor.organization.identifier.type:: uri
contributor.organization.identifier.id:: www.ietf.org
contributor.role:: publisher
contributor::
contributor.person.name.language:: en
contributor.person.name.initial:: A.
contributor.person.name.surname:: Bierman
contributor.person.affiliation.organization.name:: IETF
contributor.person.affiliation.organization.abbreviation:: IETF
contributor.person.affiliation.description.content:: Affiliation description
contributor.person.affiliation.description.language:: en
contributor.person.affiliation.description.script:: Latn
contributor.person.identifier.type:: uri
contributor.person.identifier.id:: www.person.com
contributor.role:: author
relation::
relation.type:: updates
relation.bibitem.formattedref:: ISO 19115:2003
relation.bibitem.bib_locality.type:: page
relation.bibitem.bib_locality.reference_from:: 7
relation.bibitem.bib_locality.reference_to:: 10
relation::
relation.type:: updates
relation.bibitem.type:: standard
relation.bibitem.formattedref:: ISO 19115:2003/Cor 1:2006
series::
series.type:: main
series.title.type:: original
series.title.content:: ISO/IEC FDIS 10118-3
series.title.language:: en
series.title.script:: Latn
series.title.format:: text/plain
series.place:: Serie's place
series.organization:: Serie's organization
series.abbreviation.content:: ABVR
series.abbreviation.language:: en
series.abbreviation.script:: Latn
series.from:: 2009-02-01
series.to:: 2010-12-20
series.number:: serie1234
series.partnumber:: part5678
series::
series.type:: alt
series.formattedref.content:: serieref
series.formattedref.language:: en
series.formattedref.script:: Latn