Relaton for NIST: bibliographic retrieval of NIST publications

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:

bibliographic feed from NIST CSRC
NIST Library dataset

The NIST CSRC provides:

NIST SP 800-*
NIST SP 500-*
NIST SP 1800-*
NIST FIPS {31, 39, 41, 46, 46-*, 48, 65, 73, 74, 81, 83, 87, 102, 112, 113, 139, 140-*, 141, 171, 180, 180-*, 181, 186, 186-*, 188, 190, 191, 196, 197, 198, 198-1, 199, 200, 201, 201-*, 202}

The NIST Library dataset provides documents listed in the index.

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

Configuration

Configuration is optional. The available option is logger which is a Logger instance. By default, the logger is Logger.new($stderr) with Logger::WARN level. To change the logger level, use RelatonNist.configure block.

require 'relaton_nist'
=> true

RelatonNist.configure do |config|
  config.logger.level = Logger::DEBUG
end

Search for a standard using keywords

hit_collection = RelatonNist::NistBibliography.search("NISTIR 8200")
[relaton-nist] (NIST IR 8200) Fetching from csrc.nist.gov ...
[relaton-nist] (NIST IR 8200) Fetching from Relaton repository ...
=> <RelatonNist::HitCollection:0x00000000004b28 @ref=NIST IR 8200 @fetched=false>

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

XML serialization

item.to_xml
=> "<bibitem id="NISTIR8200" type="standard" schema-version="v1.2.8">
      <fetched>2023-10-16</fetched>
      <title format="text/plain" language="en" script="Latn">Interagency report on the status of international cybersecurity standardization for the internet of things (IoT)</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.8">
      <fetched>2023-10-16</fetched>
      <title format="text/plain" language="en" script="Latn">Interagency report on the status of international cybersecurity standardization for the internet of things (IoT)</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 SP 8200:2018) Fetching from csrc.nist.gov ...
[relaton-nist] (NIST IR 8200:2018) Fetching from Relaton repository...
[relaton-nist] (NIST IR 8200:2018) 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("NIST SP 800-205 (February 2019) (IPD)")
[relaton-nist] (NIST SP 800-205) Fetching from csrc.nist.gov ...
[relaton-nist] (NIST SP 800-205) Found: `NIST SP 800-205 (Draft)`
=> #<RelatonNist::NistBibliographicItem:0x00000001105afdc8
...

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 from csrc.nist.gov ...
[relaton-nist] (NIST SP 800-67r1) Found: `NIST SP 800-67 Rev. 1`
=> #<RelatonNist::NistBibliographicItem:0x00000001105acd08
...

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

item = RelatonNist::NistBibliography.get 'NIST SP 800-38A/Add'
[relaton-nist] (NIST SP 800-38A/Add) Fetching from csrc.nist.gov ...
[relaton-nist] (NIST SP 800-38A/Add) Found: `NIST SP 800-38A-Add`
=> #<RelatonNist::NistBibliographicItem:0x00000001105abf48
...

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

Typed links

NIST documents may have src and doi link types.

item.link
=> [#<RelatonBib::TypedUri:0x0000000111087a98
  @content=#<Addressable::URI:0x8c0 URI:https://csrc.nist.gov/pubs/sp/800/38/a/sup/final>,
  @language=nil,
  @script=nil,
  @type="src">,
 #<RelatonBib::TypedUri:0x00000001110879a8 @content=#<Addressable::URI:0x8d4 URI:https://doi.org/10.6028/NIST.SP.800-38A-Add>, @language=nil, @script=nil, @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).

nistbib

Development

Runtime

Relaton for NIST: bibliographic retrieval of NIST publications

Purpose

Data sources

Installation

Usage

Configuration

Search for a standard using keywords

XML serialization

Get code, and year

Get short citation

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

Typed links

Create bibliographic item from YAML

Fetch data

Development

Contributing

License