User:MPopov (WMF)/Notes/Updating SearchSatisfaction schema

This page walks through the process of updating the SearchSatisfaction schema in the modern Event Platform system, as it's one of the first schemas ported from the legacy EventLogging system (based on meta wiki) to the new git-based repository. For an example of a patch, please refer to 621473.

Prerequisites

• NodeJS v10 or greater, so the current LTS release (v12.19.0) is fine
  • This will also install npm, which we need
• git-review (on Macs this is easiest with Homebrew and brew install git-review)
• Cloned schemas/event/secondary repository
• Gerrit config
  • Create an SSH key pair and upload the public key to your Gerrit account settings at https://gerrit.wikimedia.org/r/settings/#SSHKeys
  • Add the following to your ~/.ssh/config:

    Host gerrit
    	Hostname gerrit.wikimedia.org
    	Port 29418
    	User bearloga
    	IdentityFile ~/.ssh/gerrit_ed25519
    Host gerrit.wikimedia.org
    	Hostname gerrit.wikimedia.org
    	Port 29418
    	User bearloga
    	IdentityFile ~/.ssh/gerrit_ed25519

    Replacing the values for User and IdentityFile to values specific to you

Setup

Navigate to the cloned repository and run npm install to install jsonschema-tools and the pre-commit hook for schema materialization.

You should see a message like

Saving jsonschema-tools materialize-modified pre-commit hook to /Users/mpopov/Desktop/temporary/secondary/.git/hooks/pre-commit

somewhere in there.

Changes

Open jsonschema/analytics/legacy/searchsatisfaction/current.yaml in your favorite text editor. We'll be adding a new boolean field to the schema called coinFlipTail. There are many other types of fields supported by JSONSchema.

First, we bump the schema version up at the top of the file:

# Old:
$id: /analytics/legacy/searchsatisfaction/1.2.0

# New:
$id: /analytics/legacy/searchsatisfaction/1.3.0

Then we add the field itself at the bottom:

# ... schema metadata ...
allOf:
  - $ref: /fragment/analytics/legacy/eventcapsule/1.1.0#
  - required:
      - event
    properties:
      event:
        type: object
        required:
          - action
          - searchSessionId
          - pageViewId
          - scroll
          - mwSessionId
          - source
          - uniqueId
        properties:
          action:
            type: string
          # ... more fields like searchToken, extraParams, skinVersion, etc. ...
          # ======= NEW FIELD WE'RE ADDING: ========
          coinFlipTail:
            type: boolean
            description: >-
              The result of a random coin flip at the time of the event.

Make sure that the indentation is done with 2 spaces, otherwise you'll get validation errors. Once done, track & commit the changes:

git add -A
git commit -m "Added coinFlipTail field to Search Satisfaction legacy schema"

You should then see messages about latest symlinks having been created and that "New schema files have been materialized."

Run npm test to verify that there are no errors before uploading to Gerrit for code review via git review

Once uploaded for review, add Bearloga or Ottomata as reviewer(s).

Manual Changes

Sometimes you may need to make modifications that require manually re-materializing a schema. This is accomplished any time by:

./node_modules/.bin/jsonschema-tools materialize jsonschema/analytics/legacy/searchsatisfaction/current.yaml

Indeed, that is essentially what gets run automatically for you by the installed pre-commit hook.