GSoC 2025: Investigating Schema Normalization

[Julian]

Brief Description
JSON Schema is a rich language for expressing constraints on JSON data. If we strictly consider JSON Schema validation (rather than any other use of JSON Schema), in many cases there are multiple ways to express the same constraints. For example, the schema:

{
  "oneOf": [
    {"const": "foo"},
    {"const": "bar"}
  ]
}

will have the same validation outcome on all instances as the schema:

{"enum": ["foo", "bar"]}

One might say that this second schema is in some way "better" than the first one in some way that could be made precise.

The same is true for the schemas {"required": ["foo"]} and {"title": "My Schema", "required": ["foo"]}, and one might say the first one is "better" than the second for the purpose of validation.

We can define two schemas to be "equivalent" if they have this property that any instance is valid under one if and only if it is valid under the other, and if we have two equivalent schemas S and S' we might wish to define an algorithm for transforming these schemas into a form which is "canonical" or "normal" such as above.

There are existing attempts to do this for various use cases, but no central place where a self-contained set of normalization rules are written down and a self-contained tool exists to perform the procedure. Let's try and write a simple one!

Expected Outcomes

• Investigate the existing implementations of normalization in the wild. There are at least two known ones, one being here.
• Define a set of normalization rules, with configurability for cases where there are multple reasonable canonical forms
• Define a set of test cases for schemas which are equivalent under these rules, and for the target canonical form for each set of schemas
• Write a Python library which performs the normalization and emits the normalized schema
• Empirically test our normalization procedure by running normalized schemas through Bowtie and comparing whether a given implementation returns the same results

Skills Required

• An existing understanding of JSON Schema's keywords, which can be used to think about areas which might create possible "denormalization" (e.g. keywords which when used together overlap)
• Familiarity writing Python, and ideally using JSON Schema from Python
• Experience testing pieces of software by writing test cases, here likely in the form of writing JSON Schema + instance examples
• Careful diligence in reading and understanding the existing procedures used (in the link above, as well as in a number of JSON Schema journal articles) and the ability to compare the previous work with each other

Mentors
@Julian

Expected Difficulty
medium

Expected Time Commitment
175

[jviotti]

I love this, and I think it has some interesting overlap with my linting proposal: #856. The things that should be normalised can make very good linting rules that we can aim to auto-fix for schemas. If I can help in any way, please count me in.

[Honyii]

Thank you for your submission Julian

[VishwapriyaVelumula]

Hello, I'm Vishwapriya, currently pursuing 3rd year of BTech. I want to contribute to this idea in this GSoC, this my very first time of trying an open source contribution. @Julian or anyone please let me know where to start and how to start.
Thankyou in advance for letting me know!!

[Illucious]

This sounds like a great idea, here's what I found and think.

After a bit of digging around, I found some common patterns where different schemas produce identical validation outcomes

1. Enumeration Equivalences

{"oneOf": [{"const": "foo"}, {"const": "bar"}]} ≡ {"enum": ["foo", "bar"]}
{"anyOf": [{"const": "foo"}, {"const": "bar"}]} ≡ {"enum": ["foo", "bar"]}

2. Type Equivalences
   {"type": ["string", "number"]} ≡ {"anyOf": [{"type": "string"}, {"type": "number"}]}

3. Required Properties
   {"properties": {"foo": {}}, "required": ["foo"]} ≡ {"properties": {"foo": {"type": ["null", "string", "number", "integer", "object", "array", "boolean"]}}, "required": ["foo"]}

4. Non-validation Keywords
   {"title": "My Schema", "description": "...", "required": ["foo"]} ≡ {"required": ["foo"]}

5. Default Values
   {"type": "string", "default": "foo"} ≡ {"type": "string"} (for validation purposes only)

6. Empty Schemas

{} ≡ {"additionalProperties": true}
{} ≡ {"type": ["null", "string", "number", "integer", "object", "array", "boolean"]}

Existing Normalization Approaches

Though I haven't yet gone through existing approaches, I'd examine the existing approaches mentioned in the description, with a particular focus on:

1. How they handle nested schemas
2. Their treatment of metadata keywords
3. Special handling of boolean schemas

Proposed Normalization Rules

Here's an initial set of normalization rules I would implement:

1. Enumeration Normalization: Convert any oneOf or anyOf with only const schemas to an enum
2. Type Consolidation: Normalize type specifications to the most concise form
3. Redundant Keyword Removal: Strip keywords that don't affect validation outcomes
4. Property Requirement Simplification: Standardize ways of expressing required properties
5. Logical Operation Flattening: Flatten nested logical operators when possible
6. Empty Schema Normalization: Standardize representation of unrestricted schemas

Implementation Approach

I would develop a Python library for it, but rightnow I'm still thinking about an approach.

I would love to get some constructive criticism of this idea and some good feedback.

[TheGreatCorrine]

Hi @Illucious ! Your exploration is a good starting point! However, I do have some other thoughts:

4. Non-validation Keywords:
   JSON schema is not only used for validation, it can be used for many other tasks, including API documentation generation and UI generation. So it is important to keep these keywords (description, etc.).
5. Empty Schema Equivalence:
   While {} ≡ {"additionalProperties": true} is correct
   {} ≡ {"type": ["null", "string", "number", "integer", "object", "array", "boolean"]} is not entirely accurate.
   An empty schema accepts any valid JSON value, but listing all types doesn't fully capture the semantic meaning of an empty schema, especially in nested contexts.

Additionally, I hope to get some clarifications as well if possible.@Julian What does better mean? Historical precedence? Code readability? Or something else? Is the second schema better just because it improves the code readability? :) Any insight will be highly appreciated!

[idanidan29]

Hey @Julian and the team👋

I’m Idan Levi, a software engineering undergrad with a passion for JSON Schema and open-source. I’ve worked with both front-end and back-end tech like Next.js, Flask, and MongoDB, and I’ve used JSON Schema in some of my projects as well.

I really enjoy diving into technologies, understanding how they work, and contributing to improve them.
and I would love to apply for this project for GSoC!

Additionally, I have a small question the project

Could we clarify what "better" means in this context? Are we optimizing for code readability, historical precedence, performance in validation engines, or something else? For example, { "enum": ["foo", "bar"] } is more concise than { "oneOf": [{ "const": "foo" }, { "const": "bar" }] }, but does that alone make it the preferred form? Defining the exact criteria for "better" would help refine the normalization rules.

Thanks in advance for your help! 😊

[TheGreatCorrine]

Hi everyone, I have a question about handling the empty object {}. In JSON Schema, an empty object accepts any valid JSON value. I see several possible normalization approaches:

1. Keep as is: Maintain {} as {}
2. Expand to explicit form: Convert {} to {"type": ["null", "boolean", "object", "array", "string", "number", "integer"]}
3. Use other equivalent forms: For example {"additionalProperties": true}

I'd like to know which approach you think is most reasonable, and what factors might be considered in different contexts?
Thanks in advance for your insights!

[cbum-dev]

Hi everyone, I have a question about handling the empty object {}. In JSON Schema, an empty object accepts any valid JSON value. I see several possible normalization approaches:

1. Keep as is: Maintain `{}` as `{}`

2. Expand to explicit form: Convert `{}` to `{"type": ["null", "boolean", "object", "array", "string", "number", "integer"]}`

3. Use other equivalent forms: For example `{"additionalProperties": true}`

I'd like to know which approach you think is most reasonable, and what factors might be considered in different contexts? Thanks in advance for your insights!

I think keeping it {} is most appropriate because it follows the JSON Schema specification and keeps the schema as minimal as possible.

[TheGreatCorrine]

Hi everyone, I have a question about handling the empty object {}. In JSON Schema, an empty object accepts any valid JSON value. I see several possible normalization approaches:

1. Keep as is: Maintain `{}` as `{}`

2. Expand to explicit form: Convert `{}` to `{"type": ["null", "boolean", "object", "array", "string", "number", "integer"]}`

3. Use other equivalent forms: For example `{"additionalProperties": true}`

I'd like to know which approach you think is most reasonable, and what factors might be considered in different contexts? Thanks in advance for your insights!

