docs: correct type list and fix typos in type-specific keywords page #1952 #1954

DivyanshuVortex · 2025-11-23T20:14:11Z

What kind of change does this PR introduce?

Documentation fix (typo corrections and type-list accuracy improvements)

Issue Number:

Closes [📝 Docs]: fixs typo's in the 'reference/type.md' #1952

Screenshots/videos:

N/A (text-only documentation changes)

If relevant, did you update the documentation?

Yes — this PR directly updates the documentation page.

Summary

This PR corrects multiple inaccuracies in the Type-specific Keywords documentation:

Fixed the primitive type list and ensured accuracy with the JSON Schema specification.
Cleaned several typos, spacing issues, and minor wording inconsistencies.
Ensured examples refer only to valid JSON Schema types.

These improvements increase correctness, clarity, and consistency across the documentation.

Does this PR introduce a breaking change?

No. Documentation-only changes.

Checklist

Read, understood, and followed the contributing guidelines.

github-actions · 2025-11-23T20:16:29Z

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	`9e9bee8`

codecov · 2025-11-23T20:18:49Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (dcf4ea4) to head (9e9bee8).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1954   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           30        30           
  Lines          633       633           
  Branches       196       196           
=========================================
  Hits           633       633

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jdesrosiers

Thanks for fix this. There's one more thing we can fix while we're here. See the inline comment.

jdesrosiers · 2025-11-24T18:58:31Z

pages/understanding-json-schema/reference/type.md

 1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type. 

-Here is an example of using the `string` keyword as a single string:
+Here is an example of using the `number` keyword as a single string:


We usually only refer to the property names as "keywords", not their values. So, type is a keyword and "number" is the value of that keyword.

Suggested change

Here is an example of using the `number` keyword as a single string:

Here is an example of using `"number"` as a single string value:

Hey @jdesrosiers , pushed the requested changes. Lmk if you need tweaks .

jdesrosiers

Sorry, I noticed a couple more things that are wrong. Not sure when this got so broken, but I appreciate you fixing these issues as well. Thanks.

jdesrosiers · 2025-11-24T20:10:41Z

pages/understanding-json-schema/reference/type.md

 - [array](../../understanding-json-schema/reference/array)
 - [boolean](../../understanding-json-schema/reference/boolean)
 - [null](../../understanding-json-schema/reference/null)
 - [numeric types](../../understanding-json-schema/reference/numeric)


"numeric types" is not a type.

Suggested change

- [integer](../../understanding-json-schema/reference/numeric)

- [number](../../understanding-json-schema/reference/numeric)

jdesrosiers · 2025-11-24T20:11:07Z

pages/understanding-json-schema/reference/type.md

 - [null](../../understanding-json-schema/reference/null)
 - [numeric types](../../understanding-json-schema/reference/numeric)
 - [object](../../understanding-json-schema/reference/object)
 - [regular expressions](../../understanding-json-schema/reference/regular_expressions)


"regular expressions" is not a type.

Suggested change

jdesrosiers · 2025-11-24T20:12:23Z

pages/understanding-json-schema/reference/type.md


 The `type` keyword can take two forms:

 1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type. 


"regular expressions" is not a type.

Suggested change

1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type.

1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, or `string`). This specifies that the instance data is only valid when it matches that specific type.

jdesrosiers

Thanks for continuing to iterate on this.

There's a nuance about types that isn't communicated here properly. (Again, I don't know how this got so bad. It didn't used to be like this.) JSON has six types: null, boolean, number, string, array, and object. "Integer" is not a JSON type.

JSON Schema does something confusing where it allows for a seventh value for type called "integer". This does not mean that JSON or JSON Schema supports integers. It's effectively a shorthand for { "type": "number", "multipleOf": 1 } for describing numbers that are restricted to the set of integers.

So, adding "integer" to all the tables is not the right thing to do.

jdesrosiers · 2025-11-25T18:12:15Z

pages/understanding-json-schema/reference/type.md


-[2] JSON does not have separate types for integer and
-floating-point.
+[2] JSON defines a single numeric literal, but JSON Schema distinguishes between `number` (any numeric value) and `integer` (no fractional part).


This is not correct. JSON Schema is uses the mathematical value, not the way number is represented. So, 1.0 is considered an integer even though it contains a fractional part.

