Add json-schema support #118

kerwanp · 2025-07-05T20:56:16Z

🔗 Linked issue

VineJS schema to JSON schema

❓ Type of change

✨ New feature (a non-breaking change that adds functionality)

📚 Description

This feature adds the ability to transform validators to json-schema using the toJSONSchema method.

This will open a lot of doors for libraries that can build around the json-schema standards (openapi generation, form builder, configuration files, etc).

Implementation

This is currently a draft and serves as an implementation proposal.

The json-schema is computed when calling toJSONSchema on a schema. It can also be computed on the validator with the difference that it is computed only once.

const validator = vine.create(vine.object({
   hello: vine.string(),
}))

const schema = validator.toJSONSchema()

assert.toDeepEqual(schema, {
  type: 'object',
  properties: {
    hello: { type: 'string' }
  },
  required: ['hello']
})

Each type can include toJSONSchema which must return a valid json-schema. If a type does not include it it returns an empty json-schema {} which is considered as an Any type.

When creating rules, it is possible to pass an optional parameter for altering the json-schema.

export const emailRule = createRule<EmailOptions | undefined>(
  function email(value, options, field) {
    if (!helpers.isEmail(value as string, options)) {
      field.report(messages.email, 'email', field)
    }
  },
  {
    toJSONSchema: (schema) => {
      schema.format = 'email'
    },
  }
)

The user is able to provide custom meta that will be merged with the schema to provide custom parameters.

vine.string().meta({ description: "Hello world" })

📝 Checklist

[x ] I have linked an issue or discussion.
I have updated the documentation accordingly.

thetutlage · 2025-07-07T09:44:22Z

Hello @kerwanp

The high-level approach looks fine to me. However, I will have a few changes.

I will rename the json property on a rule to toJSONSchema. Which indicates, this method will be called when converting the Vine schema node to a JSON schema node.
Similarly, the protected method on the Vine schema classes should be called toJSONSchema.
Finally, the meta property should not be strictly tied to JSON schema. If we want to do it, we should rename it to toJSONSchema. It will accept either a JSON schema object, or a function.

Also, once we merge this PR, Vine will support JSON schema as a first-class citizen and all custom schema types must implement the toJSONSchema method as-well.

thetutlage · 2025-07-07T10:00:02Z

Also, we should write some tests for the vine.group and vine.union schema types as well 👍

kerwanp · 2025-07-07T16:49:31Z

Thanks for the feedback!

I added support for vine.group, vine.literal, vine.union and vine.unionOfTypes.

Concerning the meta method. We can either change this to be more generic allowing to retrieve the provided meta when using toJSON() which would be also merged with the json-schema or we could make it specific to json schema (with a different method name). What do you prefer?

I also started the implementation of integration tests that validate values against the generate json-schema using ajv. This can help use spot issues with the complexity of some generated schemas (tuples, records, etc). What do you think?

I we are good with the implementation I will start expanding the test cases, cleaning up my work and add some comments

thetutlage · 2025-07-08T08:52:31Z

I also started the implementation of integration tests that validate values against the generate json-schema using ajv. This can help use spot issues with the complexity of some generated schemas (tuples, records, etc). What do you think?

Yeah, this seems like a great strategy.

Concerning the meta method. We can either change this to be more generic allowing to retrieve the provided meta when using toJSON() which would be also merged with the json-schema or we could make it specific to json schema (with a different method name). What do you prefer?

I will be okay with a more generic approach. However, the issue is, how do we know which properties to merge with the JSON schema?

kerwanp · 2025-07-13T15:08:38Z

I will be okay with a more generic approach. However, the issue is, how do we know which properties to merge with the JSON schema?

LIbraries like Zod provide a meta method that accept anything with a set of known properties that will be merged (title, description, examples, etc). This set is really restrictive and does not really allow schema customization. We can for the moment just rely on JSONSchema as it covers most of the use case. We could rename the method to json or jsonSchema and if metadata is a asked feature the current implementation could be extended

