Improved deserialization of AI citation models

[Rodrigo Brandão (rodrigobr-msft)]

This pull request improves the serialization and deserialization of schema.org-style @id, @type, and @context fields in entity models, ensuring that these fields are handled consistently and only included when defined in the model. It also adds comprehensive tests to verify the correct behavior for models with and without an at_id field.

Enhancements to schema field serialization/deserialization:

• Refactored the handling of @type, @context, and @id fields in _schema_mixin.py by introducing helper functions _deserialize_at_field and _serialize_at_field, ensuring these fields are only set or serialized if defined in the model or if extra fields are allowed. This prevents unintended attributes from being added to models.
• Updated validate_schema_model and serialize_schema_model to use the new helper functions, improving maintainability and correctness of schema field processing.

Model updates:

• Added an optional at_id field to the ClientCitation model to support deserialization and serialization of the @id property.

Testing improvements:

• Added tests to verify that models without an at_id field ignore the @id property during (de)serialization, and that models with at_id handle it correctly. Also added tests for nested deserialization scenarios (e.g., Activity containing a ClientCitation).
• Included missing import of Activity in the serialization test module to support new tests.

[Copilot]

Copilot review overview

🟡 Changes recommended

Schema values currently bypass Pydantic validation, and the new deserialization helper is an unused no-op.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Validate declared schema fields before assigning values · New
• Remove or invoke unused schema deserialization helper · New

What changed in this PR

Improves schema.org field handling for AI citation entities.

Changes:

• Adds optional @id support to ClientCitation.
• Refactors schema-field serialization and deserialization.
• Adds direct and nested citation tests.

File	Description
_schema_mixin.py	Refactors @type, @context, and @id handling.
ai_entity.py	Adds at_id to ClientCitation.
test_serialization.py	Tests schema-ID handling and nested deserialization.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Schema aliases are no longer emitted for programmatically supplied fields on models that allow extras.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Validate declared schema fields before assigning values
• Remove or invoke unused schema deserialization helper

Previously missed (1)

In code that hasn't changed since last review

Preserve schema aliases for programmatically supplied extra fields

libraries/​microsoft-agents-activity/​microsoft_agents/​activity/​entity/​_schema_mixin.py:66

This drops schema aliases for programmatically supplied extras. Entity allows extra fields and uses this serializer, so Entity(type="custom", at_id="schema-id").model_dump(by_alias=True) previously included "@id" but now emits only the ordinary atId extra. The validator explicitly treats schema fields as valid when extras are allowed, so serialization should retain that same path rather than returning solely because the field is not declared.