[Feat]: Clarify nullability and optionality of the spec API

Open
#506 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Stale
Tech stack
java
Domain
api

Research direction

Examine the Task and TaskStatus classes in the spec module to understand current nullability patterns. Review the spec API's design principles and consistency rules. Determine which fields should be Optional and which collections should default to empty. Update the classes, ensure backward compatibility, and revise Javadoc accordingly.

Written by the indexing model from the issue text.

Description

Is your feature request related to a problem? Please describe.

The spec API is not consistent with this expectation for the nullability and optionality of objects.

For example, the Task class
will always instantiate its history and artifact with (potentially empty) collections while its metatada can be null.
The API should be consistent unless there is a good reason not to.
In that case, the metadata should also be an empty Map if the parameter is null.

For case where we want to record that a field can have a value or be null, we could also leverage Optional.
For example, in TaskStatus, the message is optional. We could make its type Optional<String> to constrain its contract.

Describe the solution you'd like

Update the spec API to:

  • be consistent with the nullabitity of fields (especially collections)
  • use the Optional type for optional fields
  • update the javadoc when there is exception to this general rule
Describe alternatives you've considered

No response

Additional context

No response

Code of Conduct
  • I agree to follow this project's Code of Conduct
Dominant language
Java
Stars
514
Forks
200
Avg merge
1d 2h
Merged PRs (30d)
53

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from a2aproject/a2a-java

All issues in a2aproject/a2a-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.