Type Readonly purpose

[enzolupia]

HI, I wanted to define some readonly properties in our API definition schema, so we tried to use the Type.Readonly type, but apparently it doesn't add the readOnly property in the resulting schema.

Usage example:

const schema = Type.Object(
  {
    uuid: Type.Readonly(Type.String({ format: 'uuid' })),
    title: Type.String()
  });

I was expecting the following schema to be generated:

{
...
properties: {
  "id": {
     "type":  "string",
     "format": "uuid",
     "readOnly": true
   }
}
...
}

But the actual result is:

{
...
properties: {
  "id": {
     "type":  "string",
     "format": "uuid"
   }
}
...
}

Currently I had to use a Type.Unsafe type to get the desired result:

const schema = Type.Object(
  {
    uuid: Type.Unsafe<string>({
      type: 'string',
      format: 'uuid',
      readOnly: true,
    }),
    title: Type.String(),
  }
);

Am I doing something wrong or is this type not supposed to do what I was expecting?

[sinclairzx81]

@enzolupia Hi!

TypeBox only provides readonly support for TS static inference (not JSON Schema). Internally it assigns a [Modifier]: 'Readonly' symbol property to the schema, with the symbol used as non-serializable backing property (which makes it hidden to validators like Ajv) while still allowing types to compose. Just be mindful that the keyword readOnly isn't part of the JSON Schema specification (which is why TB doesn't support it)

Adding readOnly property

You can add your own custom property using the following. This creates a custom CustomReadonly function (which you can rename accordingly), which accepts a TSchema, and returns a TReadonly<TSchema> + readOnly: true additional property.

TypeScript Link Here

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

function CustomReadonly<T extends TSchema>(schema: T): TReadonly<T> {
  return Type.Readonly({ ...schema, readOnly: true }) // augment with readOnly here
}

const T = Type.Object({
  x: CustomReadonly(Type.Number()),
  y: CustomReadonly(Type.Number()),
  z: CustomReadonly(Type.Number()),
})

type T = Static<typeof T> // type T = {
                          //  readonly x: number;
                          //  readonly y: number;
                          //  readonly z: number;
                          // }

This should give you the static inference of readonly as well as applying the readOnly property to the schema.
Hope this helps!
S

[enzolupia]

Hi @sinclairzx81 thanks for your quick and exhaustive response, I will definitely give a try to the solution you suggested.

Just a little note, readOnly property is actually part of the draft 7 of the JSON schema 2020-12 specification.
It would be a great improvement to add support for readOnly and writeOnly properties in the future.

Thanks,

E

[sinclairzx81]

@enzolupia Hi! :)

Just a little note, readOnly property is actually part of the draft 7 of the JSON schema 2020-12 specification.
It would be a great improvement to add support for readOnly and writeOnly properties in the future.

Ah, I actually meant to say "Isn't part of the JSON Schema Draft 6 specification" (noting TypeBox is based on draft 6 + partial 2019-09 support for intersect unevaluatedProperties), but yeah, you're quite right; the readOnly and writeOnly annotations are defined on draft 2012-12 as metadata (not necessarily related to validation though)

I have briefly looked these before, and it's difficult to know how best introduce them proper, particularly writeOnly as there is no analogous modifier for writeonly in TS (although there is a TS suggestion here that tries to provide something to describe property setter accessors). I guess one possible solution might be to provide ReadonlyOptions on Type.Readonly(), This would let someone opt into the annotation, but doesn't provide much room for writeOnly...

const T = Type.Object({
  x: Type.Readonly(Type.String(), { readOnly: true }) // options added to readonly, not string
})

But this could also be achieved with the following today.

const T = Type.Object({
  x: Type.Readonly(Type.String({ readOnly: true })) // this also works (albeit a bit superfluous)
})

At this stage, given the inability to express writeOnly (tagged with a possible upstream inclusion of a writeonly modifier in TS), it's probably best to defer to the CustomReadonly() suggestion for the time being (which can remove the duplication). Currently, TypeBox doesn't prohibit users from adding these annotations to schemas (as above), it's just reconciling the annotations to work with TS modifier inference is a bit of a challenge (at least when reconciling across the different draft versions of the specification)

Still, will give this some more thought, there's probably something that can be done here (if only to add readOnly and writeOnly to SchemaOptions)
All the best!
S