Describe the last undocumented fields (drift → 0) - #159
Merged
Conversation
Closes the uniform half of what the schema audit found: 161 -> 83 undocumented fields, 93 -> 50 endpoints, with the suite still passing. The `_links` group is gone entirely, and it was the bulk — 61 fields, 57% of all occurrences. v1 declared its links object with no properties at all while using it for every entity, so `_links.webui` existed at runtime and nowhere in the types. Now it is typed. `version.ncsStepVersion` and `version.contributorIds` follow, along with the `_expandable` keys Confluence has grown since the spec was written. Types are what the API actually returned. `ncsStepVersion` is nullable because responses came back null; `contributorIds` keeps an open element type because every array observed was empty, and a guessed element type would read as breakage rather than as drift. 79 fields remain, with no shape in common — `ari`, `operations`, the `container` group, user fields like `locale`. Each needs deciding which schema owns it, so they are a separate pass.
161 undocumented fields across 93 endpoints down to 7 across 5, with the suite passing 493/493. This is the long tail the first pass deliberately left: fields with no shape in common, each needing a decision about which schema owns it. `Container` turned out to be a second empty schema, like the links one before it — declared with no properties at all while naming the parent of every piece of content. Ten fields, including its own `_links`. The rest are one-offs: `ari` and `base64EncodedAri`, `accountStatus` and `locale` across the three separate user schemas that each lag differently, `resolutionStatus` on comments, `operations` and `properties` on the newer v2 entities. Seven remain. Each sits either behind an inline response schema with no name to target, or behind a collection whose item schema differs from the single-entity one — both want a proper look rather than a guess, and the audit will keep reporting them until they get one.
Brings develop up to 3.0.1: the version bump, the cleared changesets, and the release workflow now publishing via changeset publish. develop matches master.
The remaining seven the schema audit reported: Version's comment/attachment, the like collection's count, the hyphenated inline-comment property keys, the async content-body's content, and noAccessEmails on the check-access response. Drift is now 0.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Promotes the last of the schema-drift work to
masterfor release3.0.2.What's here
The final undocumented fields. After the previous release closed 154 of them, the audit still reported seven:
comment/attachmenton a version returned inside aversionscollection, thecounton a like collection's meta, the hyphenatedinline-marker-ref/inline-original-selectioninline-comment property keys, the async content-body'scontent, andnoAccessEmailson the check-access-by-email response. All are now described, and a live audit run against the tenant reports no drift at all (161 → 0 over the two releases).Changeset describing the above for the changelog.
Five of the seven had a named component to point at;
noAccessEmailsdid not — its response is declared inline on the operation — so the generator side gained a small reusable mechanism for patching inline responses by<method> <path>. That change lives in the generator, not here; this PR is the regenerated output plus its changeset.Every addition is optional and additive: nothing that used to type-check stops doing so, runtime validation is unchanged, and no field is renamed or removed.
Release note
Once merged, the workflow updates the Version Packages PR to
3.0.2; merging that publishes3.0.2. This is also the first real exercise of thechangeset publishswitch — the publish should now tagv3.0.2and cut its GitHub release on its own.