Schemas

This document shows the schemas for Pulp data understood by this library, in JSON schema format.

These schemas may be useful when providing data to the from_data() methods, or as a general reference.

Repository

title: pulp2-repository

description: >-
  Schema for a Pulp 2.x repository dict, as returned by the
  /pulp/api/v2/repositories/<repo_id>/ API.

$schema: http://json-schema.org/draft-07/schema#

definitions:
  # A repository distributor (yum_distributor, iso_distributor...)
  distributor:
    type: object
    properties:
      id:
        # String ID of distributor, e.g. "yum_distributor"
        type: string
      distributor_type_id:
        # String ID of distributor's type, e.g. "yum_distributor"
        type: string
      repo_id:
        # String ID of distributor's repository
        type: string
      config:
        # Config dict for this distributor, different per distributor type.
        # We won't mandate which config keys are used with each distributor,
        # but if they're present, we'll validate them
        type: object
        properties:
          # Publish path for this URL, relative to Pulp/CDN root
          relative_url:
            type: string
          # True if rsync of repodata should be skipped
          skip_repodata:
            type: boolean

      # An ISO8601 timestamp for the last time this distributor was published.
      last_publish:
        anyOf:
        - type: "null"
        - type: string
          # example: 2019-06-05T11:56:50Z
          pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z"

    required:
    - id
    - distributor_type_id

type: object

properties:

  # ID of the repo, e.g. "my-repo", "zoo".
  # Note this is different from _id, which is the mongo document ID.
  id:
    type: string

  # Repository notes.
  # This is a dict where any keys/values may be stored.
  notes:
    type: object

    properties:

      # Identifier for repository type, e.g. "iso-repo", "rpm-repo"
      _repo-type:
        type: string

      # An ISO8601 timestamp for creation of this repo.
      # Note that this field is not set by Pulp itself.  Only certain tools
      # are expected to initialize this field when creating a repo.
      created:
        anyOf:
        - type: "null"
        - type: string
        # example: 2019-06-05T11:56:50Z
        pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z"

      # Comma-separated GPG public key IDs, used for signing content in
      # this repository.
      signatures:
        type: string

      # True if this is considered a temporary repository, created for
      # use during certain workflows and deleted later
      pub_temp_repo:
        type: boolean

      # True if repository supposed to be populated from repositories
      # mentioned in population_sources
      ubi_population:
        type: boolean

      # List of repositories used for populating the repository
      population_sources:
        type: array
        items:
          type: string

      # Name of content set that is associated with this repository
      content_set:
        anyOf:
        - type: "null"
        - type: string

      # Version of ubi config that should be used for population of this repository
      ubi_config_version:
        anyOf:
        - type: "null"
        - type: string

      # Flag indicating whether the repository is visible in production instance
      # of download service. Stored as string.
      include_in_download_service:
        enum:
          - "True"
          - "False"

      # Flag indicating whether the repository is visible in staging instance
      # of download service. Stored as string.
      include_in_download_service_preview:
        enum:
          - "True"
          - "False"

  # List of repository distributors.
  # Note that order matters in this list.
  distributors:
    type: array
    items:
      $ref: "#/definitions/distributor"

required:
- id

Task

title: pulp2-task

description: >-
  Schema for a Pulp 2.x task dict, as returned by the
  /pulp/api/v2/tasks/<task_id>/ API.

$schema: http://json-schema.org/draft-07/schema#

definitions:
  # An error object
  # https://docs.pulpproject.org/dev-guide/conventions/exceptions.html#error-details
  error:
    type: object
    properties:

      # Short identifier of error, e.g. PLP0018
      code:
        type: string

      # Summary of error for end-user
      description:
        type: string

      # Arbitrary key-value data, different per error code
      data:
        type: object

    required:
    - code
    - description

type: object

properties:

  # ID of the task, e.g. "7744e2df-39b9-46f0-bb10-feffa2f7014b"
  task_id:
    type: string

  # Task state
  state:
    enum:
    - accepted  # this value has never been observed
    - running   # task is being worked on
    - waiting   # task is waiting for a worker to pick it up
    - finished  # task completed successfully
    - error     # task completed unsuccessfully
    - canceled  # task was canceled
    - skipped   # Pulp decided not to execute this task

  # The error - only non-null for failed tasks
  error:
    anyOf:
    - type: "null"
    - $ref: "#/definitions/error"

  # Python traceback if an exception was raised - a single multi-line string
  traceback:
    anyOf:
    - type: "null"
    - type: string

  # Tags of a task; a list of arbitrary strings
  tags:
    type: array
    items:
      type: string

  # Task result. The content depends on the task type.
  result:
    anyOf:

    # If it's not an object, we don't care what it is, just accept it.
    - not:
        type: object

    # If it is an object, we will validate some inner fields.
    - type: object
      properties:
        # For tasks operating on units (e.g. assoc/unassoc), this element
        # in the result will record which unit(s) were affected.
        units_successful:
          type: array
          items:
            type: object
            properties:
              type_id:
                type: string
              unit_key:
                type: object
            required:
            - type_id
            - unit_key

required:
- task_id
- state

Unit

