Skip to content

Portable schema IDs cascade from the root document digest, so any root edit rotates every ID in generated output #117

Description

@jd-lara

Generated clients embed a _SCHEMA_RESOURCE_DATA table keyed by https://openapi.invalid/schema/.json. The labels are content-derived, and the derivation chains every label back to the root document's digest. The practical effect is that editing one field anywhere in the root spec rotates every schema ID in the generated package. So for every update in the schemas the changes are massive in the autogenerated code.

The source of this problem is here

src/normalize.jl, _portable_schema_ids:

labels = Dict{Resources.ResourceId,String}(
primary.id => "root-" * first(_content_digest(primary.contents), 20),
)
...
seed = parent * "|" * pointer * "|" * keyword
labels[target] = "external-" * first(bytes2hex(SHA.sha256(seed)), 20)

_content_digest is sha256 over the canonical JSON of the whole root document, so it covers info.version, info.description, and every unrelated part of the spec.

Each external- label is then seeded on its parent label, which is the root label for first-level references and another derived label deeper down. So the root digest propagates transitively into every ID in the graph.

The fix entails decoupleing each label from the root digest, so an ID changes only when that schema changes:

  • Seed external- labels on the target resource's own _content_digest, rather than on the parent label. Collisions already have handling via the -2, -3 suffix loop in the remaining branch just below.
  • Or seed on the structural reference path from a stable root identifier (for example the spec's info.title) instead of the root's content hash.

Either keeps IDs stable under unrelated root edits while preserving determinism and uniqueness.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions