Schemas#

The following sections represent the schemas used in validate-pyproject. They were automatically rendered via sphinx-jsonschema for quick reference. In case of doubts or confusion, you can also have a look on the raw JSON files in JSON Schemas.

Data structure for pyproject.toml files#

File format containing build-time configurations for the Python ecosystem. PEP 517 initially defined a build-system independent format for source trees which was complemented by PEP 518 to provide a way of specifying dependencies for building Python projects. Please notice the project table (as initially defined in PEP 621) is not included in this schema and should be considered separately.

https://packaging.python.org/en/latest/specifications/declaring-build-dependencies/

type

object

properties

  • build-system

Table used to store build-related data

type

object

properties

  • requires

List of dependencies in the PEP 508 format required to execute the build system. Please notice that the resulting dependency graph MUST NOT contain cycles

type

array

items

type

string

  • build-backend

Python object that will be used to perform the build according to PEP 517

type

string

format

pep517-backend-reference

  • backend-path

List of directories to be prepended to sys.path when loading the back-end, and running its hooks

type

array

items

type

string

additionalProperties

False

  • project

https://packaging.python.org/en/latest/specifications/declaring-project-metadata/

  • tool

type

object

additionalProperties

False

Package metadata stored in the project table#

Data structure for the project table inside pyproject.toml (as initially defined in PEP 621)

https://packaging.python.org/en/latest/specifications/declaring-project-metadata/

type

object

properties

  • name

The name (primary identifier) of the project. MUST be statically defined.

type

string

format

pep508-identifier

  • version

The version of the project as supported by PEP 440.

type

string

format

pep440

  • description

The summary description of the project

type

string

  • readme

Full/detailed description of the project in the form of a README with meaning similar to the one defined in core metadata’s Description

oneOf

Relative path to a text file (UTF-8) containing the full description of the project. If the file path ends in case-insensitive .md or .rst suffixes, then the content-type is respectively text/markdown or text/x-rst

type

string

type

object

allOf

anyOf

properties

  • file

Relative path to a text file containing the full description of the project.

type

string

properties

  • text

Full text describing the project.

type

string

properties

  • content-type

Content-type (RFC 1341) of the full description (e.g. text/markdown). The charset parameter is assumed UTF-8 when not present.

type

string

  • requires-python

The Python version requirements of the project.

type

string

format

pep508-versionspec

  • license

Project license.

oneOf

properties

  • file

Relative path to the file (UTF-8) which contains the license for the project.

type

string

properties

  • text

The license of the project whose meaning is that of the License field from the core metadata.

type

string

  • authors

The people or organizations considered to be the ‘authors’ of the project. The exact meaning is open to interpretation (e.g. original or primary authors, current maintainers, or owners of the package).

type

array

items

Author or Maintainer

  • maintainers

The people or organizations considered to be the ‘maintainers’ of the project. Similarly to authors, the exact meaning is open to interpretation.

type

array

items

Author or Maintainer

  • keywords

List of keywords to assist searching for the distribution in a larger catalog.

type

array

items

type

string

  • classifiers

Trove classifiers which apply to the project.

type

array

items

PyPI classifier.

type

string

format

trove-classifier

  • urls

URLs associated with the project in the form label => value.

type

object

patternProperties

  • ^.+$

type

string

format

url

additionalProperties

False

  • scripts

Instruct the installer to create command-line wrappers for the given entry points.

Entry-points

  • gui-scripts

Instruct the installer to create GUI wrappers for the given entry points. The difference between scripts and gui-scripts is only relevant in Windows.

Entry-points

  • entry-points

Instruct the installer to expose the given modules/functions via entry-point discovery mechanism (useful for plugins). More information available in the Python packaging guide.

patternProperties

  • ^.+$

Entry-points

additionalProperties

False

  • dependencies

Project (mandatory) dependencies.

type

array

items

Dependency

  • optional-dependencies

Optional dependency for the project

type

object

patternProperties

  • ^.+$

type

array

items

Dependency

additionalProperties

False

  • dynamic

Specifies which fields are intentionally unspecified and expected to be dynamically provided by build tools

type

array

items

enum

version, description, readme, requires-python, license, authors, maintainers, keywords, classifiers, urls, scripts, gui-scripts, entry-points, dependencies, optional-dependencies

additionalProperties

False

if

not

properties

  • dynamic

version is listed in dynamic

then

version should be statically defined in the version field

Author or Maintainer#

#/definitions/author

type

object

properties

  • name

MUST be a valid email name, i.e. whatever can be put as a name, before an email, in RFC 822.

type

string

  • email

MUST be a valid email address

type

string

format

idn-email

Entry-points#

Entry-points are grouped together to indicate what sort of capabilities they provide. See the packaging guides and setuptools docs for more information.

#/definitions/entry-point-group

type

object

patternProperties

  • ^.+$

Reference to a Python object. It is either in the form importable.module, or importable.module:object.attr.

type

string

format

python-entrypoint-reference

additionalProperties

False

Dependency#

Project dependency specification according to PEP 508

#/definitions/dependency

type

string

format

pep508

tool table#

According to PEP 518, tools can define their own configuration inside pyproject.toml by using custom subtables under tool.