title: pulp2-unit

description: >-
  Schema for a Pulp 2.x unit, as returned by content search API.

$schema: http://json-schema.org/draft-07/schema#

definitions:
  # ISO units (generic file)
  iso:
    type: object

    properties:
      # Type of the unit, e.g. "iso", "rpm", "srpm", "erratum" ...
      _content_type_id:
        const: iso

      # Filename (actually path)
      name:
        type: string

      # SHA256 checksum
      checksum:
        type: string
        pattern: "^[a-f0-9]{64}$"

      # Size in bytes
      size:
        # Ideally would be 'integer', but some old units have been stored
        # as non-integers, e.g.
        # RHEL4-U5-ia64-source-disc2.iso => 512251904.0
        type: number

      repository_memberships:
        type: array
        items:
          type: string

    required:
    - _content_type_id
    - name
    - checksum
    - size

  # RPM units
  rpm:
    type: object

    properties:
      # Type of the unit
      _content_type_id:
        enum:
        - rpm
        - srpm

      # ENVR components
      name:
        type: string
      epoch:
        type: string
      version:
        type: string
      release:
        type: string

      # Architecture
      arch:
        type: string

      # Filename of the rpm
      filename:
        anyOf:
        - type: string
        - type: "null"

      # source rpm filename
      sourcerpm:
        anyOf:
        - type: string
        - type: "null"

      # Short ID of key used to sign this RPM
      signing_key:
        anyOf:
        - type: string
        - type: "null"

      # Checksums in key/value pairs (key=algorithm, value=hex string).
      # All checksums are optional.
      checksums:
        type: object
        properties:
          md5:
            type: string
            pattern: "^[a-f0-9]{32}$"
          sha1:
            type: string
            pattern: "^[a-f0-9]{40}$"
          sha256:
            type: string
            pattern: "^[a-f0-9]{64}$"

      # SHA256 checksum.
      # This duplicates checksums.sha256 above; the difference is that this field
      # is a part of the unit key, so it's both mandatory & indexed.
      # Also, though the original intent was probably to support multiple checksum
      # types in this field, it is nowadays forced to sha256, see:
      # https://github.com/pulp/pulp_rpm/blob/69759d0fb9a16c0a47b1f49c78f6712e650912e1/plugins/pulp_rpm/plugins/importers/yum/upload.py#L436
      checksum:
        type: string
        pattern: "^[a-f0-9]{64}$"

      repository_memberships:
        type: array
        items:
          type: string

      requires:
        type: array
        items:
          type: object

      provides:
        type: array
        items:
          type: object


    required:
    - _content_type_id
    - name
    - version
    - release
    - arch

  # modulemd units
  modulemd:
    type: object

    properties:
      # Type of the unit
      _content_type_id:
        const: modulemd

      # NSVCA components
      name:
        type: string
      stream:
        type: string
      version:
        type: integer
      context:
        type: string
      arch:
        type: string

      repository_memberships:
        type: array
        items:
          type: string

      artifacts:
        type: array
        items:
          type: string

      profiles:
        type: object

      dependencies:
        type: array
        items:
          type: object

    required:
    - _content_type_id
    - name
    - stream
    - version
    - context
    - arch


  # modulemd_defaults units
  modulemd_defaults:
    type: object

    properties:
      # Type of the unit
      _content_type_id:
        const: modulemd_defaults

      name:
        type: string
      repo_id:
        type: string
      stream:
        type: string
      profiles:
        type: object

      repository_memberships:
        type: array
        items:
          type: string

    required:
    - _content_type_id
    - name
    - repo_id

  # Schema for any unknown type of unit
  unknown:
    type: object

    properties:
      # Type of the unit. Since this is the catch-all schema for unknown unit types,
      # this must be a type not included in one of the other schemas.
      _content_type_id:
        allOf:
        - type: string
        - not:
            enum:
            - iso
            - rpm
            - srpm
            - modulemd
            - modulemd_defaults

    required:
    - _content_type_id

anyOf:
- $ref: "#/definitions/iso"
- $ref: "#/definitions/rpm"
- $ref: "#/definitions/modulemd"
- $ref: "#/definitions/modulemd_defaults"
- $ref: "#/definitions/unknown"

Maintenance

title: maintenance report

description: >-
  Schema for the maintenance report JSON file.
  This is a custom file used on release-engineering Pulp servers to flag repositories
  as being in "maintenance mode", meaning that external publishes are not allowed.

$schema: http://json-schema.org/draft-07/schema#

definitions:
  # details of maintenance
  details:
    type: object
    properties:
      # Why this repo is in maintenance mode
      message:
        type: string
      # Who set it to maintenance
      owner:
        type: string
      # An ISO8601 timestamp for when did the maintenance start for this repo
      started:
        type: string
        pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z"

type: object

properties:
  # An ISO8601 timestamp for when this report was updated last time
  last_updated:
    type: string
    pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z"

  # The person who updated maintenance repo last time
  last_updated_by:
    type: string

  # repo_id: details pairs, indicate which repo is in maintenance mode
  # with details.
  repos:
    type: object
    patternProperties:
      ".*":
        $ref: "#/definitions/details"