Skip to content
GitHub
Twitter

How to review a pull request for a Bioschemas Specification

In this how-to, we will provide recommendations for reviewing a pull request on a Bioschemas specification and triggering the automated scripts for pushing it onto the website
Previous tutorial: Create New Type

Review a pull request for a Bioschemas Specification JSON-LD file

A community member has created or updated a Bioschemas specification JSON-LD file and created a pull request. Here’s how to help review and merge it, so that the website and the DDE will be updated.

Step 1 ensure you have access to the appropriate channels and repositories

Step 2 Claim the pull request

  • Reply to the slack notification on the pull request to inform others that you will be reviewing it
  • Assign the pull request to yourself on GitHub

Step 3 - Verify that the JSONLD schema file is working properly and that the config file is up-to-date

  • Go to the branch or fork of the Bioschemas specification repository that has the Bioschemas profile JSON-LD file that is the subject of the pull request
    • Does it load without error in the DDE?
    • Does it have the correct hierarchy (rdfs:subclassOf)?
    • Does the @context have the necessary iri’s?
    • Only if it is a __profile: Are the constraints properly expressed in the $validation?
  • Verify that the configuration file in the bioschemas website repository is up-to-date
    • The configuration file needs to be updated only for brand new specifications, to update:
      • Create a new branch in the Bioschemas website repository with a suitable name to identify the intended outcome of the work, e.g. for a new 0.4 draft of the “example profile” we might have draft-example-0.4.
      • Find the _data/metadata_mapping.csv file. If it isn’t, add a row for the specification stating the specification name, working group name, and expected parent.
        • Note that the expected parent of a profile specification and type specification may be different:
          • For example: parent for FormalParameter profile is expected to be bioschemastypes:FormalParameter type, but the parent for FormalParameter type is expected to be schema:Intangible
      • Create a pull request from your branch to the parent branch.

Step 4 - Merge the pull requests

  • IF you edited the metadata_mapping file in Step 3:
    • merge the pull request from your branch of the Bioschemas website to the parent branch.
    • This will ensure that the automated script has the information needed to automatically generate html files once triggered.
  • Merge the pull request for the new/updated JSON-LD file that you reviewed to the master branch of the specification repository
    • This will trigger the GitHub action for automatically generating the corresponding page in the Bioschemas website.
    • The GitHub action will create a new branch of the Bioschemas website with the required changes
      • The branch will be named based on the date and time of when the GitHub action was triggered
        • It will follow the format YYYY_MM_DD-HH_MM_SS
      • The GitHub action will also automatically generate a pull request to merge the branch into master
  • Merge the pull request that was generated by the GitHub action

Step 5 - Update the bioschemas specification in the DDE schema registry (to be automated and removed as a step)

  • This step has been automated in a branch, but that branch has not been merged as it is dependant on the GitHub action in Step 4
  • Documentation on the automated JSON-LD-to-webpage conversion: https://hackmd.io/zGOAxx-BRfi4rDiaW9Rk4Q?both
  • Documentation on the automated DDE-updates: https://github.com/bioschemas/bioschemas-dde
  • About JSON-LD: https://json-ld.org/
  • About JSON-schema: https://json-schema.org/
  • The FAQ for the Data Discovery Engine (DDE): https://discovery.biothings.io/faq/dde

Keywords: schemaorg, markup, structured data, bioschemas

Topics:

Audience:

  • People familiar with GitHub, JSON-LD and JSON-schema representation

Authors:

License: CC-BY 4.0

Version: 0.2

Last Modified: 02 November 2022

Previous tutorial: Create New Type