I think you can revert this and the other footnote changes. The original was fine.

jdesrosiers · 2025-11-25T18:16:05Z

pages/understanding-json-schema/reference/type.md

 | [array](../../understanding-json-schema/reference/array)        | `items`, `additionalItems`, `minItems`, `maxItems`, `uniqueItems` | Define item schemas, additional item handling, item count constraints, and uniqueness. |
 | [number](../../understanding-json-schema/reference/numeric)       | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` | Define numeric ranges, including exclusive bounds and divisibility. |
 | [object](../../understanding-json-schema/reference/object)      | `required`, `properties`, `additionalProperties`, `patternProperties`, `minProperties`, `maxProperties`, `dependencies` | Define required properties, property schemas, additional property handling, pattern-based property matching, and property count constraints. |
+| [integer](../../understanding-json-schema/reference/numeric)     | Same as `number` | Integers use numeric constraints but must not contain a fractional part. |


Again, the fractional part is not relevant. I don't think we need this row, but maybe we can update the number row to number/integer or something like that.

jdesrosiers · 2025-11-25T18:21:39Z

pages/understanding-json-schema/reference/type.md

-It should be noted that `format` is not limited to a specific set of valid values or types. Users may define their own custom keywords including ones that work with JSON data types other than `string`, such as `number`. Below, we cover the formats specified in the JSON Schema specification.
+It should be noted that `format` is not limited to a specific set of valid values or types. Users may define custom formats through vocabularies, but the built-in formats apply only to strings.


I think this was more clear before except for the error of calling it "custom keywords" instead of "custom formats". Also, formats can't be added through vocabularies.

Thanks for the clarification. I misunderstood the role of "integer" in JSON Schema and treated it as a base JSON type instead of a specialized constraint on "number".

jdesrosiers · 2025-11-28T23:30:07Z

pages/understanding-json-schema/reference/type.md

 The `type` keyword can take two forms:

-1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type. 
+1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean` , `number`, `null`, `object` or `string`). This specifies that the instance data is only valid when it matches that specific type. 


Suggested change