thetutlage · 2025-07-16T08:52:58Z

We could rename the method to json or jsonSchema and if metadata is a asked feature the current implementation could be extended

Cool, let's go with that. Maybe people can rely on the JSONschema properties for their other needs as well.

thetutlage · 2025-07-24T05:05:24Z

@kerwanp What are the next steps for this PR? Do you need any feedback from me?

kerwanp · 2025-07-31T14:41:33Z

@kerwanp What are the next steps for this PR? Do you need any feedback from me?

Hi, I am currently in vacations, will be back the 8th to finish this PR and I think I have all the information required

kerwanp · 2025-08-27T02:16:34Z

I've implemented the different integration tests, it helped me identify a lot of different edge cases.

I will now start updating the existing tests as some of them now contain the JSON schema (286 of them...).

We could either avoid using deep equal or simply bring the json schema in the expected results.

Also it seems that the reference ids are now calculated in different orders with my changes, what is the impact?

  Object {
    "conditions": Array [
      Object {
-       "conditionalFnRefId": "ref://2",
+       "conditionalFnRefId": "ref://1",
        "schema": Object {
          "allowNull": true,
          "bail": true,
          "fieldName": "*",
          "isOptional": false,
+         "jsonSchema": Object {
+           "type": "null",
+         },
          "parseFnId": undefined,
          "propertyName": "*",
          "subtype": "null",
          "type": "literal",
          "validations": Array [],
        },
      },
      Object {
-       "conditionalFnRefId": "ref://3",
+       "conditionalFnRefId": "ref://2",
        "schema": Object {
          "allowNull": false,
          "bail": true,
          "fieldName": "*",
          "isOptional": false,
+         "jsonSchema": Object {
+           "enum": Array [
+             "1",
+             1,
+             "true",
+             true,
+             "on",
+             "0",
+             0,
+             "false",
+             false,
+           ],
+         },
          "parseFnId": undefined,
          "propertyName": "*",
          "subtype": "boolean",
          "type": "literal",
          "validations": Array [
            Object {
              "implicit": false,
              "isAsync": false,
              "name": "boolean",
-             "ruleFnId": "ref://4",
+             "ruleFnId": "ref://3",
            },
          ],
        },
      },
      Object {
-       "conditionalFnRefId": "ref://5",
+       "conditionalFnRefId": "ref://4",
        "schema": Object {
          "allowNull": false,
          "bail": true,
-         "dataTypeValidatorFnId": "ref://6",
+         "dataTypeValidatorFnId": "ref://5",
          "fieldName": "*",
          "isOptional": false,
+         "jsonSchema": Object {
+           "type": "string",
+         },
          "parseFnId": undefined,
          "propertyName": "*",
          "subtype": "string",
          "type": "literal",
          "validations": Array [],
        },
      },
    ],
-   "elseConditionalFnRefId": "ref://1",
+   "elseConditionalFnRefId": "ref://6",
    "fieldName": "*",
+   "jsonSchema": Object {
+     "anyOf": Array [
+       Object {
+         "type": "null",
+       },
+       Object {
+         "enum": Array [
+           "1",
+           1,
+           "true",
+           true,
+           "on",
+           "0",
+           0,
+           "false",
+           false,
+         ],
+       },
+       Object {
+         "type": "string",
+       },
+     ],
+   },
    "propertyName": "*",
    "type": "union",
  }

kerwanp · 2025-12-23T04:04:31Z

Hey @thetutlage!

This pull-request is finally ready to be merged! I made a big change by moving out completely the json-schema computation out of the PARSER methods:

Do not have any impact on performances as the json-schema is only computed when required
Make it way simpler to implement toJSONSchema on any type (even custom ones)

thetutlage · 2025-12-29T05:44:21Z

Hello @kerwanp

The PR looks great. Thanks for putting in the efforts

