How Can We Help?
Pure API: Working with Research output types (and subtypes in general)Pure API: Working with Research output types (and subtypes in general)
The Research output type is a bit special in the Pure API, because you will always work with one of its subtypes, and there is an implicit coupling with the "type" classification.
Let's first have a look at the OpenAPI3 schema for a definition of the allowed subtypes (Anything that is not relevant to this discussion has been removed):
ResearchOutput:
required:
- typeDiscriminator
type: object
properties:
typeDiscriminator:
type: string
type:
$ref: '#/components/schemas/ClassificationRef'
discriminator:
propertyName: typeDiscriminator
mapping:
BookAnthology: '#/components/schemas/BookAnthology'
ContributionToBookAnthology: '#/components/schemas/ContributionToBookAnthology'
ContributionToConference: '#/components/schemas/ContributionToConference'
ContributionToJournal: '#/components/schemas/ContributionToJournal'
ContributionToMemorandum: '#/components/schemas/ContributionToMemorandum'
ContributionToPeriodical: '#/components/schemas/ContributionToPeriodical'
Memorandum: '#/components/schemas/Memorandum'
NonTextual: '#/components/schemas/NonTextual'
OtherContribution: '#/components/schemas/OtherContribution'
Patent: '#/components/schemas/Patent'
Thesis: '#/components/schemas/Thesis'
WorkingPaper: '#/components/schemas/WorkingPaper' |
From this we can see that Research output has a number of subtypes (the discriminator section), and in practice you would always be using one of these and not the "abstract" ResearchOutput object. Any of the subtypes will include all properties from the Researchoutput object, as an example here is the relevant parts of the BookAnthology definition:
BookAnthology:
required:
- category
- contributors
- language
- managingOrganization
- publicationStatuses
- title
- type
type: object
description: "Books, reports and anthologies/collected works where the author(s)\
\ are responsible for the entire work."
allOf:
- $ref: '#/components/schemas/ResearchOutput'
- type: object
properties:
commissioningBody:
$ref: '#/components/schemas/ExternalOrganizationRef'
|
The "allOf" construct specifies that the BookAnthology object is composed of the definition of the ResearchOutput object in addition to its own definition, which starts with the "- type: object" section.
If you use a generated webservice client this will typically be handled for you through the programming language' inbuilt inheritance mechanisms if it supports that.
In Pure there is a coupling between the structural subtype of ResearchOutput and the chosen value of the "type" classification property. The allowed values of this value set is defined in the "allowed-types" helper method on the "research-output" endpoint which will return a list of "Classification" objects that can be used to build the "ClassificationRef" object that the property expects. In practice the "uri" property is used as a natural key for the classification. Here is the definition of the ClassificationRef and a sample output from the "allowed-types" operation:
ClassificationRef:
required:
- uri
type: object
properties:
uri:
type: string
description: Classification URI of the referred classification |
{
"classifications": [
{
"uri": "/dk/atira/pure/researchoutput/researchoutputtypes/bookanthology/book",
"term": {
"en_US": "Book",
"da_DK": "Bog",
"nl_NL": "Boek"
}
},
{
"uri": "/dk/atira/pure/researchoutput/researchoutputtypes/bookanthology/anthology",
"term": {
"en_US": "Anthology",
"da_DK": "Antologi",
"nl_NL": "Anthologie"
}
},
{
"uri": "/dk/atira/pure/researchoutput/researchoutputtypes/bookanthology/commissioned",
"term": {
"en_US": "Commissioned report",
"da_DK": "Rekvireret rapport",
"nl_NL": "Opgedragen rapport"
}
}
]
} |
The Research output type classification uri's are hierarchical, so here I've shown the three allowed values for bookanthology. The token after "researchoutputtypes" indicates the structural type, in this case "bookanthology" which corresponds to the "BookAnthology" type, the last part is a semantic specialization that doesn't have a direct structural impact. The Pure API will validate that a valid type classification is submitted on save.
Published at December 12, 2024