swagger.yaml

openapi: 3.0.0
components:
  securitySchemes:
    basicLogin:
      type: http
      scheme: basic
  schemas:
    nameType:
      type: object
      properties:
        full_name:
          description: The name of an organization.
          type: string
          maxLength: 1000
        last_name:
          description: 'For persons, the last or family name.'
          type: string
          maxLength: 100
        first_name:
          description: 'For persons, the first or given name.'
          type: string
          maxLength: 500
        middle_name:
          description: 'For persons, the middle name or initial.'
          type: string
          maxLength: 50
        email:
          description: An email used for contacting this organization or individual.
          type: string
          format: email
          maxLength: 640
        orcid:
          description: 'The ORCID identifying this particular person, author or contributor.'
          type: string
          maxLength: 20
        affiliations:
          description: List any affiliations or labs this person is associated with.
          type: array
          items:
            type: string
            maxLength: 250
      anyOf:
        - required:
            - full_name
        - required:
            - last_name
            - first_name
    contributorType:
      allOf:
        - $ref: '#/components/schemas/nameType'
        - properties:
            contributor_type:
              description: The type of contribution made for this person or organization.
              $ref: '#/components/schemas/contributorTypes'
          required:
            - contributor_type
    date:
      type: string
      anyOf:
        - format: year
        - format: yearmonth
        - format: date
        - format: datetime
    productTypes:
      type: string
      description: The general type of the work, report, or document for this record.
      enum:
        - Audiovisual
        - Collection
        - Dataset
        - Event
        - Image
        - InteractiveResource
        - Model
        - PhysicalObject
        - Service
        - Software
        - Sound
        - Text
        - Workflow
        - Other
    identifierTypes:
      type: string
      description: The type of identifier represented by this value.
      enum:
        - ARK
        - arXiv
        - bibcode
        - DOI
        - EAN13
        - EISSN
        - Handle
        - IGSN
        - ISBN
        - ISSN
        - ISTC
        - LISSN
        - LSID
        - PMID
        - PURL
        - UPC
        - URL
        - URN
        - w3id

    contributorTypes:
      type: string
      description: |
        Describes the type of contribution to the work.
        |code|description|
        |----|-----------|
        |ContactPerson|Person with knowledge of how to access, troubleshoot, or otherwise field issues related to the resource.|
        |DataCollector|Person/institution responsible for finding or gathering data under the guidelines of the author(s) or Principal Investigator.|
        |DataCurator|Person tasked with reviewing, enhancing, cleaning, or standardizing metadata and the associated data submitted.|
        |DataManager|Person (or organisation with a staff of data managers, such as a data centre) responsible for maintaining the finished resource.|
        |Distributor|Institution tasked with responsibility to generate/disseminate copies of the resource in either electronic or print form.|
        |Editor|A person who oversees the details related to the publication format of the resource.|
        |HostingInstitution|The organisation allowing the resource to be available on the internet.|
        |Producer|Typically a person or organisation responsible for the artistry and form of a media product.|
        |ProjectLeader|Person officially designated as head of project team instrumental in the work necessary to development of the resource.|
        |ProjectManager|Person officially designated as manager of a project. Project may consist of one or many project teams and sub-teams.|
        |ProjectMember|Person on the membership list of a designated project/project team.|
        |RegistrationAgency|Institution officially appointed by a Registration Authority to handle specific tasks within a defined area of responsibility.|
        |RegistrationAuthority|A standards-setting body from which Registration Agencies obtain official recognition and guidance.|
        |RelatedPerson|Person with no specifically defined role in the development of the resource, but who is someone the author wishes to recognize.|
        |Researcher|A person involved in analyzing data or the results of an experiment or formal study.|
        |ResearchGroup|Refers to a group of individuals with a lab, department, or division; the group has a particular, defined focus of activity.|
        |RightsHolder|Person or institution owning or managing property rights, including intellectual property rights over the resource.|
        |Sponsor|Person or organisation that issued a contract or under the auspices of which a work has been performed.|
        |Supervisor|Designated administrator over one or more groups working to produce a resource or over one or more steps of development process.|
        |WorkPackageLeader|A Work Package is a recognized data product, not all of which is included in publication.|
        |Other|Any person or institution making a significant contribution, but whose contribution does not "fit".|
      enum:
        - ContactPerson
        - DataCollector
        - DataCurator
        - DataManager
        - Distributor
        - Editor
        - HostingInstitution
        - Producer
        - ProjectLeader
        - ProjectManager
        - ProjectMember
        - RegistrationAgency
        - RegistrationAuthority
        - RelatedPerson
        - Researcher
        - ResearchGroup
        - RightsHolder
        - Sponsor
        - Supervisor
        - WorkPackageLeader
        - Other

    relationTypes:
      type: string
      description: |
        Indicates the relationship between this identifier and the source record.
        |code|description|
        |----|-----------|
        |Cites|indicates that A includes B in a citation|
        |Compiles|indicates B is the result of a compile or creation event using A|
        |Continues|indicates A is a continuation of the work B|
        |Describes|indicates A describes B|
        |Documents|indicates A is documentation about/B|
        |HasMetadata|indicates resource A has additional metadata B|
        |HasPart|indicates A includes the part B|
        |HasVersion|indicates A has a version of B|
        |IsCitedBy|indicates that B includes A in a citation|
        |IsCompiledBy|indicates B is used to compile or create A|
        |IsContinuedBy|indicates A is continued by the work B|
        |IsDerivedFrom|indicates B is a source upon which A is based|
        |IsDescribedBy|Indicates A is described by B|
        |IsDocumentedBy|indicates B is documentation about/explaining A|
        |IsIdenticalTo|indicates that A is identical to B, for use when there is a need to register two separate instances of the same resource|
        |IsMetadataFor|indicates additional metadata A for a resource B|
        |IsNewVersionOf|indicates A is a new edition of B, where the new edition has been modified or updated|
        |IsObsoletedBy|Indicates A is replaced by B|
        |IsOriginalFormOf|indicates A is the original form of B|
        |IsPartOf|indicates A is a portion of B; may be used for elements of a series|
        |IsPreviousVersionOf|indicates A is a previous edition of B|
        |IsReferencedBy|indicates A is used as a source of information by B|
        |IsRequiredBy|inidcates A is required by B|
        |IsReviewedBy|indicates that A is reviewed by B|
        |IsSourceOf|indicates A is a source upon which B is based|
        |IsSupplementTo|indicates that A is a supplement to B|
        |IsSupplementedBy|indicates that B is a supplement to A|
        |IsVariantFormOf|indicates A is a variant or different form of B, e.g. calculated or calibrated form or different packaging|
        |IsVersionOf|indicates A is a version of B|
        |Obsoletes|Indicates A replaces B|
        |References|indicates B is used as a source of information for A|
        |Requires|indicates A requires B|
        |Reviews|indicates that A is a review of B|

      enum:
        - IsDescribedBy
        - Describes
        - HasVersion
        - IsVersionOf
        - IsRequiredBy
        - Requires
        - Obsoletes
        - IsObsoletedBy
        - IsCitedBy
        - Cites
        - IsSupplementTo
        - IsSupplementedBy
        - IsContinuedBy
        - Continues
        - HasMetadata
        - IsMetadataFor
        - IsNewVersionOf
        - IsPreviousVersionOf
        - IsPartOf
        - HasPart
        - IsReferencedBy
        - References
        - IsDocumentedBy
        - Documents
        - IsCompiledBy
        - Compiles
        - IsVariantFormOf
        - IsOriginalFormOf
        - IsIdenticalTo
        - IsReviewedBy
        - Reviews
        - IsDerivedFrom
        - IsSourceOf

    recordType:
      type: object
      description: Represents the metadata information about a particular work, document, dataset, or
        paper for a given DOI record.
      properties:
        id:
          description: >-
            Unique identifier for this record for edit purposes. Do not provide for
            new records.
          type: integer
        title:
          description: 'Title of the work, data set, or product.'
          type: string
          maxLength: 500
        sponsoring_organization:
          description: Name of the primary sponsoring organization.
          type: string
          maxLength: 400
        research_organization:
          description: Name of the primary research organization.
          type: string
          maxLength: 400
        accession_number:
          description: >-
            Indicate a client-specific unique identifier if any in your own system.
            May be used in place of specifying ID in future edits if desired.
          type: string
          maxLength: 100
        doi:
          description: >-
            DOI value associated with this record.  Omit for new records to obtain
            initial value.
          type: string
          maxLength: 100
        doi_infix:
          description: Optional DOI infix value used in initial construction of the DOI value.
          type: string
          maxLength: 60
        language:
          description: Primary language of the work.
          type: string
          maxLength: 255
        report_numbers:
          description: Any primary identifying numbers associated with the work.
          type: string
          maxLength: 250
        contract_numbers:
          description: Any contract or award numbers associated with the work.
          type: string
          maxLength: 250
        other_numbers:
          description: Any additional identifying numbers associated with the work.
          type: string
          maxLength: 250
        publisher:
          description: Publisher of the record.
          type: string
          maxLength: 1000
        availability:
          description: >-
            Description of the document's availability, any restrictions on use or
            other information pertinent to its dissemination.
          type: string
          maxLength: 1000
        publication_date:
          description: The date of publication of this information.
          type: string
          format: date
        country:
          description: The country of publication for this work.
          type: string
          maxLength: 1000
        description:
          description: Abstract or description for this work.
          type: string
        site_url:
          description: >-
            The URL to the landing page of this publication, or direct to its full
            text.
          type: string
          format: uri
          maxLength: 250
        product_type:
          description: >-
            Used to specify the type of information contained in this record, one of
            the indicated required values.
          $ref: '#/components/schemas/productTypes'
        product_type_specific:
          description: >-
            Describes the product type in more general terms, to further explain the
            type of information contained within the record.
          type: string
          maxLength: 250
        keywords:
          description: >-
            One or more keywords describing the information in general terms. 
            Multiple values should be semi-colon delimited.
          type: string
          maxLength: 4000
        related_identifiers:
          description: >-
            The set of related identifiers for a given work, indicating type and
            relationship to this work of each identifier.
          type: array
          items:
            type: object
            properties:
              identifier_value:
                type: string
              identifier_type:
                $ref: '#/components/schemas/identifierTypes'
              relation_type:
                $ref: '#/components/schemas/relationTypes'
            required:
              - identifier_value
              - identifier_type
              - relation_type
          minItems: 0
          uniqueItems: true
        authors:
          description: This work's list of authors or creators.
          type: array
          items:
            $ref: '#/components/schemas/nameType'
        contributors:
          description: List of persons or organizations contributing to this work.
          type: array
          items:
            $ref: '#/components/schemas/contributorType'