I remember you had plans to test the JSON schema output against ajv. Have you dropped that plan?

kerwanp · 2025-12-29T11:35:51Z

@thetutlage It might deserve more in depth testing but you can find tests against ajv here

kerwanp added 2 commits July 5, 2025 21:49

feat: implement json-schema support

dc5639c

feat: add json-schema support

d152ba2

kerwanp force-pushed the 4.x branch from 57f93e8 to d152ba2 Compare July 5, 2025 20:59

kerwanp added 2 commits July 5, 2025 23:11

fix: add base schema meta method

e89ee92

test: added integration tests with ajv

c01d132

rename json schema properties and methods

a66cd15

kerwanp force-pushed the 4.x branch from 937df0b to b0bd173 Compare July 7, 2025 22:41

add conditional groups support

f6a579b

kerwanp force-pushed the 4.x branch from b0bd173 to f6a579b Compare July 7, 2025 22:52

thetutlage mentioned this pull request Jul 21, 2025

Discussion for a new feature - KV store in schema #116

Open

kerwanp mentioned this pull request Aug 6, 2025

[OpenApi] No parser found for type record FriendsOfAdonis/FriendsOfAdonis#74

Open

json schema fixes and integration tests

312d02c

kerwanp mentioned this pull request Aug 27, 2025

nullable() without optional() is marked as required in OpenAPI schema FriendsOfAdonis/FriendsOfAdonis#52

Closed

kerwanp mentioned this pull request Sep 4, 2025

Support for AdonisJS unique / exists rules in FoA OpenAPI loader FriendsOfAdonis/FriendsOfAdonis#81

Closed

RomainLanz mentioned this pull request Oct 10, 2025

Discussion for a new feature - Support for Standard Schema V1 interface #125

Closed

kerwanp force-pushed the 4.x branch 3 times, most recently from 124e2d5 to f6d3331 Compare December 22, 2025 19:50

Merge remote-tracking branch 'upstream' into 4.x

71f9731

kerwanp force-pushed the 4.x branch 2 times, most recently from e5625c5 to cb607d0 Compare December 23, 2025 03:18

kerwanp force-pushed the 4.x branch from cb607d0 to 96f0207 Compare December 23, 2025 03:49

move schema computation out of parser

e0620ac

kerwanp force-pushed the 4.x branch from 96f0207 to e0620ac Compare December 23, 2025 03:56

kerwanp mentioned this pull request Dec 23, 2025

JSON Schema support documentation vinejs/vinejs.dev#50

Open

kerwanp marked this pull request as ready for review December 23, 2025 04:05

This was referenced Dec 27, 2025

feat: [openapi] add support for choices and example in vine loader FriendsOfAdonis/FriendsOfAdonis#95

Closed

Bug : mapping fails when all schema property names are camelCase FriendsOfAdonis/FriendsOfAdonis#64

Open

Uh oh!

Add json-schema support #118

Are you sure you want to change the base?

Add json-schema support #118

Uh oh!

Conversation

kerwanp commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

❓ Type of change

📚 Description

Implementation

📝 Checklist

Uh oh!

thetutlage commented Jul 7, 2025

Uh oh!

thetutlage commented Jul 7, 2025

Uh oh!

kerwanp commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thetutlage commented Jul 8, 2025

Uh oh!

kerwanp commented Jul 13, 2025

Uh oh!

thetutlage commented Jul 16, 2025

Uh oh!

thetutlage commented Jul 24, 2025

Uh oh!

kerwanp commented Jul 31, 2025

Uh oh!

kerwanp commented Aug 27, 2025

Uh oh!

kerwanp commented Dec 23, 2025

Uh oh!

thetutlage commented Dec 29, 2025

Uh oh!

kerwanp commented Dec 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kerwanp commented Jul 5, 2025 •

edited

Loading

kerwanp commented Jul 7, 2025 •

edited

Loading