New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Attribute value registry #118

Open
Klortho opened this Issue Dec 1, 2015 · 10 comments

Comments

2 participants
@Klortho
Member

Klortho commented Dec 1, 2015

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:

@Klortho

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Dec 1, 2015

Member

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.

Member

Klortho commented Dec 1, 2015

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

This comment has been minimized.

Show comment
Hide comment
@hubgit

hubgit Dec 1, 2015

Member

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.
Member

hubgit commented Dec 1, 2015

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

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Dec 2, 2015

Member

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?

Member

Klortho commented Dec 2, 2015

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

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Dec 2, 2015

Member

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.

Member

Klortho commented Dec 2, 2015

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

This comment has been minimized.

Show comment
Hide comment
@Klortho
Member

Klortho commented Dec 2, 2015

@hubgit

This comment has been minimized.

Show comment
Hide comment
@hubgit

hubgit Dec 3, 2015

Member

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?

Member

hubgit commented Dec 3, 2015

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

This comment has been minimized.

Show comment
Hide comment
@hubgit

hubgit Dec 3, 2015

Member

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

Member

hubgit commented Dec 3, 2015

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

@Klortho

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Dec 3, 2015

Member

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

Member

Klortho commented Dec 3, 2015

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

@Klortho

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Dec 3, 2015

Member

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

Member

Klortho commented Dec 3, 2015

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

@Klortho

This comment has been minimized.

Show comment
Hide comment
@Klortho

Klortho Mar 31, 2016

Member

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

Member

Klortho commented Mar 31, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment