Skip to content

Conversation

@AnirudhJindal
Copy link

@AnirudhJindal AnirudhJindal commented Oct 27, 2025

Description

This PR adds support for the optional id property to the test schema, enabling stable identifiers for test cases and individual tests as discussed in #698.

Changes

  • Added optional id property to test case schema definition
  • Added optional id property to individual test schema definition ($defs/test)
  • Both id properties are optional (not in required array) for backward compatibility
  • Added detailed descriptions explaining ID requirements:
    • Must be unique within the version
    • Should never change even if description changes
    • Enables stable tracking across file reorganization

Specification References

This change enables the behavior discussed in #698 where test cases can be tracked over time even when:

  • Descriptions are clarified or modified
  • Tests are moved within files
  • Tests are recategorized between files

Schema Structure

Test Case Level

"id": {
  "description": "A stable, unique identifier for this test case. Must be unique within the version. Should never change even if the description or other properties change.",
  "type": "string"
}

Individual Test Level ($defs/test)

"id": {
  "description": "A stable, unique identifier for this test. Must be unique within the test case. Should never change even if the description or other properties change.",
  "type": "string"
}

Testing

  • Validated JSON syntax with python -m json.tool
  • Ran bin/jsonschema_suite check successfully
  • Verified schema structure is correct
  • Confirmed id is not in required arrays (optional for backward compatibility)
  • Added descriptive commit message following repository guidelines

Design Rationale

  • Optional now, required later: The property is initially optional to avoid breaking existing test files. Once all files have IDs, the property can be made required in a future PR.
  • Minimal change: Only adds the id property definition, no other modifications to the schema structure.

Related Issue

Relates to #698

Next Steps

After this PR is merged:

  1. Individual test files can be updated with UUID values (starting with enum.json)
  2. A sanity check can be added to verify ID uniqueness
  3. Once all files have IDs, the property can be made required

Review Notes

This is a foundational change that enables the work in #698. The actual addition of UUID values to test files will come in subsequent PRs (one file at a time per repository guidelines).

Looking forward to feedback! Happy to make any adjustments. :)

- Added optional id property for test cases with detailed description
- Added optional id property for individual tests in /test
- Both id properties are optional for backward compatibility
- IDs will be made required once all test files have them

The id property enables stable tracking of test cases and tests
across description changes and file reorganization.

Refs json-schema-org#698
@AnirudhJindal AnirudhJindal requested a review from a team as a code owner October 27, 2025 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant