One Model GraphQL Common Patterns and Conventions

This section includes patterns and conventions that are applied across all One Model domains:

Namespaces and Queries

Each domain in the JFrog Platform model is mapped to a namespace, which is represented by a field in the GraphQL root query. The namespace field itself contains the actual queries.

Queries are named according to the following convention:

search... for queries that return a list of items (the list can be empty)
get... for queries that return a single item (the item can be null)

For example, the following query returns a list of Evidences in a specific repository:

query {
  # Namespace for Evidence business-domain
  evidence {
    # Query to search for evidence items in a specific repository
    searchEvidence(where: {hasSubjectWith: {repositoryKey: "example-repo-local"}}) {
      # Field(s) to include in the result set
      totalCount
    }
  }
}

Search queries usually accept the following arguments to filter and order the results:

where: a filter object that contains the filtering criteria
orderBy: a filter object that defines the result ordering (e.g. orderBy: {field: LICENSE, direction: ASC} will sort according to the LICENSE field in ascending order)

Note

The where and orderBy arguments are not supported for all queries: check the specific query before using these arguments.

Pagination

Some search queries provide paginated results to allow the handling of very large result sets. In these cases, pagination is cursor-based and implemented according to the widely-adopted Relay style.

For example, the following query returns a paginated list of evidence items:

query {
  evidence {
    searchEvidence(where: {hasSubjectWith: {repositoryKey: "example-repo-local"}}) {
      # Items of the current page
      edges {
        node {
          # Evidence fields for the current item
          name
          verified
        }
        # Cursor value for the current item
        cursor
      }
      # Information about the current page
      pageInfo {
        # Whether there are more items in the next page
        hasNextPage
        # Cursor value for the last item in the current page
        endCursor
      }
    }
  }
}

To iterate over pages, use the following query arguments:

first: the number of items to include in the page
after: the cursor value of the item after which to fetch the page, which is usually the last item in the previous page.

Paginated queries may also support backward pagination, which is implemented in the same way as forward pagination but with the following arguments:

last: the number of items to include in the page
before: the cursor value of the first item in the next page

Note

Note the following guidelines for using pagination:

The default values for pagination query arguments first and last depend on each query
after is optional: in forward pagination, if not provided, the first page is fetched. The same logic applies for backwards pagination, where last is optional
If none of first/last/after/before is provided, the first page is returned in default size
first/after and last/before are mutually exclusive and cannot be used in the same query.

Field Values

Date Values

Fields ending with ...At (e.g. createdAt) are used to represent timestamp values (date and time).

By default, timestamps are shown using the ISO-8601 format in UTC timezone (marked by the Z suffix), for instance: 2024-11-05T13:15:30.972Z.

You may select a different date format with the @dateFormat directive:

@dateFormat(format: ISO8601_DATE_ONLY): same as the default format, but hiding the time part (e.g. 2024-11-05)
@dateFormat(format: DD_MMM_YYYY): date-only in a "long" format (e.g. 05 Nov 2024)

For exmaple:

query {
  evidence {
    searchEvidence() {
      edges {
        node {
          createdAt @dateFormat(format: DD_MMM_YYYY)
        }
      }
    }
  }
}

Username Values

Fields ending with ...By (e.g. createdBy) are used to represent the user who performed an action.

Experimental Features and Deprecation

Experimental features are marked with the @experimental directive. These are new features and may be subject to breaking changes in future releases. Pay attention to this directive, meaning you use these features at your own risk.

Deprecations are marked with the @deprecated directive. Deprecated features are still available, but will be removed in future releases. Pay attention to this directive, and change your queries according to the deprecation notice.