Refine multi-value vocab references

[sij411]

Summary

• Replace the public OneOrMany<T> helper with References<T> for zero-or-more ActivityStreams fields
• Keep scalar-or-array deserialization internally while exposing a semantic collection API
• Serialize References<T> as a scalar for one value and an array for multiple values
• Document the intended containing-field pattern: #[serde(default, skip_serializing_if = "References::is_empty")]
• Add tests for absent-vs-empty equivalence and scalar/array recipient shapes

Context

This follows up on the issue #5 discussion about Option<OneOrMany<T>> representing states JSON-LD does not distinguish. In JSON-LD, an absent property and an empty array are equivalent for multi-valued fields, so exposing both None and Some(Many([])) would make callers handle a meaningless distinction.

References<T> represents the semantic state directly:

• absent property -> empty collection
• empty array -> empty collection
• scalar value -> one item
• array -> many items

Reference<T> remains the singular ID-or-embedded-object helper. References<T> is for fields that can appear zero or more times.

Validation

• cargo fmt --check
• cargo check -p feder-vocab --lib
• cargo test
• mise run check

Summary by CodeRabbit

Release Notes

• Breaking Changes

  • Updated how multiple values are handled for ActivityStreams properties; serialization and deserialization behavior adjusted.

• Tests

  • Updated test suite to validate new serialization and deserialization behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 61354e07-45f1-4ce0-b2ff-964fdea15a2e

📥 Commits

Reviewing files that changed from the base of the PR and between ae71392 and a6e68cb.

📒 Files selected for processing (2)

• crates/feder-vocab/src/lib.rs
• crates/feder-vocab/tests/phase1_shapes.rs

---

📝 Walkthrough

Walkthrough

The PR replaces the OneOrMany<T> enum with a new References<T> struct that wraps a Vec<T> and implements custom serde logic to serialize empty values as [], single values as scalars, and multiple values as JSON arrays—conforming to ActivityStreams conventions. Tests are updated to validate deserialization, serialization, and field-omission behavior.

Changes

References Container Implementation

Layer / File(s)	Summary
References struct and serde implementations crates/feder-vocab/src/lib.rs	References<T> wraps an internal Vec<T>, exposes constructors (new, one, many) and accessors (is_empty, len, iter, into_vec), and implements custom Serialize/Deserialize to map empty to [], single values to JSON scalars, and multiple values to JSON arrays.
References validation tests crates/feder-vocab/src/lib.rs, crates/feder-vocab/tests/phase1_shapes.rs	Unit tests validate References<Iri> deserialization from both scalar and array JSON forms. Integration tests verify serialization behavior for empty, single, and multi-value cases, and confirm that absent and empty-array fields both deserialize as empty and serialize with field omission.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fedify-dev/feder#13: Introduces OneOrMany<T> container and recipient-shape tests that this PR directly replaces with the new References<T> implementation.

Suggested labels

enhancement, phase 1

Poem

🐰 A container born anew,
OneOrMany's work is through,
References now wraps the Vec with care,
Empty, single, many—all laid bare,
ActivityStreams flows with flair! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 63.16% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Refine multi-value vocab references' clearly and accurately summarizes the main change—replacing OneOrMany with References for handling multi-value ActivityStreams properties.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[sij411]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.