feat(shared-data): json protocol schema 8 #13848

sfoster1 · 2023-10-25T19:34:36Z

Add JSON protocol schema 8, which is similar in semantic concept to json protocol schema 7 but defines new keys for many large components (commands, annotations, liquids, labware) that set the expected schema for the content for that component.

For instance, now you specify a commandSchemaId and the elements of the commands array have to match that. You specify a liquidSchemaId and the elements of the liquid object have to match that.

This hopefully will let us be more flexible with upgrading things like the kinds of commands a protocol can run without having to change the protocol schema itself. Consumers will have to make sure that they can handle the schema for the components, but there's a new provided typescript validator (in shared-data/js/protocols.ts) that will validate any version of the protocol we support and return it with appropriate types; that's a bit more spread around in python but it similarly handles everything.

Also, you specify the deck schema version now.

This should be integrated into the robot for execution and we should make sure the app doesn't choke on it, but really it's a good way to be able to add new commands without making other protocols accidentally invalid.

This should be a big step forward in flexibility for our protocol schemas.

testing

odd can render protocols tagged jp8
app can render protocols tagged jp8
offline analysis can handle protocols tagged jp8
robot analysis can handle protocols tagged jp8
robot can execute protocols tagged jp8
if you have a jp8 protocol run, analysis, and protocol saved on the robot and then you downgrade, the server is still operational

Add JSON protocol schema 8, which is similar in semantic concept to json protocol schema 7 but - Requires user specification of the schema for the command List This allows json protocols to switch which commands they're interning without requiring further bumps to the protocol schema - Does the same thing for command annotations, liquids, and labware For the same reasons. This should be a big step forward in flexibility for our protocol schemas.

b-cooper · 2023-10-25T19:38:26Z

shared-data/command-annotation/schemas/1.json

This directory should be camelCase like the reference in the v8 schema commandAnnotation/schemas

codecov · 2023-10-25T19:38:38Z

Codecov Report

Merging #13848 (eeb8e4b) into edge (6b79819) will increase coverage by 0.14%.
Report is 18 commits behind head on edge.
The diff coverage is 84.39%.

❗ Current head eeb8e4b differs from pull request most recent head 4509338. Consider uploading reports for the commit 4509338 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #13848      +/-   ##
==========================================
+ Coverage   70.65%   70.79%   +0.14%     
==========================================
  Files        2491     1625     -866     
  Lines       70040    54034   -16006     
  Branches     8523     3779    -4744     
==========================================
- Hits        49486    38254   -11232     
+ Misses      18531    15120    -3411     
+ Partials     2023      660    -1363

