a2aproject / a2aproject/a2a-java

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

Offen
#506 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Java
Sterne
490
Forks
172
Ø Merge
1 T. 6 Std.
Gemergte PRs (30 T.)
55

Beschreibung

### 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](https://github.com/a2aproject/a2a-java/blob/cb084ec517f5511c45c0457850337b4b74431b10/spec/src/main/java/io/a2a/spec/Task.java#L68) 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](https://github.com/a2aproject/a2a-java/blob/cb084ec517f5511c45c0457850337b4b74431b10/spec/src/main/java/io/a2a/spec/TaskStatus.java#L46), the `message` is optional. We could make its type `Optional` 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

- [x] I agree to follow this project's Code of Conduct

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.