In validate-pyproject, schemas for these subtables can be specified via Plugins. The following subtables are defined by built-in plugins (i.e. plugins that are included in the default distribution of validate-pyproject):

tool.setuptools table#

Please notice for the time being the setuptools project does not specify a way of configuring builds via pyproject.toml. Therefore this schema should be taken just as a “thought experiment” on how this might be done, by following the principles established in ini2toml. It considers only setuptools parameters that can currently be configured via setup.cfg and are not covered by PEP 621 but intentionally excludes dependency_links and setup_requires. NOTE: scripts was renamed to script-files to avoid confusion with entry-point based scripts (defined in PEP 621).

https://setuptools.pypa.io/en/latest/references/keywords.html

type

object

properties

  • platforms

type

array

items

type

string

  • provides

Package and virtual package names contained within this package (not supported by pip)

type

array

items

type

string

format

pep508-identifier

  • obsoletes

Packages which this package renders obsolete (not supported by pip)

type

array

items

type

string

format

pep508-identifier

  • zip-safe

Whether the project can be safely installed and run from a zip file.

type

boolean

  • script-files

Legacy way of defining scripts (entry-points are preferred).

type

array

items

type

string

  • eager-resources

Resources that should be extracted together, if any of them is needed, or if any C extensions included in the project are imported.

type

array

items

type

string

  • packages

Packages that should be included in the distribution. It can be given either as a list of package identifiers or as a dict-like structure with a single key find which corresponds to a dynamic call to setuptools.config.expand.find_packages function. The find key is associated with a nested dict-like structure that can contain where, include, exclude and namespaces keys, mimicking the keyword arguments of the associated function.

oneOf

Array of Python package identifiers

type

array

items

type

string

format

python-module-name

‘find:’ directive

  • package-dir

dict-like structure mapping from package names to directories where their code can be found. The empty string (as key) means that all packages are contained inside the given directory will be included in the distribution.

type

object

patternProperties

  • ^.*$

type

string

additionalProperties

False

  • package-data

Mapping from package names to lists of glob patterns. Usually this option is not needed when using include-package-data = true For more information on how to include data files, check setuptools docs.

type

object

patternProperties

  • ^.*$

type

array

items

type

string

additionalProperties

False

  • include-package-data

Automatically include any data files inside the package directories that are specified by MANIFEST.in For more information on how to include data files, check setuptools docs.

type

boolean

  • exclude-package-data

Mapping from package names to lists of glob patterns that should be excluded For more information on how to include data files, check setuptools docs.

type

object

patternProperties

  • ^.*$

type

array

items

type

string

additionalProperties

False

  • namespace-packages

type

array

items

type

string

format

python-module-name

  • py-modules

Modules that setuptools will manipulate

type

array

items

type

string

format

python-module-name

  • data-files

DEPRECATED: dict-like structure where each key represents a directory and the value is a list of glob patterns that should be installed in them. Please notice this don’t work with wheels. See data files support

type

object

patternProperties

  • ^.*$

type

array

items

type

string

  • cmdclass

Mapping of distutils-style command names to setuptools.Command subclasses which in turn should be represented by strings with a qualified class name (i.e., “dotted” form with module), e.g.:

cmdclass = {mycmd = "pkg.subpkg.module.CommandClass"}

The command class should be a directly defined at the top-level of the containing module (no class nesting).

type

object

patternProperties

  • ^.*$

type

string

format

python-qualified-identifier

  • license-files

PROVISIONAL: List of glob patterns for all license files being distributed. (might become standard with PEP 639).

type

array

default

LICEN[CS]E*

COPYING*

NOTICE*

AUTHORS*

items

type

string

  • dynamic

Instructions for loading PEP 621-related metadata dynamically

type

object

properties

  • version

A version dynamically loaded via either the attr: or file: directives. Please make sure the given file or attribute respects PEP 440.

oneOf

‘attr:’ directive

‘file:’ directive

  • classifiers

‘file:’ directive

  • description

‘file:’ directive

  • dependencies

‘file:’ directive

  • entry-points

‘file:’ directive

  • optional-dependencies

type

object

patternProperties

  • .+

‘file:’ directive

additionalProperties

False

  • readme

anyOf

‘file:’ directive

properties

  • content-type

type

string

additionalProperties

False

additionalProperties

False

‘file:’ directive#

Value is read from a file (or list of files and then concatenated)

#/definitions/file-directive

type

object

properties

  • file

oneOf

type

string

type

array

items

type

string

additionalProperties

False

‘attr:’ directive#

Value is read from a module attribute. Supports callables and iterables; unsupported types are cast via str()

#/definitions/attr-directive

type

object

properties

  • attr

type

string

additionalProperties

False

‘find:’ directive#

#/definitions/find-directive

type

object

properties

  • find

Dynamic package discovery.

type

object

properties

  • where

Directories to be searched for packages (Unix-style relative path)

type

array

items

type

string

  • exclude

Exclude packages that match the values listed in this field. Can container shell-style wildcards (e.g. 'pkg.*')

type

array

items

type

string

  • include

Restrict the found packages to just the ones listed in this field. Can container shell-style wildcards (e.g. 'pkg.*')

type

array

items

type

string

  • namespaces

When True, directories without a __init__.py file will also be scanned for PEP 420-style implicit namespaces

type

boolean

additionalProperties

False

additionalProperties

False