nbformat Typescript type definitions

[nokome]

Hi :wave:

Originally, posted at https://discourse.jupyter.org/t/nbformat-typescript-type-definitions/1935, but posting here in case there more (>0) interest

We've generated Typescript type definitions for nbformat JSON Schema versions 3 and 4 using json-schema-to-typescript e.g.

• https://github.com/stencila/encoda/blob/384250a09102d77983a96e63e258a008016dda4b/src/codecs/ipynb/nbformat-v4.d.ts

Previously we were using the type definitions already available in @jupyterlab/coreutils:

• https://github.com/jupyterlab/jupyterlab/blob/3592afd328116a588e3307b4cdd9bcabc7fe92bb/packages/coreutils/src/nbformat.ts

However, we found we had to use a couple of workarounds because those manually coded definitions differ from the JSON schema in some places (e.g. orig_nbformat is required) and due to the dependence on @phosphor/coreutils (which I can't recall the details of). Also we wanted to have Typescript definitions for v3 which do not appear to be available anywhere else.

In our use case, we are using the nbformat JSON Schema definitions anyway (to validate both incoming notebooks prior to decoding, and outgoing notebooks after encoding). So, it makes sense to use Typescript definitions generated from those schemas. We have used json-schema-to-typescript elsewhere and have been pleased with the type definitions it produces.

I was wondering if there is any interest in making these Typescript type definitions more generally available by submitting them to https://definitelytyped.org. They would then be available via npm install @types/jupyter or similar. I'd be happy to help out with, or lead, a PR towards that, but also understand if someone else more involved in Jupyter development would prefer to take it over.

[Madhu94]

@nokome Is your use case to create/manipulate notebooks in a nodejs environment ?

[Madhu94]

If it is, have you tried building on top of commutable ?

[nokome]

@Madhu94 Thanks for the pointer to commutable, I hadn't see that before. Although there are some similarities, I'm not sure if it would be that useful for our use case - which is conversion between nbformat JSON Schema and Stencila's own JSON Schema (which is based on schema.org). We use the type definitions I describe above in the ipynb codec of our encoda format conversion tool.

What we wanted to be able to build on for our use case was some good, canonical Typescript type definitions for nbformat, ideally hosted in the https://github.com/DefinitelyTyped/DefinitelyTyped repo. If that was available then projects like commutable and encoda could reuse those, instead of writing their own.