Override Typebox object properties in schema composiiton/merge

[lucashfreitas]

Hello @sinclairzx81 ,

Sorry, another question.

it's possible to "mutate" type box object properties to reuse them to compose schemas?. A common use of case when we are defining schemas is to "merge" types overriding a few properties. We are using json-merge and the JSON schema definition is something like:

https://github.com/boschni/json-merger. So we run json-merge and it automatically merges and outputs it to a new Json Schema Object.

I was wondering if it's possible to "override/mutate" properties of a typebox object when reusing it to compose schemas.

[sinclairzx81]

@lucashfreitas Hi!

TypeBox types/schemas are considered immutable from a library standpoint. TypeBox doesn't prevent users from mutating schemas...but doing so may invalidate the TS type associated with that schema (so it would be generally discouraged)

Composition in TypeBox is however supported; but limited to composition types provided by the library such as Type.Intersect([A, B]), Type.KeyOf(A), Type.Partial(A), etc. I'm not very familiar with json-merger but taking a look at it's readme, it doesn't seem like it would be immediately compatible. To merge objects in TypeBox, you would use similar type construction patterns used to compose types in TypeScript. For example.

// typescript intersect (similar to merge)
interface A { a: number }
interface B { b: number }
type C = A & B

// typebox intersect 
const A = Type.Object({ a: Type.Number() })
const B = Type.Object({ b: Type.Number() })
const C = Type.Intersect([A, B])

Here, the Type.Intersect(...) function produces a new JSON schema that is semantically equivalent to the TypeScript type. To achieve this, the function computes the new schema in very particular ways to ensure the output schema matches the semantics of the expected TypeScript type. Because computing the new schema requires the function to have some intrinsic knowledge of JSON Schema, it's unlikely libraries like json-merger would produce an output schema that captured the same semantics (was looking specifically at $merge, maybe the library has some other json schema specific functions?)

It might be possible to use TypeBox to construct correct source schemas that are later passed to json-merge for merging, but you would need to be careful the merge didn't invalidate the schema in some unexpected way.

Does this help? Or were you just looking to use json-merger to combine multiple schemas into a single output document (this would be common if you're looking to publish schemas for example)

[lucashfreitas]

@sinclairzx81, yeah objects should be immutable - I am trying to figure out how can I produce a new object "overriding" specific properties basically. Not sure if Intersect handles that - but just to demonstrate would be something similar to this

merging schemas would be producing new types but replace specific properties. eg.

const Measure = Type.Object(
  {
    value: Type.Number({
      title: "Value of the field",
      examples: [25.5, 12],
    }),
    unit: Type.String({
      title: "The SI unit that value is measured in",
      examples: ["ms-1", "kg"],
    }),
  },

  {
    additionalProperties: false,
  }
);

So, in another JSON I want to "reuse" the measure type/object but replace the type of the unit field, it now needs to be a enum. Note that the Object.assign here is just to demonstrate that I want to produce a new type with only the unit property modified - ofc object.assign is not immutable for nested objects atm but would be an immutable function that produces a type override the unit property.

const Position = Type.Object(
  {
    point: GeoPoint,
    altitudeEllipsoid: Object.assign({}, ...Measure, {
      unit: Type.Enum(MetterOnly),
    }),
  },

[sinclairzx81]

It is possible to replace properties in objects the same as you would in TypeScript without having to modify the schema properties manually. TypeBox emulates quite a lot of TypeScript's type system and Utility Types. So the majority of types you can create with TypeScript can also be created with TypeBox.

In the case of replacing properties, consider the following example where we replace the z: number property in A with a updated z: boolean. Similar approaches can be used to remap the unit property in the Position type you showed above.

TypeScript Link Here

import { Type, Static } from '@sinclair/typebox'


// --------------------------------------------------------
// for the given type A ...

const A = Type.Object({       // type A = { 
   x: Type.Number(),          //   x: number,
   y: Type.Number(),          //   y: number,
   z: Type.Number()           //   z: number
})                            // }

// --------------------------------------------------------
// ... remove property 'z'

const B = Type.Omit(A, ['z']) // type B = { 
                              //  x: number, 
                              //  y: number 
                              // }

// --------------------------------------------------------
// ... then re-add z as a boolean type

const C = Type.Intersect([    // type C = { 
    B,                        //  x: number, 
    Type.Object({             //  y: number, 
        z: Type.Boolean()     // } & {
    })                        //  z: boolean
])                            // }

// --------------------------------------------------------
// ... which produces the following type

type C = Static<typeof C>     // type T = Omit<{
                              //   x: number;
                              //   y: number;
                              //   z: number;
                              // }, "z"> & {
                              //   z: boolean;
                              // }

// --------------------------------------------------------
// ... and the following schema

console.log(C)              // {
                            //    type: 'object',
                            //    properties: {
                            //      x: { type: 'number' },
                            //      y: { type: 'number' },
                            //      z: { type: 'boolean' }
                            //    },
                            //    required: [ 'x', 'y', 'z' ],
                            // }

The TypeScript equivalent of this would simply be

interface A {
  x: number,
  y: number,
  z: number
}

type B = Omit<A, 'z'>

type C = B & { z: boolean }

You can achieve other kinds of compositions like this (where TypeBox will ensure the resulting schema is correct), however the TypeBox API is a bit more verbose than the terse syntax TypeScript provides. But the same concepts should be transferrable.

[lucashfreitas]

Awesome, I can create a helper method that first remove and intersect the new property. Thank you very much!

[lucashfreitas]

@sinclairzx81 thank you very much! A last and out-of-scope question:

By any chance, can this library do the reverse - generating typescript types from JSON schema? I think that's not supported and not indented to, right? I am using some external $refs for a definition for schemas and would like for it to be fully type compatible. I tried several libraries to generate TS types out of JSON schemas but all of them have issues/aren't working correctly, so due to that I have decided to migrate the schema definition to typebox and get it out of the box. :)

[sinclairzx81]

Have a look at https://www.npmjs.com/package/json-schema-to-typescript which may be able to convert your existing JSON Schema to TypeScript. Once you have converted to TypeScript, you might be able to use this to convert TypeScript into TypeBox.

To run this, you will need to clone the TypeBox repository and run the generator from the example/index.ts script by running npm start in the project root. The code to generate TypeBox code from TypeScript code should look as follows.

const Code = CodeGen.TypeBox(`
   interface A {
      x: number,
      y: number,
      z: number
   }
`)
console.log(Code) // print TypeBox translated code.

Note: Automatic code translation is a work in progress (and hasn't had a lot of testing) but it may be able to help save you some time. The key will be getting your existing schemas into typescript code first tho.

Hope that helps!
S

[lucashfreitas]

Cool - that was really helpful. Thank you!