I think keeping it {} is most appropriate because it follows the JSON Schema specification and keeps the schema as minimal as possible.

Yeah, I think it makes sense, that's why I mark it as the number one implementation.

[KajalMishra-29]

hi @Julian ,
I recently came across the "Investigating Schema Normalization" project and found it really interesting. I have some experience working with the MERN stack (MongoDB, Express, React, Node.js), where I worked with JSON data in API requests and stored JSON-like data in MongoDB. This experience gave me a strong connection to the concepts of JSON schema, which is why I find this project particularly appealing.
After going through the project details, I’d love to share my understanding of the project and how I plan to approach its implementation.

My Understanding of JSON Schema Normalization :

To me schema normalization means transforming different JSON Schemas that mean the same thing into a standard(canonical) form.

For example, normalization may involve:

1. Merging anyOf into a single type definition
   {"anyOf":[{"type": "String"}, {"type": "number"}]} -> {"type":["String","Number"]}
2. Sorting required fields alphabetically
   { "required": ["age", "name"] } → { "required": ["name", "age"] }
3. Removing redundant properties
   {"type":"String","enum":["apple"]} -> {"const": "apple"}
4. Removing unnecessary boolean values
   {"not": { type: "null" } → type: "object"}

Implementation Approach :

I am thinking for this a python-based library could be made
Identifying scenarios where normalization could be applied and applying normalization rules to each scenario independently
for ex : replace enum with a single value by const

def remove_redundant_properties(schema):
       if "enum" in schema and len(schema["enum"]) == 1:
        return {"const": schema["enum"][0]}
    return schema

{ "type": "string", "enum": ["apple"]} -> { "const": "apple" }

Is my understanding of schema normalization and the approach correct?
What tools or python libraries should I familiarize myself for this project?
I’d love to get your insights on how I can further refine my approach. Looking forward to your guidance.

[Kashika23]

@Julian
Hi, I am interested in contributing to the "Investigating Schema Normalization" project for GSoC 2025. JSON Schema provides multiple ways to define equivalent constraints, and this project aims to create a self-contained normalization tool that transforms schemas into a canonical form.
As a beginner in Python and JSON Schema, I want to improve my skills in schema validation, algorithm design, and software testing. I am eager to study existing normalization approaches, define rules, and implement a Python library for normalization. This project will deepen my understanding of structured data validation and improve my Python development skills.
I am looking forward to your guidance! I am eager to learn, collaborate, and deliver a tool that simplifies schema exploration for developers worldwide.

[Julian]

Hi all! Thanks for your interest, glad to hear some are excited!

Here's a qualification task for this idea:

Review the Hypothesis normalizer that I linked and document as many of the transformation rules you see it doing

If you manage that, another good thing to review is this egg tutorial which we'll likely review more carefully during the project itself, as I'd like to understand whether it can help with either the normalization process itself or else with doing optimizations on top of whatever we define.

As for those of you asking for precise definitions of "better": that is up to us to define as part of the project and it is likely there are multiple different normalizations and rulesets we can and will define. "Fastest for boolean validation" is certainly the most obvious one, and "Fastest for validation while preserving equivalent annotation results" is likely another.

Good luck to all of you and thanks again for your interest.

[TheGreatCorrine]

Hi all! Thanks for your interest, glad to hear some are excited!

Here's a qualification task for this idea:

Review the Hypothesis normalizer that I linked and document as many of the transformation rules you see it doing

If you manage that, another good thing to review is this egg tutorial which we'll likely review more carefully during the project itself, as I'd like to understand whether it can help with either the normalization process itself or else with doing optimizations on top of whatever we define.

As for those of you asking for precise definitions of "better": that is up to us to define as part of the project and it is likely there are multiple different normalizations and rulesets we can and will define. "Fastest for boolean validation" is certainly the most obvious one, and "Fastest for validation while preserving equivalent annotation results" is likely another.

Good luck to all of you and thanks again for your interest.

Hi @Julian ! I can't wait to start the qualification task! Would you prefer submissions directly in this issue thread (For example, submit a gist link, or directly attach a PDF file?) or through another channel?

[Julian]

The easiest is probably if you respond with a gist or repository I suppose yep!