V3 Swagger for funding, works & peer-review. Hiccups: 1 minor but widespread, 1 major, 1 weird.

147 views
Skip to first unread message

Jason

unread,
Jul 10, 2019, 12:17:58 AM7/10/19
to ORCID API Users

Hi all, further to "Issues we've encountered while migrating affiliations from V2.1 to V3.0"

 

Rob: Thanks for the pointer to https://trello.com/b/0RcSj7uQ/member-feedback, that was a pleasant discovery.

 

Re: standardisation of category values between xml and json messages? OK. Fair enough.  

 

And yes, the change notes should be something we explicitly review for new releases.

 

Where we're at: the team has just finished migration of works, funding, and peer review tasks to V3.0 and in the process have dealt with the following:

 

The minor:

 

No surprise that the V3_0 swagger is enumerating the values as the old underscore+uppercase -- c.f., the new required hyphen+lowercase -- in all elements and not just the affiliation elements that we dealt with earlier, i.e.:

 

FundingV3_0 { type enum: [ 'GRANT', 'CONTRACT', 'AWARD', 'SALARY_AWARD' ] , FundingContributorAttributesV3_0 { contributor-role enum: [ 'LEAD', 'CO_LEAD', 'SUPPORTED_BY', 'OTHER_CONTRIBUTION' ] } }

 

PeerReviewV3_0 { reviewer-role enum: [ 'REVIEWER', 'EDITOR', 'MEMBER', 'CHAIR', 'ORGANIZER' ] , review-type enum: [ 'REVIEW', 'EVALUATION' ] , subject-type enum: [ 'ARTISTIC_PERFORMANCE', 'BOOK_CHAPTER', 'BOOK_REVIEW', 'BOOK', 'CONFERENCE_ABSTRACT', 'CONFERENCE_PAPER', 'CONFERENCE_POSTER', 'DATA_SET', 'DICTIONARY_ENTRY', 'DISCLOSURE', 'DISSERTATION_THESIS', 'EDITED_BOOK', 'ENCYCLOPEDIA_ENTRY', 'INVENTION', 'JOURNAL_ARTICLE', 'JOURNAL_ISSUE', 'LECTURE_SPEECH', 'LICENSE', 'MAGAZINE_ARTICLE', 'MANUAL', 'NEWSLETTER_ARTICLE', 'NEWSPAPER_ARTICLE', 'ONLINE_RESOURCE', 'OTHER', 'PATENT', 'PREPRINT', 'REGISTERED_COPYRIGHT', 'REPORT', 'RESEARCH_TECHNIQUE', 'RESEARCH_TOOL', 'SOFTWARE', 'SPIN_OFF_COMPANY', 'STANDARDS_AND_POLICY', 'SUPERVISED_STUDENT_PUBLICATION', 'TECHNICAL_STANDARD', 'TEST', 'TRADEMARK', 'TRANSLATION', 'WEBSITE', 'WORKING_PAPER', 'UNDEFINED' ] }

 

WorkV3_0 { type enum: [ 'ARTISTIC_PERFORMANCE', 'BOOK_CHAPTER', 'BOOK_REVIEW', 'BOOK', 'CONFERENCE_ABSTRACT', 'CONFERENCE_PAPER', 'CONFERENCE_POSTER', 'DATA_SET', 'DICTIONARY_ENTRY', 'DISCLOSURE', 'DISSERTATION_THESIS', 'EDITED_BOOK', 'ENCYCLOPEDIA_ENTRY', 'INVENTION', 'JOURNAL_ARTICLE', 'JOURNAL_ISSUE', 'LECTURE_SPEECH', 'LICENSE', 'MAGAZINE_ARTICLE', 'MANUAL', 'NEWSLETTER_ARTICLE', 'NEWSPAPER_ARTICLE', 'ONLINE_RESOURCE', 'OTHER', 'PATENT', 'PREPRINT', 'REGISTERED_COPYRIGHT', 'REPORT', 'RESEARCH_TECHNIQUE', 'RESEARCH_TOOL', 'SOFTWARE', 'SPIN_OFF_COMPANY', 'STANDARDS_AND_POLICY', 'SUPERVISED_STUDENT_PUBLICATION', 'TECHNICAL_STANDARD', 'TEST', 'TRADEMARK', 'TRANSLATION', 'WEBSITE', 'WORKING_PAPER', 'UNDEFINED' ] , citation enum: [ 'FORMATTED_UNSPECIFIED', 'BIBTEX', 'FORMATTED_APA', 'FORMATTED_HARVARD', 'FORMATTED_IEEE', 'FORMATTED_MLA', 'FORMATTED_VANCOUVER', 'FORMATTED_CHICAGO', 'RIS' ] , ContributorAttributesV3_0 { contributor-sequence enum: [ 'FIRST', 'ADDITIONAL' ], contributor-role enum: [ 'AUTHOR', 'ASSIGNEE', 'EDITOR', 'CHAIR_OR_TRANSLATOR', 'CO_INVESTIGATOR', 'CO_INVENTOR', 'GRADUATE_STUDENT', 'OTHER_INVENTOR', 'PRINCIPAL_INVESTIGATOR', 'POSTDOCTORAL_RESEARCHER', 'SUPPORT_STAFF' ] } }

 

