Evidence Service GraphQL Schema

The JFrog Evidence service provides a comprehensive GraphQL API for querying evidence and Release Bundle information. This API follows the ​OneModel​ GraphQL ​conventions​​ and supports pagination, filtering, and federated queries.

Key features include:

• Evidence management​​: Query and search evidence associated with artifacts.
• ​​Release Bundle queries​​: Access Release Bundle version, artifacts, and their relationships.
• ​​Pagination support​​: Cursor-based pagination for handling large result sets.
• ​​Filtering and ordering​​: Advanced filtering and sorting capabilities.
• ​​Federation support​​: Compatible with ​Apollo Federation​​ for distributed architectures. Apollo Federation enables you to declaratively combine multiple APIs into a single federated GraphQL API.

This topic is divided into the following sections:

• ​​Evidence Schema
• ​​Release Bundle Schema
• ​​Common Types and Conventions
• ​​Query Examples
• ​​Application Version Query Example
• ​​Best Practices

Evidence Schema

This section describes the Evidence schema, including:

• ​​Query Entry Points
• ​​Evidence Queries
• ​​Input Types
• ​​Output Types

Queue Entry Points

Evidence Queries

getEvidenceById

Fetch specific evidence by its unique identifier.

• Parameters​​: ​id​​ (String!, required): Unique identifier of the evidence.
• ​​Returns​​: Evidence or null if not found.

query {
  evidence {
    getEvidenceById(id: "evidence-123") {
      id
      name
      predicateType
      createdBy
      createdAt
    }
  }
}

getEvidence

Fetch evidence by repository key, path, name, and optional SHA-256 hash.

• Parameters:
  • ​​repositoryKey​​ (String!, required): Repository key (e.g., my-repo-key).
  • ​​path​​ (String!, required): Path within the repository (e.g., artifacts/path).
  • ​​name​​: (String!, required): Name of the evidence file (e.g., evidence.json).
  • ​​sha256​​: (Sha256, optional): SHA-256 hash of the evidence.
• Returns: Evidence or null if not found.

query {
  evidence {
    getEvidence(
      repositoryKey: "my-repo-key",
      path: "artifacts/path",
      name: "evidence.json"
    ) {
      id
      predicateType
      verified
    }
  }
}

searchEvidence

Search for evidence with advanced filtering and pagination.

• Parameters:
  • where​​ (EvidenceWhereInput!, required): Filter specification.
  • ​​first​​ (Int, optional): Number of items per page.
  • ​​after​​: (Cursor, optional): Cursor for pagination.
• Returns: EvidenceConnection​ with ​edges​​, ​pageInfo​​, and ​totalCount. ​

query {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          repositoryKey: "my-repo-key"
          path: "artifacts/path"
        }
      }
      first: 10
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        cursor
        node {
          id
          name
          predicateType
          createdBy
        }
      }
    }
  }
}

Input Types

Evidence GraphQL queries accept the following input types.

Output Types

Evidence GraphQL queries feature the following output types.

Evidence

Represents artifact (subject) evidence.

EvidenceSigningKey

EvidenceSubject

Release Bundle Schema

This section describes the Release Bundle v2 schema. It is divided into the following subsections:

• Query Entry Points
• ​​Release Bundle Queries
• ​​Output Types
• ​​EvidenceConnection and ArtifactConnection Wrapper

Query Entry Points

Release Bundle Queries

getVersion

Fetch a Release Bundle version by its key parameters.

• Parameters:
  • ​​name​​: (String!, required): Name of the Release Bundle.
  • ​​version​​ (String!, required): Version of the Release Bundle.
  • ​​repositoryKey​​ (String, optional): Repository key (default: release-bundles-v2).
  • ​​projectKey​​: (String, optional): Project key (will use the project's default repo, if provided).
• Returns: ReleaseBundleVersion or null if not found.

query {
  releaseBundleVersion {
    getVersion(
      name: "my-release-bundle",
      version: "1.0.0"
    ) {
      createdBy
      createdAt
      artifactsConnection(first: 10) {
        totalCount
        edges {
          node {
            name
            path
            packageType
          }
        }
      }
    }
  }
}

Output Types

Release Bundle v2 GraphQL queries feature the following output types.

ReleaseBundleVersion

Represents a Release Bundle v2 version.

ReleaseBundleVersionArtifactConnection

Arguments:

ReleaseBundleVersionArtifactEdge

ReleaseBundleVersionBuild

Represents a build within a ReleaseBundle version.

ReleaseBundleVersionArtifact

Represents an artifact within a Release Bundle version.

EvidenceConnection and ArtifactConnection Wrapper Structure

The wrapper for evidenceConnection should have the following format:

evidenceConnection { totalCount edges { node { predicateSlug predicateType...}}}

The wrapper for artifactConnection should have the following format:

artifactConnection { totalCount edges { node { path name ...}}}

Common Types and Conventions

Pagination

The API uses Relay cursor-based pagination for all list queries.

Scalar Types

Directives

Query Examples

This section includes the following query examples:

• ​Example 1: Search Evidence by Subject
• ​​Example 2: Get Release Bundle with Artifacts and Evidence

Example 1: Search Evidence by Subject

Searches for evidence associated with a specific artifact as defined by its repository key, path, and name.

query SearchEvidenceBySubject {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          repositoryKey: "my-docker-repo"
          path: "images"
          name: "my-app"
        }
      }
      first: 20
    ) {
      totalCount
      pageInfo { hasNextPage, endCursor }
      edges {
        node {
          id
          name
          predicateType
          createdAt
          verified
          predicate
        }
      }
    }
  }
}

