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:

This topic is divided into the following sections:

Evidence Schema

This section describes the Evidence schema, including:

Query Entry Points

Evidence Queries

getEvidenceById

Fetch specific evidence by its unique identifier.

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

getEvidence

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

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.

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

getVersion

Fetch a Release Bundle version by its key parameters.

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

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 federation).JFrog AppTrust

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: