## A pykwalify schema for basic validation of the structure of a
## manifest YAML file.  (Full validation would require additional work,
## e.g. to validate that remote URLs obey the URL format specified in
## rfc1738.)
##
## This schema has similar semantics to the repo XML format:
##
## https://gerrit.googlesource.com/git-repo/+/master/docs/manifest-format.txt
##
## However, the features don't map 1:1.

# The top-level manifest is a map. There may be multiple sections in the
# manifest file. Each section can be validated by their own schema.
# This schema validates the 'manifest' section.
type: map
mapping:
  # The "defaults" key specifies some default values used in the
  # rest of the manifest.
  #
  # The value is a map with the following keys:
  #
  # - remote: if given, this is the default remote in each project
  # - revision: if given, this is the default revision to check
  #   out of each project
  #
  # See below for more information about remotes and projects.
  #
  # Examples:
  #
  # default:
  #   remote: zephyrproject-rtos
  #   revision: master
  defaults:
    required: false
    type: map
    mapping:
      remote:
        required: false
        type: str
      revision:
        required: false
        type: str

  # The "remotes" key specifies a sequence of remotes, each of
  # which has a name and a fetch URL.
  #
  # These work like repo remotes, in that they specify a URL
  # prefix which remote-specific Git repositories hang off of.
  # (This saves typing and makes it easier to move things around
  # when most repositories are on the same server or GitHub
  # organization.)
  #
  # Example:
  #
  #   remotes:
  #     - name: zephyrproject-rtos
  #       url-base: https://github.com/zephyrproject-rtos
  #     - name: developer-fork
  #       url-base: https://github.com/a-developer
  remotes:
    required: true
    type: seq
    sequence:
      - type: map
        mapping:
          name:
            required: true
            type: str
          url-base:
            required: true
            type: str

  # The "projects" key specifies a sequence of "projects",
  # i.e. Git repositories. These work like repo projects, in that
  # each project has a name, a remote, and optional additional
  # metadata.
  #
  # Each project is a map with the following keys:
  #
  # - name: Mandatory, the name of the git repository. The clone
  #   URL is formed by remote url-base + '/' + name. The name cannot
  #   be one of the reserved values "west" and "manifest".
  # - remote: Optional, the name of the remote to pull it from.
  #   If the remote is missing, the remote'key in the top-level
  #   defaults key is used instead. If both are missing, it's an error.
  # - revision: Optional, the name of the revision to check out.
  #   If not given, the value from the default element will be used.
  #   If both are missing, then the default is 'master'.
  # - path: Where to clone the repository locally. If missing,
  #   it's cloned at top level in a directory given by its name.
  # - clone-depth: if given, it is a number which creates a shallow
  #   history in the cloned repository limited to the given number
  #   of commits.
  #
  # Example, using default and non-default remotes:
  #
  #   projects:
  #     # Uses default remote (zephyrproject-rtos), so clone URL is:
  #     #   https://github.com/zephyrproject-rtos/zephyr
  #     - name: zephyr
  #     # Manually specified remote; clone URL is:
  #     #   https://github.com/a-developer/west
  #     - name: west
  #       remote: developer-fork
  #     # Manually specified remote, clone URL is:
  #     #   https://github.com/zephyrproject-rtos/some-vendor-hal
  #     # Local clone path (relative to installation root) is:
  #     #   ext/hal/some-vendor
  #     - name: some-vendor-hal
  #       remote: zephyrproject-rtos
  #       path: ext/hal/some-vendor
  projects:
    required: true
    type: seq
    sequence:
      - type: map
        mapping:
          name:
            required: true
            type: str
          remote:
            required: false
            type: str
          revision:
            required: false
            type: text        # SHAs could be only numbers
          path:
            required: false
            type: str
          clone-depth:
            required: false
            type: int