Example 2: Get Release Bundle with Artifacts and Evidence

Retrieves a specific Release Bundle v2 version, its associated artifacts (filtered for those with evidence), and the evidence for both the bundle and its artifacts.

query GetReleaseBundleWithDetails {
  releaseBundleVersion {
    getVersion(
      name: "my-release-bundle"
      version: "1.0.0"
    ) {
      createdBy
      createdAt
      
      # Get artifacts in the release bundle
      artifactsConnection(
        where: { hasEvidence: true }
        first: 50
      ) {
        edges {
          node {
            name
            sha256
            sourceRepositoryPath
            # Get evidence for each artifact
            evidenceConnection(first: 10) {
              totalCount
              edges {
                node {
                  id
                  predicateType
                  verified
                }
              }
            }
          }
        }
      }
      
      # Get evidence for the release bundle itself
      evidenceConnection(first: 10) {
        edges {
          node {
            id
            predicateType
            verified
          }
        }
      }
    }
  }
}

Application Version Query Example

For customers with ​AppTrust​​, the following example fetches an application version from the AppTrust service and retrieves its associated evidence (resolved by the Evidence service via ​Apollo Federation​​).

Query:

query GetApplicationVersionWithEvidence {
  applications {
    getApplicationVersion(
      applicationKey: "my-app"
      version: "1.0.0"
    ) {
      application {
        key
        displayName
      }
      version
      tag
      createdAt
      createdBy
      status
      releaseStatus
      
      # Evidence fields resolved by Evidence service via federation
      evidence(first: 10, verified: true) {
        id
        name
        predicateType
        predicateCategory
        verified
        createdAt
        createdBy
        subject {
          fullPath
          repositoryKey
          path
          name
        }
      }
    }
  }
}

Response:

{
  "data": {
    "applications": {
      "getApplicationVersion": {
        "application": {
          "key": "my-app",
          "displayName": "My Application"
        },
        "version": "1.0.0",
        "tag": "release-v1.0.0",
        "createdAt": "2024-11-20T10:00:00Z",
        "createdBy": "ci-system",
        "status": "COMPLETED",
        "releaseStatus": "RELEASED",
        "evidence": [
          {
            "id": "evidence-123",
            "name": "build-attestation",
            "predicateType": "https://slsa.dev/provenance/v1",
            "predicateCategory": "BUILD",
            "verified": true,
            "createdAt": "2024-11-20T10:15:00Z",
            "createdBy": "ci-system",
            "subject": {
              "fullPath": "npm-local/artifacts/my-app/1.0.0",
              "repositoryKey": "npm-local",
              "path": "artifacts/my-app",
              "name": "1.0.0"
            }
          }
        ]
      }
    }
  }
}

Best Practices

We recommend the following best practices when preparing Evidence GraphQL queries:

• ​​Use pagination for large result sets​​

  Always specify ​first​ and use the ​after​​ cursor for subsequent pages to handle large result sets efficiently.

• ​​Request only required fields​​

  Request only the fields necessary to minimize response size and improve query performance. For example:

  query {
    evidence {
      getEvidenceById(id: "123") {
        id
        predicateType
        verified
      }
    }
  }

• ​​Use filters to narrow results​​

  Apply filtering criteria (e.g., ​where​​ arguments) directly in the GraphQL query instead of fetching large datasets and filtering in the application layer.

• ​​Use variables for dynamic queries​​

  Define variables for dynamic values to make queries cleaner and reusable.

  query GetEvidence($repoKey: String!, $path: String!, $name: String!) {
    evidence {
      getEvidence(
        repositoryKey: $repoKey
        path: $path
        name: $name
      ) {
        id
        verified
      }
    }
  }