How Can We Help?
Working with research-output types (and sub-types in general)Working with research-output types (and sub-types in general)
The research-output type is a bit special in the Pure API, because you'll always work with one of its sub-types, 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 sub-types (I've removed anything that isn't relevant to this discussion):
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 sub-types (the discriminator section), and in practice you'd always be using one of these and not the "abstract" ResearchOutput object. Any of the sub-types will include all properties from the ResearchOutout 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 web-service 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 sub-type 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.
Updated at October 03, 2024