Metanorma: Aequitate Verum

Contributor metadata

Organizations

Basic information

Organizations contributing to a document are specified with document attributes.

For each organization, it is necessary to name the organization and its role.

Roles available for organizations are:

publisher

Publisher of the document.

sponsor

Sponsor of the document.

copyright-holder

Copyright owner of the document.

Multiple instances of organizations are specified by suffixing a number to the document attribute, as _2, _3, etc.

Example 1. Example of setting multiple organizations per contribution role
:publisher: International Electrotechnical Commission
:publisher_2: Internet Engineering Task Force
:sponsor: International Organization for Standardization
:sponsor_2: U.S. Department of Commerce
:copyright_holder: International Electrotechnical Commission

Additional metadata

The following metadata can be provided for contributing organizations:

For sponsor:

sponsor_logo

Logo of the sponsor.

sponsor-address

Address of the sponsor.

sponsor-phone

Phone number of the sponsor.

sponsor-fax

Fax number of the sponsor.

sponsor-email

Email of the sponsor.

sponsor-uri

Website URL of the sponsor.

For publisher:

publisher_logo

Logo of the publisher.

pub-address

Address of the publisher.

pub-phone

Phone number of the publisher.

pub-fax

Fax number of the publisher.

pub-email

Email of the publisher.

pub-uri

Website URL of the publisher.

Example 2. Comprehensive example of setting organizational contributors with additional metadata
:publisher: International Electrotechnical Commission
:publisher_2: Internet Engineering Task Force
:publisher_logo: iec.gif
:publisher_logo_2: ietf.gif
:pub-address_2: 5177 Brandin Ct, Fremont, California, 94538, United States
:sponsor: International Organization for Standardization
:sponsor_2: U.S. Department of Commerce
:sponsor_logo: iso.gif
:sponsor_logo_2: us_commmerce.gif
:sponsor-email: central@iso.org
:sponsor-email_2: TheSec@doc.gov
:copyright_holder: International Electrotechnical Commission

Subdivisions

Contributing subdivisions of an organization can be set using the document attributes:

subdivision

The name of the subdivision.

subdivision-abbr

The abbreviation of the subdivision.

Note
The subdivision can only be set for the first organization with role publisher.
Example 3. Example of setting subdivision of the publisher
:publisher: Institute of Electrical and Electronics Engineers
:subdivision: IEEE SA Standards Board
:subdivision-abbr: IEEE SASB

Groups

Contributor groups of organizations are specified using document attributes.

These attributes are specific to Metanorma flavours, and are treated as SDO-specific metadata.

Example 4. Example of SDO-specific group contributor for ISO and IEC
  • technical-committee specifies the Technical Committee(s)

  • technical-committee-number specifies the TC number

  • subcommittee specifies the Subcommittee(s)

  • subcommittee-number specifies the SC number

  • workgroup specifies the Working Group(s)

  • workgroup-number specifies the WG number

  • workgroup-type specifies the type of the WG, such as WG, AG, CAG, etc.

By default, the corporate author of the document is assumed to be the same as the publishing organization.

Default values for both the corporate author and the publisher are set in each Metanorma flavour.

Individuals

General

Individual contributors to a document are specified using document attributes.

Individual contributors have significantly more complex metadata compared to organizations.

Multiple contributors are specified by reusing the document attribute, and again suffixing a number to it, as _2, _3, etc.

Name and role

Individuals' names are encoded as follows:

fullname

Full name of the individual contributor.

surname

Surname of the individual contributor.

givenname

Given names of the individual contributor.

initials

Initials of given names of the individual contributor.

Depending on the Metanorma flavor:

  • fullname may be mandatory or optional.

  • The combination of name components may replace fullname: surname, givenname and initials.

  • In some flavors, all 4 attributes all need to be filled in.

Example 5. Individual contributors with different ways of specifying names
:fullname: Fred Flintstone
:surname_2: Rubble
:givenname_2: Barney
:initials_2: B. X.

Individuals' roles:

role

The role of the individual contributor. Please refer to the Relaton specification for allowed values:

author

Author of the document.

editor

Editor of the document.

adapter

Person who adapted the document to its current form.

translator

Translator of the document.

performer

Performer of the item.

realizer

Person who realized this item.

publisher

Publisher of the document.

distributor

Distributor of the document.

owner

Owner of the document.

authorizer

Organization that authorized this document.

enabler

Person who enabled this document.

subject

Person who was a subject of this document.

The default for individuals is editor.

Roles can also be described more fully through role-description.

