Add missing typescript support by for boolean json-schema

[ekzobrain]

When parsing this schema SchemaNode for test property will contain schema: false

{
  "properties": {
     "test": false
  }
}

But type definition of SchemaNode.schema does not allow it, so it should be changed to JsonSchema | boolean.

[ekzobrain]

Also SchemaNode.dependentSchemas typedef seems invalid. Should it be Record<string, SchemaNode> instead of Record<string, SchemaNode | boolean>?

[Adityakumar37]

@sagold I checked the JSON Schema specification and boolean schemas are valid.

Since parsing { "properties": { "test": false } } produces a SchemaNode
with schema = false, the current type of SchemaNode.schema
should probably be:

JsonSchema | boolean

Otherwise TypeScript definitions are stricter than runtime behaviour.

If you agree, I would like to work on this

[sagold]

Hey Aditya,

if you want to try adding types for boolean-schemas you are welcome.

For documentation purposes: json-schema-library does fully support boolean schemas. What it lacks, is proper typescript support.

Some notes on this topic

• I did not come around to add typescript support, because it will have an impact on its public api. Thus, consuming the api will be way more complicated, because every schema has to be checked if it is boolean or not (which is the rarer case). That being said, proper types is, of course, our goal.
• A decision is outstanding if this type is part of type JsonSchema or we type everything with JsonSchema | boolean. Edit: Probably sth like JsonSchema|BooleanSchema
• Changing this type might have an impact on the whole codebase
• On a positive side, I enforced stricter types now on #main. This might support in introducing boolean-schema types

Do not hesitate to ask or discuss here, in case you want to get started.

[Adityakumar37]

Thanks for the explanation.
I would like to explore introducing boolean into JsonSchema.
I will first check how many places in the codebase assume schema is an object and estimate the impact.
Then I’ll propose an approach.

[Adityakumar37]

Hi @sagold ,
While reviewing the codebase, I noticed that boolean schemas are already supported at runtime and currently handled using @ts-expect-error in several places (for example in reduceNode).
Before starting implementation, I would like to confirm the intended direction.
Would you prefer introducing a dedicated BooleanSchema type (e.g. type BooleanSchema = true | false) and updating SchemaNode.schema to:

schema: JsonSchema | BooleanSchema

Then gradually introducing proper type narrowing across the codebase?
Or would you prefer a different structural approach to minimize public API impact?
Given current usages like Object.keys(node.schema) and direct property access (node.schema.$ref), this change will require explicit type guards before object operations.
I’d like to align on the design direction before proceeding.

[sagold]

Hey Aditya.

Yes, boolean schema is supported, thats why I wrote:

For documentation purposes: json-schema-library does fully support boolean schemas. What it lacks, is proper typescript support.

To my current knowledge:

1. We need to use JsonSchema|BooleanSchema (BooleanSchema type already exists) for the following reason:

• We need to be able to support a typeguard isJsonSchema(v) and isBooleanSchema(v) at least for ReturnTypes
• We need to explicitly type JsonSchema for internal functions as they expect a schema, not a boolean. Boolean logic is very simple and internal functions will not get called with a boolean.

I would start by introducing JsonSchema|BooleanSchema as input type for public methods one by one.
Methods on interface SchemaNodeMethodsType are probably the best start

With this achieved, I think that is a solid PR and a good improvement of current typings.

2. interface SchemaNode » property schema: JsonSchema might be tricky to change as this could have a wide spread impact. A search for node.schema results in 124 hits, including tests. Finding a way to proceed here incrementally would be a safer path. This then also starts touching public api of ReturnTypes.

3. Extend all remaining return types. I really would love to have an easy way to work with JsonSchema return types. Maybe supporting a generic on SchemaNodes<S = Schema|Boolean> or returning results on a separate property { node, nodeWithBooleanSchema, error }, but I didnt put much thought into this yet. The goal of OptionalNodeOrError is to differentiate between errors and results without requiring the constant import of typeguards.

Will need to come back to this when there is more time.
Feel free to ask, discuss or propose a solution. Looking forward to your reply.

Sascha

[Adityakumar37]

Hi @sagold,
Thank you for the detailed breakdown that really helps.
I'll start with Step 1:

• Use JsonSchema | BooleanSchema as input types on public methods in SchemaNodeMethodsType, one by one
• Add isJsonSchema andd isBooleanSchema typeguards for return types
  I'll keep SchemaNode.schema untouched for now and tackle that incrementally in a follow-up PR once Step 1 is merged.
  I'll open a draft PR once I have an initial implementation ready. Will ping you here if I run into any design questions.
  Thanks again!

[Adityakumar37]

Hi @sagold

Here's a summary of what I've implemented so far for Step 1:

Changes in src/types.ts:

• Added isJsonSchema(value) typeguard — returns true if value is a JsonSchema (i.e. an object)
• Added isBooleanSchema(value) typeguard — returns true if value is a boolean

Changes in src/SchemaNode.ts:

• Imported BooleanSchema and isJsonSchema from types.ts
• Updated compileSchema signature in SchemaNodeMethodsType to accept JsonSchema | BooleanSchema
• Updated addRemoteSchema signature in both the interface and implementation to accept JsonSchema | BooleanSchema
• Added an isJsonSchema guard in addRemoteSchema implementation before accessing schema.$id and schema.$schema

npm run lint:types passes with 0 errors.

I intentionally left SchemaNode.schema as JsonSchema for now, as changing it has a wide impact (124+ usages) and is better handled incrementally in a follow-up.

Does this direction look good to you? If so, I'll open a draft PR.

[sagold]

Yes, this sounds good. Besides npm run lint:types, npm run test should work of course. If you like, you can push the commits to your fork so I can have a look.

[sagold]

@Adityakumar37 your changes have been published with json-schema-library@11.0.3

[Adityakumar37]

Hi @sagold,
That’s great to hear thanks for the update and for the review throughout the process.