Attribute value registry

[Klortho]

This was discussed at the last telecon (12 Nov 2015). The idea is that the JATS4R group could implement and host a simple registration system for values for some of the attributes in JATS. In the telecon, we agreed that this would be in the purview of JATS4R, since the proper interpretation of attributes is related to reuse and interchange.

For an example of the motivation, consider the recent email discussion about tagging clinical trial info. It was suggested to use <related-object object-id-type=“clinical-trial” ...>. It would be nice if there were a centralized place where attribute values could be agreed upon, with a clear description of how they are to be interpreted.

There are some comments on the NISO site related to this:

• extend pub-id-type values
• Derestrict pub-id-type= in NISO Publishing JATS DTD
• Tokenized attributes in Publishing; followup
• CRediT taxonomy for @person-group-type

[Klortho]

Here's a proposed sketch of what it could look like:

View: Landing page

Title: "JATS Attribute Values"

The body would be an accordion-style list of all of the names of the attributes, e.g.

> abbrev-type          (+)
> fig-type                (+)
> fn-type                (+)
> ...

Clicking any of those headers would expand that section, with a list of all of the registered values. For example, clicking "fig-type" would expand to a table something like this:

Value             Description                                Provenance
chart              This figure is a chart ...             JATS Tag Library
map               A geographical map ...             JATS Tag Library
3d-molecule  Stereo image of a molecule     Proposed by Chemical Society of America

There would be a control at the top to allow the user to switch between displaying all of the values (including proposed), or just the approved ones.

Clicking a (+) button next to the attribute name takes the user to a form to propose a new value

View: Propose new attribute value

This is a form, with the fields:

• Value - this would enforce the conventions (lowercase, hyphens, no spaces, etc.)
• Description - as it would appear in the value list
• More info - comments the submitter could offer to our group, to help us understand what this is for
• Your name
• Organization
• Email (will not be displayed) - used by us to respond to the submitter.
• Email (again, for confirmation)

API

It would be important to provide a very simple API to allow retrieval of the data in JSON format. Maybe also some other formats (like schematron?) so that it could be easily integrated with a validator.

Other notes

I think, to start, we wouldn't need any user authentication. Just let the submitter give us his/her email. Anyone can submit a suggestion. Maybe we'd need a captcha, if it started to get abused.

At first, I was thinking this could be done using a YAML file inside one of our GitHub repos, but if we want the user's email to remain confidential, then we'd need something else. From my point of view, the simplest thing to implement would probably be a Django app.

[hubgit]

The microformats wiki is one example of a similar process, used to manage the list of valid link[rel] values in HTML.

• The Formats table contains the list of values defined in specifications, and the HTML5 link extensions table lists values that are in use - this is where people who would like to see a value added to the registry can add the new value & supporting documentation. Both of these tables are used to populate the validator's whitelist.
• The Dropped table contains values that should not be used.

[Klortho]

Oh, this is a great idea -- we can just use jats wiki. That makes things quite a bit simpler -- I think we'd just need a cron job or mediawiki hook to convert the table into json format.

Any objections?

[Klortho]

Okay, I got a proof-of-concept working. Tell me what you think.

The JATS wiki has a new page, Attribute values, that anyone with an account can edit. Account creation is by approval, only, so that takes care of the potential problem of spam.

I put some seed material in that page from the JATS spec, for two sample attributes: abstract-type and article-type. The table headers, and everything else, really, is up for discussion -- let me know if you want to change anything.

I also added some instructions there to tell people how to propose new values.

Then, I wrote a quick-and-dirty CGI that uses the mediawiki api (specifically, this request) to get the latest page contents, and parse it into JSON. The results are here.

Using that CGI, we could turn the mediawiki into a nicer HTML page, or convert it into other formats to make it easy to integrate into a validator.

Again, this is proof-of-concept, so I didn't implement any error checking or anything. If there are problems with the wikitext, the CGI will fail.

[Klortho]

Here's the cgi

[hubgit]

Looks good. It might perhaps be easier to parse the final HTML tables when generating the JSON for the validator, rather than the wikitext via the API?

[hubgit]

Here's code to parse the tables - not sure if it's easier :)

[Klortho]

As discussed in the telecon this morning, this should include @assigning-authority

[Klortho]

Question: should this also include a table for licence URIs? (See the validator issue #29).

[Klortho]

I will try to have some more work done on this before jatscon.