Example 6. Specifying roles with individual contributors
:fullname: Fred Flintstone
:role: author
:surname_2: Rubble
:givenname_2: Barney
:initials_2: B. X.
:role_2: editor
:role-description_2: consulting editor

Affiliations

Individuals have affiliations with organizations:

affiliation

Organization that the individual is affiliated with.

affiliation_abbrev

Abbreviation of the organization abbreviation.

affiliation_subdiv

Abbreviation of the subdivision that this individual is affiliated with.

affiliation_logo

The image logo of the affiliated organization.

Credentials

Individuals have relevant credentials.

contributor-credentials

Credentials of the individual.

contributor-position

Institutional position of the individual within their affiliation.

Addresses

Individuals have addresses.

address

The address of the individual. It is broken down into multiple parts:

street

Street number and street name of the address.

city

City name of the address.

region

Region name of the address.

country

Country name of the address.

postcode

Postcode of the address.

Others

Other contact details can be set for individual contributors.

contributor-uri

URL associated with the contributor.

email

Email of the contributor.

phone

Phone number of the contributor.

fax

Fax number of the contributor.

Example

The following is an illustration.

:fullname: Fred Flintstone
:role: author
:contributor-credentials: PhD, F.R.Pharm.S.
:contributor-position: Vice President, Medical Devices Quality & Compliance -- Strategic programmes
:affiliation: Slate Rock and Gravel Company
:affiliation_abbrev: SRG
:affiliation_subdiv: Hermeneutics Unit; Exegetical Subunit
:address: 6 Rubble Way, + \
Bedrock
:contributor-uri: http://slate.example.com
:phone: 123
:fax: 456
:surname_2: Rubble
:givenname_2: Barney
:initials_2: B. X.
:role_2: editor
:role-description_2: consulting editor
:contributor-credentials_2: PhD, F.R.Pharm.S.
:contributor-position_2: Former Chair ISO TC 210
:affiliation_2: Rockhead and Quarry Cave Construction Company
:affiliation_abbrev_2: RQCCC
:affiliation_subdiv_2: Hermeneutics Unit; Exegetical Subunit
:address_2: 6A Rubble Way, + \
Bedrock
:email_2: barney@rockhead.example.com
:phone_2: 789
:fax_2: 012

Advanced specification

The method of using document attributes does not actually capture the full complexity of contributor metadata.

For example, individuals can hold multiple affiliations.

More complex contributor metadata is presented using YAML embedded in the metanorma-extension clause of the document, under the subclause contributor metadata [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.0].

The YAML is in the Relaton YAML format: it is an array of contributor objects, without the expected contributor heading. Compared to Metanorma document attributes, the structure of Relaton YAML is pedantic.

  • The YAML is given as an array of objects, one for each contributor.

  • It uses the keys of document attributes as keys, but in addition, organizational details are specified under an affiliations key, again as an array of objects.

  • Organizational details includes the name and subdivision of the organization, the position held within the organization, but not credentials. Unlike the case for document attributes, contact details can be associated with either the individual, or the affiliation.

The foregoing example is presented in Relaton YAML as follows, with the second contributor’s contact details specific to them and not their company.

Example 7. Using Relaton YAML to encode advanced contribution metadata
[.preface]
= metanorma-extension

== contributor metadata

[source,yaml]
----
- role: author
  person:
    name:
      completename: Fred Flintstone
    credential:
    - PhD, F.R.Pharm.S.
    affiliation:
    - name:
        content: Vice President, Medical Devices Quality & Compliance -- Strategic programmes
      organization:
        name: Slate Rock and Gravel Company
        abbreviation: SRG
        subdivision: Hermeneutics Unit; Exegetical Subunit
        contact:
          - formatted_address: 6 Rubble Way, Bedrock
          - uri: http://slate.example.com
          - phone: 123
          - phone:
              type: fax
              value: 456
- role:
    type: editor
    description: consulting editor
  person:
    name:
      surname: Rubble
      given:
        forename: Barney
        formatted_initials: B. X.
    credential:
    - PhD, F.R.Pharm.S.
    affiliation:
    - name:
        content: Former Chair ISO TC 210
      organization:
        name: Rockhead and Quarry Cave Construction Company
        abbreviation: RQCCC
        subdivision: Hermeneutics Unit; Exegetical Subunit
    contact:
      - address:
          street: 6A Rubble Way
          city: Bedrock
      - email: barney@rockhead.example.com
      - phone: 789
      - phone:
          type: fax
          value: 012
----