and

 

Common { visiblity enum: [ 'LIMITED', 'REGISTERED_ONLY', 'PUBLIC', 'PRIVATE' ] , ExternalIDV3_0 { external-id-relationship enum: [ 'PART_OF', 'SELF', 'VERSION_OF' ] } }

 

The major:

 

The Amount/Currency element in the Funding V3_0 model is broken.  The model shows, 

 

FundingV3_0 {

AmountV3_0 {

value (string, optional),

currency-code ( Currency )

}

}

 

and where Currency is its own element: 

 

Currency {

currencyCode (stringoptional),

defaultFractionDigits (integeroptional),

numericCode (integeroptional),

displayName (stringoptional),

symbol (stringoptional)

 

Posting this structure throws an error:  

 

{  "response-code": 400,  "developer-message": "400 Bad request: invalid JSON - Cannot deserialize instance of `java.lang.String` out of START_OBJECT token\n at [Source: (org.apache.catalina.connector.CoyoteInputStream); line: 19, column: 22] (through reference chain: org.orcid.jaxb.model.v3.release.record.Funding[\"amount\"]->org.orcid.jaxb.model.v3.release.common.Amount[\"currency-code\"])",  "user-message": "Invalid JSON.",  "error-code": 9047,  "more-info": "https://members.orcid.org/api/resources/troubleshooting"}

 

Because what the model is appears to be expecting is the much simpler structure from V1.2 - V2.1, i.e, a model of:

 

FundingV3_0 {

AmountV3_0 {

value (string, optional),

currency-code (string)

}

}

 

At least posting with "amount":{"value":"500000", "currency-code":"NZD"} as part of a message to /V3.0/{orcid}/funding is successful.


The weird:


Between V3.0_rc1 and V3.0_rc2, media-type seems to have been silently dropped from publication-date so that with V3.0, works can no longer record publication dates for different media versions of the same document.  This doesn't appear to be in any change notes that we can find.  


Is this intended?  As recording different dates, e.g., for online and print publication of an article, seems like a reasonable use knowing why this was removed would be useful.

 

Finally

 

It's good to know that these issues are being thought about as with the current situation we're having to warn our Member's developers away from using the OpenAPI Spec for anything other the Swagger UI toy.  That's a real shame as it's should be a tool to reduce a lot of the pain of integration.

 

Best wishes, 

Rad, Roshan, and Jason.

 

 

Wilmers, Catalina

unread,
Jul 10, 2019, 2:02:12 PM7/10/19
to Jason, ORCID API Users
Hi Jason,

The funding structure is being incorrectly interpreted by Swagger. We continue to support a value and currency code as we did with 2.1/2.0. We'll fix the swagger markup to make the model reflect this.

The media-type on publication date was never actually supported. The field was a legacy in the schema that missed our purge of other legacy data in 2.0. We've never supported including a media-type with the date and are not set up to handle it and because it was never used we didn't mention it on our change list. If you have a use case where having media type with a date is important we can consider it as part of our member feedback process.

Finally, you raise a good point about to what level we are supporting Swagger- it's started a discussion with our team about how we should continue to support it. Thanks for the feedback!

-Catalina

--
You received this message because you are subscribed to the Google Groups "ORCID API Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to orcid-api-use...@googlegroups.com.
To post to this group, send email to orcid-a...@googlegroups.com.
Visit this group at https://groups.google.com/group/orcid-api-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/orcid-api-users/7137cd91-1700-4883-ae22-17576e64a174%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply all
Reply to author
Forward
0 new messages