Skip to content

Commit 0ddad0c

Browse files
speedstorm1copybara-github
authored andcommitted
fix: Preserve field description and title when process_schema inlines $ref
fixes #3007 PiperOrigin-RevId: 998818856
1 parent a216d95 commit 0ddad0c

2 files changed

Lines changed: 140 additions & 0 deletions

File tree

‎google/genai/_transformers.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -654,6 +654,16 @@ def _raise_for_unsupported_mldev_properties(
654654
raise ValueError('additionalProperties is only supported in Gemini Enterprise Agent Platform mode, , not in Gemini Developer API mode.')
655655

656656

657+
# Field-level annotations that override the referenced definition's values
658+
# when a '$ref' is inlined.
659+
_REF_SIBLING_ANNOTATIONS = ('description', 'title')
660+
661+
662+
def _ref_sibling_annotations(schema: _common.StringDict) -> _common.StringDict:
663+
"""Returns the annotations that `schema` declares beside its '$ref'."""
664+
return {key: schema[key] for key in _REF_SIBLING_ANNOTATIONS if key in schema}
665+
666+
657667
def process_schema(
658668
schema: _common.StringDict,
659669
client: Optional[_api_client.BaseApiClient],
@@ -766,11 +776,15 @@ def process_schema(
766776
# will have a $ref key that needs to be flattened
767777
# For example: {'default': None, 'description': 'Name of the person', 'nullable': True, '$ref': '#/$defs/TestPerson'}
768778
if (ref := schema.pop('$ref', None)) is not None:
779+
annotations = _ref_sibling_annotations(schema)
769780
schema.update(defs[ref.split('defs/')[-1]])
781+
schema.update(annotations)
770782

771783
def _recurse(sub_schema: _common.StringDict) -> _common.StringDict:
772784
"""Returns the processed `sub_schema`, resolving its '$ref' if any."""
785+
annotations: _common.StringDict = {}
773786
if (ref := sub_schema.pop('$ref', None)) is not None:
787+
annotations = _ref_sibling_annotations(sub_schema)
774788
sub_schema = defs[ref.split('defs/')[-1]]
775789
if id(sub_schema) in visited_dicts_path:
776790
return {}
@@ -782,6 +796,9 @@ def _recurse(sub_schema: _common.StringDict) -> _common.StringDict:
782796
order_properties=order_properties,
783797
visited_dicts_path=visited_dicts_path,
784798
)
799+
if annotations:
800+
# Copy, since the definition is shared by every reference.
801+
return {**sub_schema, **annotations}
785802
return sub_schema
786803

787804
if (any_of := schema.get('anyOf')) is not None:

‎google/genai/tests/transformers/test_schema.py‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,12 @@ class CountryInfoWithAnyOf(pydantic.BaseModel):
7878
restaurants_per_capita: Union[int, float]
7979

8080

81+
class _Score(pydantic.BaseModel):
82+
"""A generic score container."""
83+
84+
point: int
85+
86+
8187
@pytest.fixture
8288
def client(use_vertex):
8389
if use_vertex:
@@ -693,3 +699,120 @@ def test_t_schema_sets_property_ordering_for_schema_type(client):
693699

694700
transformed_schema = _transformers.t_schema(client, schema)
695701
assert transformed_schema.property_ordering == ['name', 'population']
702+
703+
704+
@pytest.mark.parametrize('use_vertex', [True, False])
705+
def test_t_schema_keeps_field_descriptions_on_shared_nested_model(client):
706+
"""Each field that references a shared model keeps its own description."""
707+
708+
class Review(pydantic.BaseModel):
709+
clarity: _Score = pydantic.Field(description='Rate clarity only.')
710+
accuracy: _Score = pydantic.Field(description='Rate factual accuracy only.')
711+
712+
schema = _transformers.t_schema(client, Review)
713+
714+
assert schema.properties['clarity'].description == 'Rate clarity only.'
715+
assert (
716+
schema.properties['accuracy'].description == 'Rate factual accuracy only.'
717+
)
718+
assert schema.properties['clarity'].properties['point'].type == 'INTEGER'
719+
assert schema.properties['accuracy'].properties['point'].type == 'INTEGER'
720+
721+
722+
@pytest.mark.parametrize('use_vertex', [True, False])
723+
def test_t_schema_keeps_field_description_on_optional_nested_model(client):
724+
"""An Optional nested-model field keeps its description when flattened."""
725+
726+
class Review(pydantic.BaseModel):
727+
clarity: Union[_Score, None] = pydantic.Field(
728+
default=None, description='Rate clarity only.'
729+
)
730+
731+
schema = _transformers.t_schema(client, Review)
732+
733+
assert schema.properties['clarity'].description == 'Rate clarity only.'
734+
assert schema.properties['clarity'].nullable
735+
736+
737+
@pytest.mark.parametrize('use_vertex', [True, False])
738+
def test_t_schema_keeps_field_title_on_nested_model(client):
739+
"""A nested-model field keeps its own title instead of the model name."""
740+
741+
class Review(pydantic.BaseModel):
742+
clarity: _Score = pydantic.Field(title='Clarity')
743+
744+
schema = _transformers.t_schema(client, Review)
745+
746+
assert schema.properties['clarity'].title == 'Clarity'
747+
748+
749+
@pytest.mark.parametrize('use_vertex', [True, False])
750+
def test_t_schema_uses_model_docstring_without_field_description(client):
751+
"""Without field annotations, the model docstring and name still apply."""
752+
753+
class Review(pydantic.BaseModel):
754+
clarity: _Score
755+
756+
schema = _transformers.t_schema(client, Review)
757+
758+
assert schema.properties['clarity'].description == (
759+
'A generic score container.'
760+
)
761+
assert schema.properties['clarity'].title == '_Score'
762+
763+
764+
@pytest.mark.parametrize('use_vertex', [True, False])
765+
def test_t_schema_ignores_unsupported_siblings_of_ref(client):
766+
"""Unsupported '$ref' siblings are dropped while the description is kept."""
767+
768+
class Review(pydantic.BaseModel):
769+
clarity: _Score = pydantic.Field(
770+
description='Rate clarity only.', examples=[{'point': 3}]
771+
)
772+
773+
schema = _transformers.t_schema(client, Review)
774+
775+
assert schema.properties['clarity'].description == 'Rate clarity only.'
776+
777+
778+
@pytest.mark.parametrize('use_vertex', [True, False])
779+
def test_process_schema_keeps_ref_sibling_description(client):
780+
"""Each '$ref' property gets its own copy carrying its own description."""
781+
schema = {
782+
'type': 'OBJECT',
783+
'properties': {
784+
'clarity': {
785+
'$ref': '#/$defs/Score',
786+
'description': 'Rate clarity only.',
787+
},
788+
'accuracy': {
789+
'$ref': '#/$defs/Score',
790+
'description': 'Rate factual accuracy only.',
791+
},
792+
},
793+
'$defs': {
794+
'Score': {
795+
'type': 'OBJECT',
796+
'description': 'A generic score container.',
797+
'properties': {'point': {'type': 'INTEGER'}},
798+
}
799+
},
800+
}
801+
802+
_transformers.process_schema(schema, client, order_properties=False)
803+
804+
assert schema == {
805+
'type': 'OBJECT',
806+
'properties': {
807+
'clarity': {
808+
'type': 'OBJECT',
809+
'description': 'Rate clarity only.',
810+
'properties': {'point': {'type': 'INTEGER'}},
811+
},
812+
'accuracy': {
813+
'type': 'OBJECT',
814+
'description': 'Rate factual accuracy only.',
815+
'properties': {'point': {'type': 'INTEGER'}},
816+
},
817+
},
818+
}

0 commit comments

Comments
 (0)