1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean` , `number`, `null`, `object` or `string`). This specifies that the instance data is only valid when it matches that specific type.

1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `number`, `null`, `object` or `string`). This specifies that the instance data is only valid when it matches that specific type.

jdesrosiers · 2025-11-28T23:43:09Z

pages/understanding-json-schema/reference/type.md

 ### Built-in Formats

-It should be noted that `format` is not limited to a specific set of valid values or types. Users may define their own custom keywords including ones that work with JSON data types other than `string`, such as `number`. Below, we cover the formats specified in the JSON Schema specification.
+It should be noted that `format` is not limited to a specific set of valid values or types. Users may define additional custom formats, but the built-in formats apply only to the `string` type. Below, we cover the formats defined in the JSON Schema specification.


This still doesn't quite communicate what it needs to say. It's supposed to clarify that just because all of the formats in the spec apply to strings, doesn't mean custom formats can't apply to types other than strings. I'm not understanding that from the current wording. The original wording was fine other than calling them "custom keywords" instead of "custom formats".

jdesrosiers · 2025-11-28T23:55:23Z

pages/understanding-json-schema/reference/type.md

 At its core, JSON Schema defines the following basic types:

 - [array](../../understanding-json-schema/reference/array)
 - [boolean](../../understanding-json-schema/reference/boolean)
 - [null](../../understanding-json-schema/reference/null)
- [numeric types](../../understanding-json-schema/reference/numeric)
+- [number](../../understanding-json-schema/reference/numeric)
 - [object](../../understanding-json-schema/reference/object)
- [regular expressions](../../understanding-json-schema/reference/regular_expressions)
 - [string](../../understanding-json-schema/reference/string)


 These types have analogs in most programming languages, though they may
 go by different names.

+> Note: JSON does not define an `integer` type. In JSON Schema, `"integer"` is shorthand for `"number"` with `"multipleOf": 1`, used to represent whole-number numeric values.
+
+


At no point do we document that the type keyword takes "integer". I think something like this works better.

Suggested change

The `type` keyword defines the following types:

- [array](../../understanding-json-schema/reference/array)

- [boolean](../../understanding-json-schema/reference/boolean)

- [null](../../understanding-json-schema/reference/null)

- [integer](../../understanding-json-schema/reference/numeric)

- [number](../../understanding-json-schema/reference/numeric)

- [object](../../understanding-json-schema/reference/object)

- [string](../../understanding-json-schema/reference/string)

> Note: JSON does not define an `integer` type. In JSON Schema, `"type": "integer"` is shorthand for `"type": "number", "multipleOf": 1`, and is used to represent whole-number numeric values.

These types have analogs in most programming languages, though they may

go by different names.

jdesrosiers

Sorry, I missed one in the last review.

jdesrosiers · 2025-11-29T21:33:42Z

pages/understanding-json-schema/reference/type.md

 The `type` keyword can take two forms:

-1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type. 
+1. **A single string**. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `number`, `null`, `object` or `string`). This specifies that the instance data is only valid when it matches that specific type. 


This should include "integer" because it's talking about the values the type keyword accepts.

chores

c047695

DivyanshuVortex requested a review from a team as a code owner November 23, 2025 20:14

github-project-automation bot added this to PR - Triage Group Nov 23, 2025

github-project-automation bot moved this to Ready to review in PR - Triage Group Nov 23, 2025

github-actions bot deployed to Preview November 23, 2025 20:16 View deployment

jdesrosiers requested changes Nov 24, 2025

View reviewed changes

github-project-automation bot moved this from Ready to review to Changes requested in PR - Triage Group Nov 24, 2025

chores

02a60ee

github-actions bot deployed to Preview November 24, 2025 19:08 View deployment

DivyanshuVortex requested a review from jdesrosiers November 24, 2025 19:13

jdesrosiers reviewed Nov 24, 2025

View reviewed changes

github-actions bot deployed to Preview November 25, 2025 05:15 View deployment

DivyanshuVortex requested a review from jdesrosiers November 25, 2025 05:18

jdesrosiers requested changes Nov 25, 2025

View reviewed changes

chores

7db6856

github-actions bot deployed to Preview November 26, 2025 07:06 View deployment

DivyanshuVortex marked this pull request as draft November 26, 2025 07:07

DivyanshuVortex force-pushed the fix/docus branch from 275d269 to 7db6856 Compare November 26, 2025 07:19

github-actions bot deployed to Preview November 26, 2025 07:21 View deployment

DivyanshuVortex marked this pull request as ready for review November 26, 2025 07:23

DivyanshuVortex requested a review from jdesrosiers November 26, 2025 07:23

jdesrosiers requested changes Nov 28, 2025

View reviewed changes

chores

9e9bee8

DivyanshuVortex requested a review from jdesrosiers November 29, 2025 07:04

github-actions bot deployed to Preview November 29, 2025 07:04 View deployment

jdesrosiers requested changes Nov 29, 2025

View reviewed changes

	Here is an example of using the `number` keyword as a single string:
	Here is an example of using `"number"` as a single string value:


	- [integer](../../understanding-json-schema/reference/numeric)
	- [number](../../understanding-json-schema/reference/numeric)


		The `type` keyword can take two forms:

		1. A single string. When it is a single string, it must be one of the types mentioned above (`array`, `boolean`, `integer`, `number`, `null`, `object`, `regular expressions`, or `string`). This specifies that the instance data is only valid when it matches that specific type.

		It should be noted that `format` is not limited to a specific set of valid values or types. Users may define their own custom keywords including ones that work with JSON data types other than `string`, such as `number`. Below, we cover the formats specified in the JSON Schema specification.
		It should be noted that `format` is not limited to a specific set of valid values or types. Users may define custom formats through vocabularies, but the built-in formats apply only to strings.

Uh oh!

docs: correct type list and fix typos in type-specific keywords page #1952 #1954

Are you sure you want to change the base?

docs: correct type list and fix typos in type-specific keywords page #1952 #1954

Uh oh!

Conversation

DivyanshuVortex commented Nov 23, 2025

Checklist

Uh oh!

github-actions bot commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Uh oh!

codecov bot commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdesrosiers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Nov 23, 2025 •

edited

Loading

codecov bot commented Nov 23, 2025 •

edited

Loading