Skip to content

Working with research-output types (and subtypes in general)

The research-output type is a bit special in the Pure API, because you'll 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 (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 subtypes (the discriminator section), and in practice you'd 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 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 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.