JATS4M: spec for <element-citation> #238
Comments
|
There are some journals that do not specify the article title in the references. Some of these mandatory elements may should not be mandatory. Eg: http://www.scielo.br/scielo.php?script=sci_arttext&pid=S0100-40422016000300267&lng=en&nrm=iso&tlng=pt |
|
@fabiobatalha is this more a legacy problem? Or are there good reasons not to specify an article title? Making article-title an optional field is possible but I would assume that in most cases when it is empty this is by accident and then we should warn the user? |
|
@michael There are no good reasons not to specify an article title, but this is our reality. It is not a legacy problem, it could be described as a cultural issue, a standard (bad or good) used by some journals or knowledge areas, etc. I'm not sure it is a common behavior. What I know is, we still have to deal with this kind of issues with our journals/editors. This is the newest issue of a journal (http://www.scielo.br/scielo.php?script=sci_arttext&pid=S0100-40422017000600706&lng=en&nrm=iso&tlng=pt). I don't know if our colleagues have the same issue in their collections. |
|
@fabiobatalha eLife has produced some Schematron that enforce some pretty strict rules for eLife: We'd love for this schematron to be used by more people so we can collectively help increase quality of references - we're using it in the production process, so authors can be queried for missing data before final delivery and publication. We've also reviewed our archive and come up with a list of 12 different @publication-type. In addition to the tags you have listed for publication-type="journal", we'd add:
Book (publication-type="book")
Some more to be added: Data (publication-type="data")
I won't list out all the requirements in this ticket as I can point you to the info if decided it is of use. These are the rest of our reference types: |
|
Hello @Melissa37, We also have a schematron (https://github.com/scieloorg/packtools) to validate XML files against SciELO PS rules. We will look your schematron to check if we can use some of your validations. Our reference types allowed are:
I will ask @gustavofonseca to check your schematron and find the differences and similarities between our schematron and yours. So we can set the common rules between both. I believe it could be our first requirements for Texture references metadata. After that we may discuss together to try to mitigate the diferences between both schematrons. Defining a base standard for this consortium. Thoughts? |
|
Hi there That sounds like a great idea, thanks. |
|
Schematron produced by SciELO deals with a very specific use case that is to validate the XML representation structure of an article that has already gone through the editorial process. As far as I can see -- @Melissa37 correct me if I am wrong -- the use case of eLife is different and more convenient for the application of strict rules regarding the minimum set of metadata of the bibliographic references as there is the direct interaction with the author Of the article. I believe that the Schematron pointed out by @Melissa37 will be very useful when SciELO happens to interact directly with the authors, but I do not think it will replace our need for more relaxed schemes for the case I mentioned earlier. |
|
@Melissa37 @fabiobatalha great input, thank you! I'm already working on getting journal + book pubtypes implemented. regarding |
Can you give an example? I don't like that we'd have two different values. This would complicate the user interface (two input fields). Still not sure I understand... what would 2007a mean? :) |
@Melissa37 can you give an example for group authors with a collab element present in person group? Not sure yet how we want to model this in Texture. |
|
Any objections on making surname and given-names required fields? |
|
@michael regarding pub-id with @pub-id-type of doi or pmid: I guess this is only valid for LifeScience journals? |
|
@gustavofonseca re: I believe that the Schematron pointed out by @Melissa37 will be very useful when SciELO happens to interact directly with the authors, but I do not think it will replace our need for more relaxed schemes for the case I mentioned earlier. |
|
@michael we'd request an @iso-8601-date on the year - this allows publishers to list a,b,c suffixes on dates within the field (where it's the same authors and date for multiple refs) and allowing a proper date to still be machine readable. Ref List: In-text citation: We use Harvard referencing style - name and year, not number (Vancouver)(http://site.uit.no/english/writing-style/citationstyles/). |
|
@michael Is this what you mean?: Or is this linked to: |
|
@michael Any objections on making surname and given-names required fields? |
|
@michael Any objections on making surname and given-names required fields? |
|
@Melissa37 I've modelled book and journal mostly after your guidelines. They were really helpful! I wanted to ask if we could move on and specify all the 12 pub types you use at eLife so we can work towards having them signed off by each party. You think you could translate each of the pub types into a formal spec like this one for That would great! :) |
|
HI Michael Sure I can do this - do I have a deadline/ :-) Also, we are very strict so @gustavofonseca might want to edit it! |
|
No hard deadline. :) Starting out strict is always good and then we have each org go through it and sign it off. Let's try to seek for the best possible solution and consider making updates to the existing guidelines. We will all benefit from a uniform tagging style for element-citations in the long run! Thank you very much for helping @Melissa37 ! |
|
@Melissa37 maybe you could also specify an HTML rendering template for each pub type (see ' HTML Preview in Texture ' above). We need that to have a preview in Texture when we display the refs in the reference list at the end of the document. |
publication-type="software"
person-group[person-group-type='author'], person-group[person-group-type='curator']
data-title, year, source?, version?, publisher-loc?, publisher-name?, ext-link[ext-link-type="uri"]?publication-type="preprint"
person-group[person-group-type='author'],
article-title, source, year, ext-link[ext-link-type="uri"]?, pub-id[pub-id-type='doi']?publication-type="clinicaltrial"
person-group, year, article-title, ext-link[ext-link-type="uri"], source?publication-type="confproc"
person-group[person-group-type='author'],
article-title, year, ext-link[ext-link-type="uri"], conf-name, source?, fpage?, lpage?, page-range?, elocation-id?, pub-id[pub-id-type='doi']?publication-type="data"
person-group[person-group-type='author'],
data-title, year, source, pub-id[pub-id-type="accession, ark, doi, archive"]
ext-link[ext-link-type="uri"]?, pub-id[assigning-authority="XXX"]?publication-type="patent"
person-group[person-group-type='inventor'],
article-title, year, source?, patent country,
ext-link[ext-link-type="uri"], person-group[person-group-type='assignee']publication-type="periodical"
string-date, person-group, article-title, source, fpage, lpage, volume?publication-type="report"
person-group, source, year, publisher-name, publisher-loc?, pub-id[pub-id-type='isbn']?publication-type="thesis"
person-group, year, article-title, publisher-name, publisher-loc?, pub-id[pub-id-type='doi']?, ext-link[ext-link-type="uri"]?publication-type="web"
person-group, article-title, date?, ext-link[ext-link-type="uri"],date-in-citation, publisher-loc?, source? |
|
@michael regarding HTML Preview in Texture - it is so subjective and there are so many different styles and people seem to really care (whereas I personally don't!). Only comment on journal - vol not issue please (or both) book
${source} (${edition}). ${editors}, editors. (${year}) ${publisher-loc}: ${publisher}.
|
|
Thanks so much for taking the time to put this together @Melissa37. Now we have something to start with! Please add your comments everyone! |
|
Ah, I see now! Thanks! Please ignore the second one! |
|
A preview of the required data for each reference type. It seems the publication-types used by SciELO and eLife are totally compatible, we will provide the pattern for legal-doc and newspaper.
|
|
Thanks for writing this up @fabiobatalha! Starting now with implementing this. :) Using this table as the official spec. Thanks! Oh, only one question to @fabiobatalha and @Melissa37: Instead of |
|
Thanks @fabiobatalha. The DataCite implementation is pretty close to this. Some of the questions I have include:
|
|
Agree with @mfenner on having month + day available everywhere as an optional field. Also would like to get rid of ext-link. I will make changes in table (in the issue text) so it reflects the |
|
|
What is |
|
date-in-citation is the date you visited the web page. |
|
Ah didn't first spot it in the JATS spec. I'm not sure we should use that tag, as it seems to be there for some visual clues (like freeform text such as "updated on March 23 2017"). If we captured that semantically with year+month+day (all required) we could use the same structure as in the other elements. Do we need multiple dates? Like updated-at and accessed-on? Maybe accessed-on is enough? Hard to proof when a website actually has been updated anyways. I'm sure how to deal with |
|
@michael |
|
I will make a few decisions (will change the spec in the issue text) so I can come up with an initial implementation fast. We can then start a round of user testing and adjust things were needed. All ok with that? |
|
@Melissa37 do you have one or two elife examples for the |
|
@Melissa37 (sorry for the email flood...) For patents JATS suggests using the collab element like so |
|
I've added examples to the Texture kitchen sink file (one per publication type): https://github.com/substance/texture/blob/ref-editing/data/kitchen-sink.xml#L133-L373 Please review and suggest changes via "Edit file on Github". |
|
Hi, Currently at Erudit we do not finely tag citations, we separate each citation, but the citation itself is a text string. Though we’re willing to implement a better tagging in near future, you're way farther than us into the reflexion surrounding the tagging of citations, both with the publication types and the fine tagging of these different types of citation. At Erudit, we do not deal directly with the authors and can’t impose a citation style on them. The citations we have to process may sometimes be incomplete (no given-names, no title, etc.), we have no control over it, we mark the reference as they are in the source files. We don’t clean/edit/complete citations to make the citations valid. Knowing this, our needs are more oriented toward greater flexibility. Thus, we are of the opinion that everything in the element-citation tag must be optional. Also, it seems important to us to preserve the possibility of being able to include untagged text in citations, something that the element-citation tag does not allow (but allowed in the mixed-citation tag which seems to be also permitted in JATS4R). The support of mixed-citation tag in Texture and the UX of choosing between mixed-citation and element-citation might be discussed in a dedicated issue |
|
About the publication ID, What is suggested here (DOI, ISBN, PMID,PMCID) covers our needs. |
|
About iso-8601 (date). The use of an iso-8601 covers our needs, especially if it allow a, b, c suffixes on dates. Since we think everything should be optional, we are OK with having month and day available for every type of publication as an option field. |
|
Sorry, long entry - catch up: @michael RE: Oh, only one question to @fabiobatalha and @Melissa37: Instead of ext-link could we use the uri tag? It would be more consistent to use ext-link only within text elements, not in structured elements such as element-citation.
@michael re date-in-citation - we require this and a publication date currently, but I think I agree that the publication date is ambiguous - is it the original page published date, or most recent update? Regarding software citations - I have a concern that to simplify things the software citations will go down a different route to what the data citations working group went down and will change the use/meaning of tags used, so in the larger picture will be less useful. I would be happy to review data and software citations together to try and keep them in synch. @michael re I'm sure how to deal with pub-id[assigning-authority="XXX"] would be easier to come up with a list of supported assigning authorities rather than letting the user enter something here? Shouldn't we just use a pub-id[type=doi] here instead. Hard to support any kind of id provider, and we will never be done. :/ @michael RE do you have one or two elife examples for the periodical pubtype? Wonder if we could avoid using string-date there. <ref id="bib40">
<element-citation publication-type="periodical">
<person-group person-group-type="author">
<name>
<surname>Schwartz</surname>
<given-names>J</given-names>
</name>
</person-group>
<string-date><month>September</month> <day>9</day>, <year iso-8601-date="1993-09-09">1993</year></string-date>
<article-title>Obesity affects economic, social status</article-title>
<source>The Washington Post</source>
<fpage>A1</fpage>
<lpage>A4</lpage>
</element-citation>
</ref>Yes I agree re avoiding string date - we're using it for presentation only. @michael Re: For patents JATS suggests using the collab element like so Hospira, Inc.. In your spec there's a person-group[person-group-type=assignee] used. Not sure which one is better, would need to see some real eLife examples for patents Below's an example from eLife. I guess we went with person group to keep in in the same structure as the "inventor". I guess there can only be one assignee, where as there could be multiple inventors? I am not sure! We did not have any examples or other evidence so went with our basic structure which is to put everyone/org into a person-group @pigeonm RE The support of mixed-citation tag in Texture and the UX of choosing between mixed-citation and element-citation might be discussed in a dedicated issue |
michael
changed the title
|
@pigeonm thank you for your update! I think we could solve this by providing a Do you have time to do a conference call with Oliver and I so we can better assess the requirements of Erudit for references and affiliations? @Melissa37 thanks for your update too. Will answer when I get time! |
|
I think the publication-type is more related to the type of the citation rather than the XML structure inside the element-citation. Creating a publication-type=raw could bring misinterpretations regarding to the meaning of this attribute. Maybe in the Erudit case it should be important to have at least the meaning/type of the bibliographic reference content. SciELO deal with the element-citation and mixed-citation in a combined way, where the element-citation have the structured data and mixed-citation have the citation in the way it was written by the author. Of course, this scenario deals with the content already produced by the author without texture and could also be considered a hacking of the JAT's structure to deal with a SciELO internal detail of implementation. So maybe we could find another approach to deal with untagged references. ex: <ref-list>
<ref id="B01">
<label>1</label>
<mixed-citation>ARRETCHE, M. Federalism and territorial equality: a contradiction in terms? Dados, Rio de Janeiro, v. 5, n. 02, 2010 . Disponível em: <http://socialsciences.scielo.org.</mixed-citation>
<element-citation publication-type="journal">
<person-group person-group-type="author">
<name>
<surname>ARRETCHE</surname>
<given-names>M</given-names>
</name>
</person-group>
<article-title>Federalism and territorial equality: a contradiction in terms?</article-title>
<source>Dados</source>
<publisher-loc>Rio de Janeiro</publisher-loc>
<volume>5</volume>
<issue>02</issue>
<year>2010</year>
<ext-link ext-link-type="uri" xlink:href="http://socialsciences.scielo.org">http://socialsciences.scielo.org</ext-link>
</element-citation>
</ref>
<ref-list>I agree with your point of view regarding to the meaning of the ext-link in references. For SciELO both solutions will work once we will need to produce the SciELO PS XML from the Texture XML. Now we are using the ext-link so it will be better for us, but not mandatory once it is feasible to convert from uri to ext-link. |
|
@fabiobatalha How do you see this working inside Texture ? Would it be required to always have the citation tagged both with |
|
One usage and implementation could be.
|
|
Thank you everyone for the fruitful discussions here. I've consolidated all the specification work into a single document: https://github.com/substance/texture/blob/master/docs/JATS4M.md I will close this issue now, as I think we created a good base. Please open new issues anytime if you have questions, suggestions how to improve the current spec. |
|
The document moved to substance/dar/DarArticle.md, I presume. |
<person-group><name>HTML Preview in Texture
journalbookchapter in booksoftwarepreprintclinicaltrialconfprocdatapatentperiodicalreportthesisThis spec will define what the Texture user interface will support for editing. Note that this spec is incomplete, please comment on what you would like to have included and why. I will update this issue according to your comments
The text was updated successfully, but these errors were encountered: