From a36dbef8849f6e550b34e2f012f74839764ebf89 Mon Sep 17 00:00:00 2001 From: Tim Zhang Date: Wed, 25 Feb 2026 14:24:48 +1100 Subject: [PATCH] api: update proto documentation --- README.md | 2 + api/v3/api.proto | 103 +++++++++++++++++++++++++++-- api/v3alpha/apiv3alpha.proto | 122 +++++++++++++++++++++++++++++++---- 3 files changed, 209 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 3d2235f1..78acc566 100644 --- a/README.md +++ b/README.md @@ -92,9 +92,11 @@ deps.dev aggregates data from a number of sources: - [Maven Central Repository](https://repo.maven.apache.org/maven2/) - [Google's Maven Repository](https://maven.google.com/) - [Jenkins' Maven Repository](https://repo.jenkins-ci.org/releases/) + - [Gradle Plugins Maven Repository](https://plugins.gradle.org/m2/) - [npm Registry](https://registry.npmjs.org/) - [NuGet](https://www.nuget.org/) - [PyPI](https://pypi.org/) + - [RubyGems](http://rubygems.org/) - Project data (including project names, descriptions, forks and stars, etc) - [GitHub](https://github.com/) - [GitLab](https://gitlab.com/) diff --git a/api/v3/api.proto b/api/v3/api.proto index e9c87f37..e57e416d 100644 --- a/api/v3/api.proto +++ b/api/v3/api.proto @@ -44,7 +44,7 @@ service Insights { // GetRequirements returns the requirements for a given version in a // system-specific format. Requirements are currently available for - // Maven, npm, NuGet and RubyGems. + // Go, Maven, npm, NuGet, RubyGems, PyPI, and Cargo. // // Requirements are the dependency constraints specified by the version. rpc GetRequirements(GetRequirementsRequest) returns (Requirements) { @@ -539,6 +539,7 @@ message Requirements { repeated Repository repositories = 5; // The list of profiles. repeated Profile profiles = 6; + string registry = 7; } // The Maven-specific representation of the version's requirements. // @@ -564,6 +565,12 @@ message Requirements { repeated Dependency runtime_dependencies = 1; // The list of development dependencies. repeated Dependency dev_dependencies = 2; + // Platform identifier for versions with platform specific code. + string platform = 3; + // The required version of Ruby. + string required_ruby_version = 4; + // The required version of RubyGems. + string required_rubygems_version = 5; } // The RubyGems-specific representation of the version's requirements. // @@ -572,6 +579,92 @@ message Requirements { // ecosystem. This is different to how it is used elsewhere in the deps.dev // API. RubyGems rubygems = 4; + + message Go { + message Dependency { + string name = 1; + string requirement = 2; + } + repeated Dependency direct_dependencies = 1; + repeated Dependency indirect_dependencies = 2; + } + // The Go-specific representation of the version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Go + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + Go go = 5; + + message PyPI { + message Dependency { + string project_name = 1; + string extras = 2; + string version_specifier = 3; + string environment_marker = 4; + } + // ExternalDependency represents dependencies that can't be managed by the + // Python package manager but must be installed on the consumer's system. + message ExternalDependency { + string name = 1; + string version_specifier = 2; + string environment_marker = 3; + } + // Extra represents Python's extra features/capabilities for this package. + // They are enabled in the items under the Requires-Dist. + message Extra { + string name = 1; + } + repeated Dependency dependencies = 1; + repeated Extra provided_extras = 2; + repeated ExternalDependency external_dependencies = 3; + string required_python_version = 4; + } + // The PyPI-specific representation of the version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Python + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + PyPI pypi = 7; + + message Cargo { + // Dependency represents a single dependency entry in a Cargo.toml file. + message Dependency { + string name = 1; + string requirement = 2; + // Whether this is a normal dependency, dev-dependency, or + // build-dependency. + string kind = 3; + // Whether this is an optional dependency. + bool optional = 4; + // The name of the package as it is used in the source code. + string package_alias = 5; + // Whether the dependency uses its default features. + bool uses_default_features = 6; + // Features that are enabled on this dependency. + repeated string features = 7; + // If present, then this dependency is specific to a given platform. + string target = 8; + } + + message Feature { + string name = 1; + // List of other features or dependencies that this feature would then + // enable. + repeated string implies = 2; + } + + repeated Dependency dependencies = 1; + repeated Feature features = 2; + } + // The Cargo-specific representation of a crate version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Cargo + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + Cargo cargo = 8; } // GetDependenciesRequest identifies a package version for which to return @@ -811,16 +904,16 @@ message ProjectPackageVersions { message Version { // The identifier for the version. VersionKey version_key = 1; + // What the relationship between the project and the package version is. + ProjectRelationType relation_type = 3; + // How the mapping between project and package version was discovered. + ProjectRelationProvenance relation_provenance = 4; // The SLSA provenance statements that link the version to the project. This // is only populated for npm package versions. See the 'attestations' field // for more attestations (including SLSA provenance) for all systems. repeated SLSAProvenance slsa_provenances = 2; // Attestations that link the version to the project. repeated Attestation attestations = 5; - // What the relationship between the project and the package version is. - ProjectRelationType relation_type = 3; - // How the mapping between project and package version was discovered. - ProjectRelationProvenance relation_provenance = 4; } // The versions that were built from the source code contained in this diff --git a/api/v3alpha/apiv3alpha.proto b/api/v3alpha/apiv3alpha.proto index 735cc776..773eb28a 100644 --- a/api/v3alpha/apiv3alpha.proto +++ b/api/v3alpha/apiv3alpha.proto @@ -53,7 +53,7 @@ service Insights { // GetRequirements returns the requirements for a given version in a // system-specific format. Requirements are currently available for - // Maven, npm and NuGet. + // Go, Maven, npm, NuGet, RubyGems, PyPI, and Cargo. // // Requirements are the dependency constraints specified by the version. rpc GetRequirements(GetRequirementsRequest) returns (Requirements) { @@ -175,10 +175,10 @@ service Insights { // Extra fields in the purl must be empty, otherwise the request will fail. // In particular, there must be no subpath or qualifiers. // - // Supported values for `type` are `cargo`, `golang`, `maven`, `npm`, `nuget` - // and `pypi`. Further details on types, and how to form purls of each type, - // can be found in the - // [purl spec](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst). + // Supported values for `type` are `cargo`, `gem`, `golang`, `maven`, `npm`, + // `nuget`, and `pypi`. Further details on types, and how to form purls of + // each type, can be found in the [purl + // spec](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst). // // Special characters in purls must be percent-encoded. This is described in // detail by the @@ -744,6 +744,7 @@ message Requirements { repeated Repository repositories = 5; // The list of profiles. repeated Profile profiles = 6; + string registry = 7; } // The Maven-specific representation of the version's requirements. // @@ -769,6 +770,12 @@ message Requirements { repeated Dependency runtime_dependencies = 1; // The list of development dependencies. repeated Dependency dev_dependencies = 2; + // Platform identifier for versions with platform specific code. + string platform = 3; + // The required version of Ruby. + string required_ruby_version = 4; + // The required version of RubyGems. + string required_rubygems_version = 5; } // The RubyGems-specific representation of the version's requirements. // @@ -777,6 +784,92 @@ message Requirements { // ecosystem. This is different to how it is used elsewhere in the deps.dev // API. RubyGems rubygems = 4; + + message Go { + message Dependency { + string name = 1; + string requirement = 2; + } + repeated Dependency direct_dependencies = 1; + repeated Dependency indirect_dependencies = 2; + } + // The Go-specific representation of the version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Go + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + Go go = 5; + + message PyPI { + message Dependency { + string project_name = 1; + string extras = 2; + string version_specifier = 3; + string environment_marker = 4; + } + // ExternalDependency represents dependencies that can't be managed by the + // Python package manager but must be installed on the consumer's system. + message ExternalDependency { + string name = 1; + string version_specifier = 2; + string environment_marker = 3; + } + // Extra represents Python's extra features/capabilities for this package. + // They are enabled in the items under the Requires-Dist. + message Extra { + string name = 1; + } + repeated Dependency dependencies = 1; + repeated Extra provided_extras = 2; + repeated ExternalDependency external_dependencies = 3; + string required_python_version = 4; + } + // The PyPI-specific representation of the version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Python + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + PyPI pypi = 7; + + message Cargo { + // Dependency represents a single dependency entry in a Cargo.toml file. + message Dependency { + string name = 1; + string requirement = 2; + // Whether this is a normal dependency, dev-dependency, or + // build-dependency. + string kind = 3; + // Whether this is an optional dependency. + bool optional = 4; + // The name of the package as it is used in the source code. + string package_alias = 5; + // Whether the dependency uses its default features. + bool uses_default_features = 6; + // Features that are enabled on this dependency. + repeated string features = 7; + // If present, then this dependency is specific to a given platform. + string target = 8; + } + + message Feature { + string name = 1; + // List of other features or dependencies that this feature would then + // enable. + repeated string implies = 2; + } + + repeated Dependency dependencies = 1; + repeated Feature features = 2; + } + // The Cargo-specific representation of a crate version's requirements. + // + // Note that the term "dependency" is used here to mean "a single + // requirement" to be consistent with how the term is used in the Cargo + // ecosystem. This is different to how it is used elsewhere in the deps.dev + // API. + Cargo cargo = 8; } // GetDependenciesRequest identifies a package version for which to return @@ -1094,16 +1187,17 @@ message ProjectPackageVersions { message Version { // The identifier for the version. VersionKey version_key = 1; + // What the relationship between the project and the package version is. + ProjectRelationType relation_type = 3; + // How the mapping between project and package version was discovered. + ProjectRelationProvenance relation_provenance = 4; + // The SLSA provenance statements that link the version to the project. This // is only populated for npm package versions. See the 'attestations' field // for more attestations (including SLSA provenance) for all systems. repeated SLSAProvenance slsa_provenances = 2; // Attestations that link the version to the project. repeated Attestation attestations = 5; - // What the relationship between the project and the package version is. - ProjectRelationType relation_type = 3; - // How the mapping between project and package version was discovered. - ProjectRelationProvenance relation_provenance = 4; } // The versions that were built from the source code contained in this @@ -1167,15 +1261,17 @@ message SimilarlyNamedPackages { // At least one of its fields must be set, and both fields may be set to narrow // the results. message QueryRequest { - // A content hash for an artifact associated with a package version, such as a - // JAR file. Currently supported for npm, Cargo, Maven, and NuGet. Note that - // hashes and package versions have a many-to-many relationship. + // A content hash for an artifact associated with a package version, such as + // a JAR file. Currently supported for npm, Cargo, Maven, NuGet, PyPI, and + // RubyGems. Note that hashes and package versions have a many-to-many + // relationship. Hash hash = 1; // The name of the package version. VersionKey version_key = 2; } + // QueryResult holds information about package versions matching the query. message QueryResult { message Result { @@ -1183,7 +1279,7 @@ message QueryResult { Version version = 1; // An artifact is content associated with a package version, such as a JAR - // file. Currently supported for npm, Cargo, Maven, and NuGet. + // file. Currently supported for npm, Cargo, Maven, NuGet, PyPI and RubyGems. message Artifact { // The origin of the artifact with this hash. string url = 1;