Gem Version Build Status (macOS) Build Status (Windows) Build Status (Ubuntu) Code Climate Pull Requests Commits since latest

Purpose

relaton-nist provides bibliographic information of NIST publications using the NistBibliographicItem model.

Relaton for NIST has been developed in cooperation with the NIST Cybersecurity Resource Center (CSRC) and the Computer Security Division (ITL/CSD).

Data sources

Relaton for NIST retrieves bibliographic information from two sources:

  • bibliographic feed from the NIST Cybersecurity Resource Center (CSRC) of all CSRC publications (in Relaton JSON)

  • bibliographic dataset from the NIST Library through the Information Services Office (ISO) that contains information about all NIST Technical Publications (GitHub)

Bibliographic information offered through CSRC is provided with enhanced metadata that is not available in the NIST Library dataset, including:

  • public drafts (the NIST Library dataset only contains final publications)

  • revision information: revision number, iteration

  • document stage information: retired, withdrawn, etc.

  • bibliographic dates, including issued date, updated date, published date, obsolete date, commenting period

  • document relationships: supersession and replacements

  • contacts: enhanced name parts and affiliation information

Relaton for NIST, therefore, uses the following order of priority for the data sources:

  1. bibliographic feed from NIST CSRC

  2. NIST Library dataset

Installation

Add this line to your application’s Gemfile:

gem 'relaton-nist'

And then execute:

$ bundle

Or install it yourself as:

$ gem install relaton_nist

Usage

Search for a standard using keywords

require 'relaton_nist'
=> true

hit_collection = RelatonNist::NistBibliography.search("8200")
=> <RelatonNist::HitCollection:0x007fc069d19da0 @ref=8200 @fetched=false>

item = hit_collection[1].fetch
=> #<RelatonNist::NistBibliographicItem:0x007fc049aa6778
 ...

XML serialization

item.to_xml
=> "<bibitem id="SP800-160Vol.1Ver.1Rev.1" type="standard" schema-version="v1.2.1">
      <fetched>2022-12-05</fetched>
      <title format="text/plain" language="en" script="Latn">Engineering Trustworthy Secure Systems</title>
      ...
    <bibitem>"

With argument bibdata: true it outputs XML wrapped by bibdata element and adds flavor ext element.

item.to_xml bibdata: true
=> "<bibdata type="standard" schema-version="v1.2.1">
      <fetched>2022-12-05</fetched>
      <title format="text/plain" language="en" script="Latn">Engineering Trustworthy Secure Systems</title>
      ...
      <ext schema-version="v1.0.0">
        <doctype>standard</doctype>
      </ext>
  </bibdata>"

Get code, and year

RelatonNist::NistBibliography.get("NIST IR 8200", "2018", {})
[relaton-nist] ("NIST IR 8200") fetching...
[relaton-nist] ("NIST IR 8200") found NIST IR 8200
=> #<RelatonNist::NistBibliographicItem:0x00007fab74a572c0
...

Get short citation

A short citation is a convention about a citation’s format. The format for NIST publications is:

NIST {abbrev(series)} {docnumber} {(edition), optional} {(stage), optional}
# or
{abbrev(series)} {docnumber} {(edition), optional} {(stage), optional}

  • (stage) is empty if the state is "final" (published). In case the state is "draft" it should be:

    • PD for public draft

    • IPD for initial iteration public draft or 2PD, 3PD and so one for following iterations

    • FPD for final public draft

  • (edition) is the date of publication or update

  • docnumber is the full NIST number, including revision, e.g., 800-52

The format for FIPS publications is:

FIPS {docnumber}
# or
NIST FIPS {docnumber}
RelatonNist::NistBibliography.get("SP 800-205 (February 2019) (PD)")
[relaton-nist] ("SP 800-205") fetching...
[relaton-nist] ("SP 800-205") found SP 800-205 (Draft)
=> #<RelatonNist::NistBibliographicItem:0x007fc059934768
...

Get specific part, volume, version, revision, and addendum

Referehces can contain optional parameters {ptN}{vN}{verN}{rN}{/Add}: - Part is specified as ptN (SP 800-57pt1) - Volume is specified as vN (SP 800-60v1) - Version is specified as verN (SP 800-45ver2) - Revision is specified as rN (SP 800-40r3) - Addendum is specified as /Add (SP 800-38A/Add)

item = RelatonNist::NistBibliography.get 'NIST SP 800-67r1'
[relaton-nist] ("NIST SP 800-67r1") fetching...
[relaton-nist] ("NIST SP 800-67r1") found SP 800-67 Rev. 1
=> #<RelatonNist::NistBibliographicItem:0x00007fab748ae978
...

item.docidentifier.first.id
=> "SP 800-67 Rev. 1"

item = RelatonNist::NistBibliography.get 'SP 800-38A/Add'
[relaton-nist] ("SP 800-38A/Add") fetching...
[relaton-nist] ("SP 800-38A/Add") found SP 800-38A-Add
=> #<RelatonNist::NistBibliographicItem:0x007fd88c21d880
...

item.docidentifier.first.id
=> "SP 800-38A-Add"

Typed links

NIST documents may have src and doi link types.

item.link
=> [#<RelatonBib::TypedUri:0x00007f901971dc10 @content=#<Addressable::URI:0x62c URI:https://csrc.nist.gov/publications/detail/sp/800-67/rev-2/final>, @type="src">,
 #<RelatonBib::TypedUri:0x00007f901971d6e8 @content=#<Addressable::URI:0x640 URI:https://doi.org/10.6028/NIST.SP.800-67r2>, @type="doi">]

Create bibliographic item from YAML

hash = YAML.load_file 'spec/examples/nist_bib_item.yml'
=> {"id"=>"NISTIR 8011 Vol. 3",
...

RelatonNist::NistBibliographicItem.from_hash hash
=> #<RelatonNist::NistBibliographicItem:0x007f8b708505b8
...

Fetch data

This gem uses the https://raw.githubusercontent.com/usnistgov/NIST-Tech-Pubs/nist-pages/xml/allrecords.xml dataset as one of data sources.

The method RelatonNist::DataFetcher.fetch(output: "data", format: "yaml") fetches all the documents from the datast and save them to the ./data folder in YAML format. Arguments:

  • output - folder to save documents (default './data').

  • format - the format in which the documents are saved. Possible formats are: yaml, xml, bibxxml (default yaml).

RelatonNist::DataFetcher.fetch
Started at: 2021-09-01 18:01:01 +0200
Stopped at: 2021-09-01 18:01:43 +0200
Done in: 42 sec.
=> nil

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to [rubygems.org](https://rubygems.org).

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/relaton-nist.

License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).