Flag	Coverage Δ
app	`43.57% <ø> (-24.57%)`	⬇️
g-code-testing	`96.44% <ø> (ø)`
notify-server	`89.13% <ø> (ø)`
protocol-designer	`45.45% <ø> (ø)`
shared-data	`72.96% <84.39%> (+0.74%)`	⬆️
step-generation	`84.95% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
api/src/opentrons/protocol_reader/role_analyzer.py	`100.00% <ø> (ø)`
.../src/opentrons/protocol_runner/json_file_reader.py	`100.00% <ø> (ø)`
shared-data/js/helpers/parseProtocolData.ts	`63.15% <ø> (ø)`
...ata/python/opentrons_shared_data/deck/dev_types.py	`100.00% <100.00%> (ø)`
...-data/python/opentrons_shared_data/errors/codes.py	`93.33% <100.00%> (+0.09%)`	⬆️
.../opentrons_shared_data/protocol/models/__init__.py	`100.00% <100.00%> (ø)`
..._shared_data/protocol/models/protocol_schema_v8.py	`100.00% <100.00%> (ø)`
.../python/opentrons_shared_data/errors/exceptions.py	`60.51% <66.66%> (+0.08%)`	⬆️
...a/python/opentrons_shared_data/command/__init__.py	`0.00% <0.00%> (ø)`
shared-data/js/protocols.ts	`81.65% <81.65%> (ø)`

... and 868 files with indirect coverage changes

shared-data/protocol/schemas/8.json

jbleon95 · 2023-10-27T15:56:29Z

As discussed in the comments on #13854, we should add some sort of deckVersion field along with deckId to allow robot server/protocol runner to know whether to load fixed trash or not, rather than just relying on schema version moving forward.

jerader · 2023-10-27T17:34:28Z

shared-data/protocol/schemas/8.json

+ "commandAnnotationSchemaId": {
+ "description": "The schema to which the command annotations adhere.",
+ "type": "string"
+ },
+
+ "commandAnnotations": {
+ "type": "array",
+ "items": { "$ref": "#/properties/commandAnnotationSchemaRef" }
+ }
+ }


what is an example of commandAnnotations?

Something like grouping commands into the higher-level (i.e. PD, or python api call) command that created them, for instance. Or into user-specified arbitrary groups. Or time estimates, or really anything

If you are running a dev server, tavern will use that for its tests and print out that it did so. You can also specify host and port for dev server now.

Jsonschema is a lot of things but one thing it isn't is a definer of schema behavior based on values in the document. That's the key to all of this - the document specifying a subschema for part of its content - so we're just going to do it in code instead. That means - In the protocol schema, dynamically subschema'd objects get typed as objects - We get a new typescript validator to handle it all - Also update python for this but it matters a bit less because the python defines what is acceptable anyway, so there's no point trying to be future proof here when downstream consumers will have to change

jerader

I reviewed the js stuff and sprinkled in a few clean up suggestions & notes. But lgtm! 🎉

jerader · 2023-10-31T13:53:35Z

shared-data/command/types/calibration.ts

+ LabwareOffset,
+ Coordinates,
+} from '../../js/types'
+// TODO (sb 10/26/22): Separate out calibration commands from protocol schema in RAUT-272


I think we can delete this TODO, cc @smb2268

jerader · 2023-10-31T13:56:47Z

shared-data/js/protocols.ts

+import type * as ProtocolSchemas from '../protocol'
+import type { CreateCommand } from '../command/types'
+import type { CommandAnnotation } from '../commandAnnotation/types'
+import Ajv from 'ajv'


can we move the Ajv import to be at the top of the imports? And then move the type imports to be at the bottom of the imports before line 22?

jerader · 2023-10-31T14:07:44Z

shared-data/js/protocols.ts

+ })
+
+// note: rejects with an array of ajv errors
+export function validate(


Maybe we can leave a note in here saying this is used in the protocolValidation.test since other files in the shared-data/js directory contain utils used outside of tests.

Oh this definitely will be used outside of tests, I just don't want to gate merging this pr on "switching the entire js ecosystem over to json protocol v8". The idea with this function is that you'll use it to validate protocols in js anywhere they appear since it will do the typecasting for you.

robot-server/tests/integration/conftest.py

SyntaxColoring

Python changes look great. Thank you!

SyntaxColoring · 2023-10-31T15:04:35Z

shared-data/errors/definitions/1/errors.json

+ },
+ "4006": {
+ "detail": "Invalid Protocol Data",
+ "category": "generalError"


Nice, thank you.

b-cooper

🏈

sfoster1 requested a review from a team as a code owner October 25, 2023 19:34

sfoster1 requested a review from a team October 25, 2023 19:34

sfoster1 requested a review from a team as a code owner October 25, 2023 19:34

sfoster1 marked this pull request as draft October 25, 2023 19:34

b-cooper reviewed Oct 25, 2023

View reviewed changes

b-cooper and others added 4 commits October 25, 2023 16:49

add enum to annotations and structure types for commands etc

f248da7

fix up ts config for protocol types

fecc2ba

add python types and fixup some little schema things

d7ebc44

add support in json_translator

dd9775c

SyntaxColoring reviewed Oct 26, 2023

View reviewed changes

shared-data/protocol/schemas/8.json Outdated Show resolved Hide resolved

sfoster1 mentioned this pull request Oct 27, 2023

refactor(api, robot-server, shared-data): replace v3 deck definition with v4 in protocol api and engine #13854

Merged

SyntaxColoring mentioned this pull request Oct 27, 2023

feat(protocol-engine): Add skeleton for loadAddressableArea command #13861

Closed

jerader reviewed Oct 27, 2023

View reviewed changes

sfoster1 added 8 commits October 27, 2023 13:50

update example files for better tests

ba78bcf

update reader errors and add support to runner

c69b72a

add explicit ability to use dev server for tavern

cbe5570

If you are running a dev server, tavern will use that for its tests and print out that it did so. You can also specify host and port for dev server now.

this little guy needs a change

aeefe88

add new shared-data to tsconfig-eslint

a3787ec

export types as types from protocol

fd433f6

install new schemas on robot

727317b

format py

b1ee0a6

sfoster1 marked this pull request as ready for review October 30, 2023 13:37

sfoster1 requested review from a team as code owners October 30, 2023 13:37

sfoster1 requested review from ncdiehl11 and removed request for a team October 30, 2023 13:37

add a deck schema ID to protocols

6e3c0db

sfoster1 requested a review from a team as a code owner October 30, 2023 14:00

sfoster1 added 6 commits October 30, 2023 17:21

lint

e3e46a5

js lint

cbbdbb5

py fixups

5ca1e25

py format

ec90dac

one last py format

3dfb6c2

jerader approved these changes Oct 31, 2023

View reviewed changes

review requests

27eb307

SyntaxColoring reviewed Oct 31, 2023

View reviewed changes

robot-server/tests/integration/conftest.py Outdated Show resolved Hide resolved

revert conftest changes

eeb8e4b

SyntaxColoring approved these changes Oct 31, 2023

View reviewed changes

b-cooper approved these changes Oct 31, 2023

View reviewed changes

bump the robot-server timeout

4509338

sfoster1 merged commit 196fdc0 into edge Oct 31, 2023
25 of 26 checks passed

sfoster1 deleted the add-json-protocol-8 branch October 31, 2023 15:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(shared-data): json protocol schema 8 #13848

feat(shared-data): json protocol schema 8 #13848

sfoster1 commented Oct 25, 2023 •

edited

Loading

b-cooper Oct 25, 2023

codecov bot commented Oct 25, 2023 •

edited

Loading

jbleon95 commented Oct 27, 2023 •

edited by SyntaxColoring

Loading

jerader Oct 27, 2023

sfoster1 Oct 27, 2023

jerader left a comment

jerader Oct 31, 2023

jerader Oct 31, 2023

jerader Oct 31, 2023

sfoster1 Oct 31, 2023

SyntaxColoring left a comment

SyntaxColoring Oct 31, 2023

b-cooper left a comment

feat(shared-data): json protocol schema 8 #13848

feat(shared-data): json protocol schema 8 #13848

Conversation

sfoster1 commented Oct 25, 2023 • edited Loading

testing

Choose a reason for hiding this comment

codecov bot commented Oct 25, 2023 • edited Loading

Codecov Report

jbleon95 commented Oct 27, 2023 • edited by SyntaxColoring Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jerader left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SyntaxColoring left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-cooper left a comment

Choose a reason for hiding this comment

sfoster1 commented Oct 25, 2023 •

edited

Loading

codecov bot commented Oct 25, 2023 •

edited

Loading

jbleon95 commented Oct 27, 2023 •

edited by SyntaxColoring

Loading