Proposal: harmonisation of `docid` field to combine `docnumber`, `id`, `docid`

[ronaldtse]

Due to the long discussions and resulting confusion and controversy around document identifiers in Relaton data (@strogonoff @opoudjis @andrew2net ), I propose we harmonise all of these identifier "things" under one field.

I would prefer having a docid array that has different types (and maybe scopes) of these identifiers.

• Relaton (@andrew2net) uses id for a unique reference within a dataset. That is actually a machine-readable identifier for generating filenames scoped unique within an authoritative source (publisher).

• Metanorma (@opoudjis ) uses docid with primary: true for dated references for displaying in citations, and manipulating them when necessary according to the type attribute.

• Metanorma (@opoudjis ) now needs an undated PubID for ISO to display on the ISO cover page.

• Metanorma (@opoudjis ) uses docnumber as a part of the PubID for some operations. I am unsure where exactly it is used. Most likely, it should be superseded by multiple forms of PubIDs.

• Metanorma IETF (@opoudjis ) uses the type: IETF; scope: anchor is used to generate the anchor for xml2rfc.

• BibXML Service (@strogonoff ) uses the docid with primary: true is used for uniquely identifying a bibliographic item (de-duplication) across all Relaton datasets.

Is this set of use cases accurate?

[strogonoff]

One note regarding docid:

• I believe, per discussed design, docid with primary=true is intended to denote an identifier the id of which is used by humans when referencing the bibliographic item (unambiguously, globally and uniquely).

(With that in mind, to me it doesn’t seem to make sense to display bibliographic items with the same primary ID as separate entities in the interface. So it was not really intended as a workaround for duplication, but as intended behavior that also happens to handle such possible duplication.)

[andrew2net]

• Relaton (@andrew2net) uses id for a unique reference within a dataset. That is actually a machine-readable identifier for generating filenames scoped unique within an authoritative source (publisher).

No, I don't use id. I use docid with primary: true and in some cases docnumber (for generating filenames)

[ronaldtse]

@andrew2net got it, then what is id for? No one uses it?

[strogonoff]

@andrew2net I was trying to say on the call, if you used docnumber for generating filenames then I-D versions would not have unique filenames… so it’s not docnumber, apparently

[andrew2net]

@ronaldtse I don't know. The id is in the grammar, so I've implemented it. Lets ask @opoudjis

[ronaldtse]

so it’s not docnumber, apparently

It's not, it seems that the filenames are constructed from another mechanism. I think the id should be a machine-readable ID.

[ronaldtse]

I've added the task for ISO and IETF here:

• Add ISO identifiers, dated, undated references and reference number to docid relaton-iso#107
• Add I-D identifiers, versioned and unversioned to docid relaton-ietf#74

This means we also have to do the same for all other document types: IEC, ITU, OGC, CIE, NIST, W3C, etc...

[andrew2net]

@andrew2net I was trying to say on the call, if you used docnumber for generating filenames then I-D versions would not have unique filenames… so it’s not docnumber, apparently

@strogonoff I use docnumber for generating filenames in some cases but not for I-D. Sorry for misinformation.

[ronaldtse]

While we're at dealing with docid, let's also consider the following:
relaton/relaton-nist@e18b5c6#r70684855

  <docidentifier type="NIST" primary="true">NIST IR 8011-1</docidentifier>
  <docidentifier type="DOI">10.6028/NIST.IR.8011-1</docidentifier>
  <docidentifier type="NIST" scope="anchor">NIST.IR.8011-1</docidentifier>

• type should be an enumerated value, so we should use lowercase. We also need documentation on what all these type values are.
• scope="anchor" was originally an IETF BibXML thing -- the use of the "anchor" is what we call the "reference tag" in ISO 690 -- a short handle for referring to a bibliographic item.

[strogonoff]

@ronaldtse

• I think using lowercase for “type” would help make it clear that it’s not publisher org abbreviation. If this changes, we’ll have to check if there are any dependencies on exact case-sensitive values though…
• For scope="anchor", BibXML service now uses it for constructing the anchor attribute on XML’s <reference>/<referencegroup> tags—let me know if we change key name (and if we change the values, then I’ll need to review the logic of how anchors are constructed in the service)

[ronaldtse]

• I think using lowercase for “type” would help make it clear that it’s not publisher org abbreviation. If this changes, we’ll have to check if there are any dependencies on exact case-sensitive values though…

Fully agree!

@strogonoff Can I confirm that we no longer need scope="anchor" in Relaton data. This will be a massive saver in non-IETF origin bibliographic items for @andrew2net .

[strogonoff]

@ronaldtse Will the anchor still be provided somewhere in data? In this shape: https://github.com/ietf-ribose/relaton-data-ids/blob/cd11648aa981ac87d781b8dac5598e0d56514940/data/draft-3k1n-6tisch-alice0-01.yaml#L18-L20

If not, let me know in advance, we’ll have to port corresponding these anchor formatting rules from wherever they are defined in Ruby and make them part of BibXML service Python codebase.

[ronaldtse]

@strogonoff a docid of scope anchor will be provided for IETF-sourced data, i.e. RFC, RFC subseries, I-Ds, IANA. No anchor will be provided for all other sources.

[ronaldtse]

@strogonoff if possible, I prefer to remove anchor everywhere because it is not technically part of bibliographic data.