File: README — Documentation for pubid-iso (0.3.1)

Purpose

This gem implements a mechanism to parse and utilize ISO publication identifiers.

Use cases to support

generate the corresponding URN format (according to RFC 5141)
generate updated PubID
generate language specific PubID
generate dated vs undated PubIDs

Usage samples

require "pubid-iso"

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123)
pubid.to_s

=> "ISO 1234"

With coopublisher

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", copublisher: "IEC", number: 123)
pubid.to_s

=> "ISO/IEC 1234"

With document type

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", type: "TR", number: 123)
pubid.to_s

=> "ISO/TR 1234"

With stage

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", stage: :WD, number: 123)
pubid.to_s

=> "ISO/WD 1234"

With part number

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1)
pubid.to_s

=> "ISO 1234-1"

Iteration

pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, stage: :DIS, iteration: 1)
pubid.to_s

=> "ISO/DIS 1234-1.1"

To apply iteration to document stage should be provided as well. Without stage error will be raised.

Amendment and Corrigendum

> pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, year: 2019, amendments: [{ number: "1", year: "2021", stage: :WD }])
> pubid.to_s
=> "ISO 1234-1:2019/WD Amd 1:2021"

> pubid = Pubid::Iso::Identifier.new(publisher: "ISO", number: 123, part: 1, year: 2019, corrigendums: [{ number: "1", year: "2021", stage: :WD }])
> pubid.to_s
=> "ISO 1234-1:2019/WD Cor 1:2021"

See documentation on PubId::Iso::Supplement#initialize and Pubid::Core::Supplement#initialize to see all available options.

Using format options

> pubid = Pubid::Iso::Identifier.new(
  number: "8601",
  part: "1",
  year: 2019,
  edition: 1,
  amendment: {number: "1", year: "2021", stage: "DIS"}
)
> pubid.to_s(:ref_num_short)
=> "ISO 8601-1:2019/DAM 1:2021(E)"
> pubid.to_s(:ref_num_long)
=> "ISO 8601-1:2019/DAmd 1:2021(en)"
> pubid.to_s(:ref_dated)
=> "ISO 8601-1:2019/DAM 1:2021"
> pubid.to_s(:ref_dated_long)
=> "ISO 8601-1:2019/DAmd 1:2021"
> pubid.to_s(:ref_undated)
=> "ISO 8601-1:2019/DAM 1"
> pubid.to_s(:ref_undated_long)
=> "ISO 8601-1:2019/DAmd 1"

Using language specific rendering

> pubid = Pubid::Iso::Identifier.parse("ISO/FDIS 26000:2010(ru)")
> pubid.to_s(format: :ref_num_long, lang: :russian)
=> "ИСО/ОПМС 26000:2010(ru)"
> pubid = Pubid::Iso::Identifier.parse("ISO/IEC Guide 71:2001(fr)")
> pubid.to_s(format: :ref_num_long, lang: :french)
=> "Guide ISO/CEI 71:2001(fr)"

Rendering URN identifier

> pubid = Pubid::Iso::Identifier.new(
  number: "8601",
  part: "1",
  year: 2019,
  edition: 1,
  amendments: {number: "1", year: "2021", stage: "DIS"}
)
> pubid.urn
=> "urn:iso:std:iso:8601:-1:ed-1:amd:2021:v1"

Typed stage abbreviation

> pubid = Pubid::Iso::Identifier.parse("ISO/FDIS 26000:2010")
> pubid.typed_stage_abbrev
=> "FDIS"
> pubid.typed_stage_name
=> "Final Draft"

> pubid = Pubid::Iso::Identifier.parse("ISO/FDTR 26000:2010")
> pubid.typed_stage_abbrev
=> "FDTR"
> pubid.typed_stage_name
=> "Final Draft Technical Report"

> pubid = Pubid::Iso::Identifier.parse("ISO/WD TR 26000:2010")
> pubid.typed_stage_abbrev
=> "WD TR"
> pubid.typed_stage_name
=> "Working Draft Technical Report"

See documentation (Pubid::Iso::Identifier and Pubid::Core::Identifier) for all available attributes and options.

Elements of the PubID

Document identifier

General

The ISO document identifier is assembled out of these metadata elements:

publisher: publisher of the document
document stage: stage of development of document, according to the Harmonized Stage Codes
document number: numeric identifier of document
update number: serial number of update (for amendments and technical corrigenda)
document type: type of ISO deliverable
copyright year: year of publication of document
language: language of document

Publisher

This is the abbreviation of the publishing organization, typically ISO.

If the document is published under co-publishing agreements, it can contain the abbreviations of other publishing SDOs, delimited by / after ISO.

An International Workshop Agreement document has publisher abbreviation of IWA.

ISO, ISO/IEC, ISO/IEC/IEEE, ISO/IEEE, ISO/SAE, IWA

Document type and stage

ISO document stages in document identifiers are mapped as follows.

International Standard

00.00 to 00.99: “PWI”
10.00 to 10.98: “NP”
10.99 to 20.00: “AWI”
20.20 to 20.99: “WD”
30.00 to 30.99: “CD”
40.00 to 40.99: “DIS”
50.00 to 50.99: “FDIS”
60.00: “PRF”
60.60: empty designation

Technical Specification, Technical Report

00.00 to 00.99: “PWI TR,TS”
10.00 to 10.98: “NP TR,TS”
10.98 to 20.00: “AWI TR,TS”
20.20 to 20.99: “WD TR,TS”
30.00 to 30.99: “CD TR,TS”
40.00 to 40.99: TS/TRs do not have DIS stage because they are not international standards.
50.00 to 50.99: TS/TRs do not have FDIS stage because they are not international standards.
60.00: “PRF TR,TS”
60.60: “TR,TS”

Amendment

00.00 to 00.99: “base-document-id/PWI Amd num”
10.00 to 10.98: “base-document-id/NP Amd num”
10.99 to 20.00: “base-document-id/AWI Amd num”
20.20 to 20.99: “base-document-id/WD Amd num”
30.00 to 30.99: “base-document-id/CD Amd num”
40.00 to 40.99: “base-document-id/DAmd num”
50.00 to 50.99: “base-document-id/FDAmd num”
60.00: “base-document-id/PRF Amd num”
60.60: “base-document-id/Amd num”

Technical Corrigendum

00.00 to 00.99: “base-document-id/PWI Cor num”
10.00 to 10.98: “base-document-id/NP Cor num”
10.99 to 20.00: “base-document-id/AWI Cor num”
20.20 to 20.99: “base-document-id/WD Cor num”
30.00 to 30.99: “base-document-id/CD Cor num”
40.00 to 40.99: “base-document-id/DIS Cor num”
50.00 to 50.99: “base-document-id/FDCor num”
60.00: “base-document-id/PRF Cor num”
60.60: “base-document-id/Cor num”

When the Publisher element contains a “slash” (“/”), the separation in front of the document stage will be converted into an empty space.

ISO/NP 33333 but ISO/IEC NP 33333. ISO/NP TR 33333 but ISO/IEC NP TR 33333.

According to ISO Directives Part 1 (11ed), SE.2:

Working drafts (WD), committee drafts (CD), draft International Standards (DIS), final draft International Standards (FDIS) and International Standards`", "`Successive DIS on the same subject will carry the same number but will be distinguished by a numerical suffix (.2, .3, etc.).

The stage iteration number is assigned accordingly for all stages, which is patterned as:

{document stage} (no suffix if iteration is 1); or
{document stage}.{iteration number} (suffix including iteration number after 1).

Once the document is published (stage 60 substage 60), no status abbreviation is given.

Full PubID patterns

The patterns are as follows:

International Standard: {publisher} (/{document type and stage})? ({document number}) (- {part number})? (: {copyright year}) ({ISO 639 language code})?

ISO/IEEE/FDIS 33333-2, ISO/IEEE 33333-2:2030(E)
Technical Report, Technical Specification: {publisher} (/{document type and stage}) ({document number}) (- {part number})? (: {copyright year}) ({ISO 639 language code})?

ISO/IEC/FDIS TS 33333-2, ISO/TR 33333-2:2030(E), ISO/IEC TR 33333-2:2030(E)
Amendments, Technical Corrigendum: {source document ID}/{document type and stage} {update number} (: {copyright year}) ({ISO 639 language code})?

ISO 33333-2:2030/DIS Cor 2:2031, ISO 33333-2:2030/Cor 2:2032, ISO/IEC 33333-2:2030/Cor 2:2032