info:
  title: Interagency Data ID Service API.
  version: 2.0.0
  description: Usage for OSTI Interagency Data ID (IAD) DOI assignment services API.
  contact:
    email: iad@osti.gov
    name: OSTI IAD Service
paths:
  /api/records:
    summary: Record search query
    description: Perform various queries against records at OSTI.
    get:
      security:
        - basicLogin: []
      summary: Query records
      description: Perform searches on Interagency Data API Service DOI records.
      operationId: ''
      parameters:
        - in: query
          name: id
          description: The unique record ID value
          schema:
            type: integer
        - in: query
          name: start
          description: 'Starting row offset, from 0 (default 0) in search results'
          schema:
            type: integer
            minimum: 0
            default: 0
        - in: query
          name: rows
          description: Number of desired rows per page of results
          schema:
            type: integer
            default: 10
        - in: query
          name: title
          description: Query within the title of records
          schema:
            type: string
        - in: query
          name: keywords
          description: Query within key words of records
          schema:
            type: string
        - in: query
          name: contributing_organization
          description: Query within contributing organization
          schema:
            type: string
        - in: query
          name: sponsoring_organization
          description: Query within sponsoring organization
          schema:
            type: string
        - in: query
          name: research_organization
          description: Query within research organization
          schema:
            type: string
        - in: query
          name: contract_numbers
          description: Query within contract numbers
          schema:
            type: string
        - in: query
          name: report_numbers
          description: Query within report numbers
          schema:
            type: string
        - in: query
          name: other_numbers
          description: Query within other identifying numbers
          schema:
            type: string
        - in: query
          name: description
          description: Query within description or abstract
          schema:
            type: string
        - in: query
          name: doi
          description: Query DOI values
          schema:
            type: string
        - in: query
          name: availability
          description: Query availability information
          schema:
            type: string
        - in: query
          name: publisher
          description: Query within publisher information
          schema:
            type: string
        - in: query
          name: doi_infix
          description: Query DOI infix values
          schema:
            type: string
        - in: query
          name: accession_number
          description: 'Query accession number, or site unique ID value'
          schema:
            type: string
        - in: query
          name: authors
          description: >-
            Query author information, including names, affiliations, email
            addresses, and ORCID values
          schema:
            type: string
        - in: query
          name: contributors
          description: >-
            Query contributor information, including names, affiliations, email
            addresses, ORCID values, and contribution types
          schema:
            type: string
        - in: query
          name: orcid
          description: Query records by author ORCID value
          schema:
            type: string
        - in: query
          name: related_identifiers
          description: Query related identifier values or relation types
          schema:
            type: string
        - in: query
          name: status
          description: Find records with a given status value
          schema:
            type: string
            enum:
              - Pending
              - Error
              - Reserved
              - Registered
              - Deactivated
        - in: query
          name: product_type
          description: Find records by product type
          schema:
            $ref: '#/components/schemas/productTypes'
        - in: query
          name: product_type_specific
          description: Find records of a given specific product type
          schema:
            type: string
        - in: query
          name: site_code
          description: >-
            Find records belonging to a given site code, defaults to user
            account site
          schema:
            type: string
        - in: query
          name: added-after
          description: Find records added after a given date expression
          schema:
            type: string
            format: date
        - in: query
          name: added-before
          description: Find records added before a given date
          schema:
            type: string
            format: date
        - in: query
          name: updated-after
          description: Find records modified after a given date
          schema:
            type: string
            format: date
        - in: query
          name: updated-before
          description: Find records modified before a given date
          schema:
            type: string
            format: date
        - in: query
          name: first-registered-after
          description: Find records initially registered with DataCite after a given date
          schema:
            type: string
            format: date
        - in: query
          name: first-registered-before
          description: Find records initially registered with DataCite before a given date
          schema:
            type: string
            format: date
        - in: query
          name: last-registered-after
          description: Find records most recently registered after a given date
          schema:
            type: string
            format: date
        - in: query
          name: last-registered-before
          description: Find records most recently registered before a given date
          schema:
            type: string
            format: date
        - in: query
          name: published-after
          description: Find records with a date of publication after the given date
          schema:
            type: string
            format: date
        - in: query
          name: published-before
          description: Find records with a date of publication before the given date
          schema:
            type: string
            format: date
        - in: query
          name: all
          description: Find query terms within any indexed record field
          schema:
            type: string
        - in: query
          name: has-doi-infix
          description: Find records that do or do not have DOI infix values
          schema:
            type: boolean
        - in: query
          name: has-related-identifiers
          description: Find records that do or do not have related identifiers
          schema:
            type: boolean
        - in: query
          name: has-orcid
          description: Find records that do or do not have at least one author with an ORCID value
          schema:
            type: boolean
        - in: query
          name: has-accession-number
          description: Find records that do or do not have an accession number value
          schema:
            type: boolean
        - in: query
          name: ever-registered
          description: >-
            Find records that have or have not ever been successfully registered
            with DataCite, and have a live DOI value
          schema:
            type: boolean
        - in: query
          name: include
          description: >-
            Optional list of fields to include in results (comma-delimited). If not
            provided, all fields will be returned in results
          schema:
            type: string
        - in: query
          name: sort
          description: Define a sort-by value for search results
          schema:
            type: string
            enum:
              - id
              - doi
              - title
              - added
              - updated
              - first-registered
              - last-registered
              - published
        - in: query
          name: order
          description: 'Define a sort order, ascending or descending for sort order results'
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  start:
                    description: Starting record number of this result set
                    type: integer
                    example: 0
                  rows:
                    description: Number of rows in this result set
                    type: integer
                    default: 10
                    example: 10
                  numFound:
                    description: Total number of results found in this query
                    type: integer
                    example: 855
                  docs:
                    description: Results found in this query page
                    type: array
                    items:
                      $ref: '#/components/schemas/recordType'
        '400':
          description: Bad request, unable to interpret parameters or values in search
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: HTTP status code
                    type: integer
                    default: 400
                  errors:
                    description: List of error messages specific to this issue
                    type: array
                    items:
                      type: string
                    example:
                      - Unable to parse date value
                      - Start not numeric
servers:
  - url: 'https://www.osti.gov/iad2'
    variables: {}
    description: Interagency Data API Service (production)
  - url: 'https://www.osti.gov/iad2test'
    variables: {}
    description: Interagency Data API Service (testing)