Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Additional cleanup for dynamic references #1589

Merged
merged 1 commit into from
Mar 11, 2025

Conversation

jdesrosiers
Copy link
Member

@jdesrosiers jdesrosiers commented Feb 25, 2025

What kind of change does this PR introduce?

Clarification

Issue & Discussion References

Summary

This is mostly cleanup building on #1555, although I rewrote a couple of parts I though needed it.

The main objective is to achieve consistent and correct usage of terms around fragment identifiers. Here are the definitions I'm using.

  • fragment identifier -- This is an identifier for a secondary resource (subschema) within the primary resource (schema resource).
  • IRI fragment -- The fragment identifier that appears after the # character in an IRI.
  • plain name -- A specific type of fragment identifier. $anchor creates a plain name fragment identifier.
  • fragment-only IRI -- An IRI that starts with # and is followed by a fragment identifier.
  • fragment -- This term by itself is ambiguous and imprecise. I replaced all usages with a more precise term from the above terms.

Here's a list of the other notable changes.

  • Defining location-independent identifiers
    • I removed the language around constructing an IRI from the fragment identifier. All this section needs to do is define how plain name fragment identifiers are created. How to use a fragment identifier in any IRI is well established in RFC-3986/7 and doesn't need to be repeated here.
    • I tried to clarify that $dynamicAnchor does not create a fragment identifier. It's a special kind of identifier unique to the dynamic reference mechanism. Specifically, you can't use the identifier created by $dynamicAnchor in an IRI.
  • Dynamic References with $dynamicRef
    • I provided a new introduction for dynamic references that I think make sense. I've always thought that description was awful and I think this an improvement.
  • Example of recursive schema extension
    • I fixed a sentence that didn't make sense.

Everything else is minor grammar fixes or whitespace cleanup.

Does this PR introduce a breaking change?

No. (Actually, the issue this closes is a breaking change, but this PR doesn't break anything. This is just cleanup related to and around that change.)

@jdesrosiers jdesrosiers force-pushed the spec-cleanup-dynamic branch from 53f65c0 to ccff224 Compare March 11, 2025 03:50
@jdesrosiers jdesrosiers force-pushed the spec-cleanup-dynamic branch from ccff224 to 2bff2fd Compare March 11, 2025 03:54
@jdesrosiers jdesrosiers merged commit 086a872 into json-schema-org:main Mar 11, 2025
3 of 4 checks passed
@jdesrosiers jdesrosiers deleted the spec-cleanup-dynamic branch March 11, 2025 03:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Development

Successfully merging this pull request may close these issues.

Proposal: Remove initial resolution step for dynamic references
2 participants