refactor(dpp)!: keep the property type shorthand expansion out of shipped generations

[QuantumExplorer]

Basic explanation

Follow-ups to #5355 (the "type": "identifier" and "type": "bytes" shorthands) from its review, which landed after it merged. Nothing changes for a valid contract. The shorthand rewrite now lives only in code that protocol version 14 alone selects, instead of being added to code that also runs for protocol versions 1 to 13, and three documentation statements that were wrong for shorthands are corrected.

Issue being fixed or feature implemented

The review of #5355 found three blocking defects, fixed in that PR before it merged, and a set of non-blocking ones that it never got to. This PR takes the ones worth fixing:

• feat(dpp)!: add identifier and bytes property type shorthands (PV14) #5355 called the rewrite from two places that earlier protocol versions also run: the contract update comparison helpers shared with validate_update generation 0, and create_document_types_from_document_schemas generation 1 (protocol versions 2 to 14). Both edits were inert before 14, but each needed a written argument that it was, and the second is the code that briefly made stored token-only contracts unreadable at 14 (fixed in feat(dpp)!: add identifier and bytes property type shorthands (PV14) #5355). The repository rule is that a shipped generation is edited only when that cannot be avoided.
• Three documentation statements were wrong for shorthands: the wasm-dpp2 typed-array typing, the DocumentType::schema() doc, and the typed-arrays book chapter.

What was done?

The update comparison expands inside validate_schema_compatibility 1. That generation is selected only by protocol version 14, and both comparisons go through it: the document type schema diff and the {"$defs": ..} diff. It now rewrites both sides (with_shorthands_expanded: JSON to Value, expand, back to JSON, only when a shorthand is present) before its existing prepared_for_diff. The two shared helpers (DocumentTypeRef::validate_schema_with_options, DataContract::validate_update_schema_defs) are back to their code before #5355.

Before (in a helper shared with generation 0):

let old_expanded_schema =
    DocumentType::expand_property_type_shorthands(self.schema(), false, platform_version)?;
...
let mut old_document_schema_json = match old_schema.try_to_validating_json() {

After (generation 1 only):

pub(super) fn validate_schema_compatibility_v1(original_schema, new_schema, platform_version) {
    let original_schema = with_shorthands_expanded(original_schema, platform_version)?;
    let new_schema = with_shorthands_expanded(new_schema, platform_version)?;
    let original_schema = prepared_for_diff(&original_schema);
    ...

The contract-level $defs expansion in create_document_types_from_document_schemas 1 is removed. Parser generation 3 already expands the contract's $defs for each document type (it has to, since DataContract::set_document_schema hands it the raw definitions), so the contract-level copy only saved one clone per document type, and only when a definition uses a shorthand. The one contract-level reader that saw the expanded definitions, validate_property_constraint_aggregates, reads only enum, which the rewrite never changes. A contract without document types still has its $defs left as sent: no document type parse runs.

Docs.

Where	Was	Now
wasm-dpp2 DocumentTypedArrayItem	"A bound is absent when the schema omits it."	Bounds come from the parsed element: a bytes element reports its size as minItems/maxItems; an identifier reports none
wasm-dpp2 DocumentTypedArrayProperty	contract.toJSON() and the accessors "line up key for key"	toJSON() shows the schema as sent; items gives the parsed kind and bounds
DocumentTypeV0Getters::schema	read types from expand_property_type_shorthands of this schema	schema_defs() may hold shorthands too; a raw read that follows a $ref expands the enriched root, which rewrites properties and $defs together
book, typed-arrays element keywords	list without size	size (on a bytes element) added

v14 note 91 now names validate_schema_compatibility 1 as the update comparison's rewrite and mentions the check_tx depth pre-check, which #5355 made walk the rewritten schema.

In-place changes to shipped generations

None added. This PR removes the two that #5355 made:

Generation	Selected by	Change
validate_update helpers shared with generation 0 (validate_schema_with_options, validate_update_schema_defs)	protocol versions 1 to 14	Restored to their code before #5355
create_document_types_from_document_schemas 1	protocol versions 2 to 14	Restored to its code before #5355

validate_schema_compatibility 1 and parser generation 3 are selected only by protocol version 14, which is unreleased.

How Has This Been Tested?

• dpp, new in validate_schema_compatibility/v1: should_compare_a_shorthand_as_the_long_form_it_stands_for (a property and a definition rewritten between the spellings, both directions, no change) and should_still_report_a_change_behind_a_shorthand (an identifier definition turned into bytes is reported at /$defs/owner/contentMediaType).
• dpp, existing from feat(dpp)!: add identifier and bytes property type shorthands (PV14) #5355 and passing unchanged: the update between spellings accepted end to end through DataContract::validate_update, protocol version 13 judging updates as before, contracts registered at 13 with unread shorthand-shaped values reading back at 14, a shorthand and its long form parsing to identical document types.
• drive: add_version_items_to_all_contracts reads contracts stored at 13 that hold such values.
• drive-abci: the end-to-end shorthand test (signed create, queries with and without proof, signed update between spellings), the check_tx depth regression, and the contract create and update suites.
• cargo test -p dpp, cargo test -p platform-version, cargo test -p wasm-dpp2; targeted drive and drive-abci filters; cargo clippy --all-features --all-targets -D warnings on dpp, platform-version and wasm-dpp2; cargo fmt --all.

Breaking Changes

None for any released protocol version: every edit is inert before protocol version 14, and two edits restore code that runs before 14 to its exact previous form.

At protocol version 14 (unreleased) a valid contract parses and compares exactly as before. The one observable difference is the order of two refusals: a malformed shorthand in the contract's $defs used to be refused before any document type was parsed, and is now refused inside the first document type's parse, after that parse's check for a - in the type name. A contract that breaks both (a - in its first document type's name and a malformed shorthand definition) now gets InvalidDocumentTypeNameError instead of InvalidContractStructure (10231). Nodes running PV14 builds from before and after this change could therefore disagree on that one refusal, hence the !.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed
• If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · e113bf4

• Bots — coderabbitai not yet · thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
• Self-review — post /self-reviewed
• Build running
• Approvals — you own every area touched; none needed

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 37 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: dashpay/platform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 57f91feb-b65a-47c8-b559-cae86ea9924b

---

📥 Commits

Reviewing files that changed from the base of the PR and between ac12d70 and e113bf4.

---

📒 Files selected for processing (10)

• book/src/contract-keywords/typed-arrays.md
• packages/rs-dpp/src/data_contract/document_type/accessors/v0/mod.rs
• packages/rs-dpp/src/data_contract/document_type/class_methods/create_document_types_from_document_schemas/v1/mod.rs
• packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v3/mod.rs
• packages/rs-dpp/src/data_contract/document_type/methods/validate_update/common/mod.rs
• packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/mod.rs
• packages/rs-dpp/src/data_contract/document_type/schema/validate_schema_compatibility/v1/mod.rs
• packages/rs-dpp/src/data_contract/methods/validate_update/common/mod.rs
• packages/rs-platform-version/src/version/v14.rs
• packages/wasm-dpp2/src/data_contract/document_type_typed_arrays.rs

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📖 Book Preview built successfully.

Download the preview from the workflow artifacts.
To view locally: download the artifact, unzip, and open index.html.

Updated at 2026-10-09T12:41:04.113Z

[github-actions]

Waiting for bot review — coderabbitai not yet · thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

[thepastaclaw]

🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.

• Request normal review — click when the PR is ready for review.
• Request priority review — click to move this review to the front of the queue.

Commit e113bf4. Normal review starts when eligible; priority review starts as soon as a slot is available.