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/pyproject-toml/
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/pyproject-toml/
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
additionalProperties	False

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

setuptools-specific configurations that can be set by users that require customization. These configurations are completely optional and probably can be skipped when creating simple packages. They are equivalent to some of the Keywords used by the setup.py file, and can be set via the tool.setuptools table. It considers only setuptools parameters that are not covered by PEP 621; and intentionally excludes dependency_links and setup_requires (incompatible with modern workflows/standards).

https://setuptools.pypa.io/en/latest/userguide/pyproject_config.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. OBSOLETE: only relevant for pkg_resources, easy_install and setup.py install in the context of eggs (DEPRECATED).
	type	boolean
script-files	Legacy way of defining scripts (entry-points are preferred). Equivalent to the script keyword in setup.py (it was renamed to avoid confusion with entry-point based project.scripts defined in PEP 621). DISCOURAGED: generic script wrappers are tricky and may not work properly. Whenever possible, please use project.scripts instead.
	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. OBSOLETE: only relevant for pkg_resources, easy_install and setup.py install in the context of eggs (DEPRECATED).
	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	Valid package 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	DEPRECATED: use implicit namespaces instead (PEP 420).
	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	dict-like structure where each key represents a directory and the value is a list of glob patterns that should be installed in them. DISCOURAGED: please notice this might not work as expected with wheels. Whenever possible, consider using data files inside the package directories (or create a new namespace package that only contains data files). 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. (likely to become standard with PEP 639). By default: ['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']
	type	array
	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. Also ensure to set project.dynamic accordingly.
		oneOf	‘attr:’ directive
			‘file:’ directive
	classifiers	‘file:’ directive
	description	‘file:’ directive
	entry-points	‘file:’ directive
	dependencies	‘file:’ directive for dependencies
	optional-dependencies	type	object
		patternProperties
		.+	‘file:’ directive for dependencies
		additionalProperties	False
	readme	type	object
		anyOf	‘file:’ directive
			type	object
			properties
			content-type	type	string
			file	#/definitions/file-directive/properties/file
			additionalProperties	False
	additionalProperties	False
additionalProperties	False

Valid package name

Valid package name (importable or PEP 561).

#/definitions/package-name
type	string
anyOf	type	string
	format	python-module-name
	type	string
	format	pep561-stub-name

‘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

‘file:’ directive for dependencies

allOf	BETA: subset of the requirements.txt format without pip flags and options (one PEP 508-compliant string per line, lines that are blank or start with # are excluded). See dynamic metadata.
	‘file:’ directive

‘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
	format	python-qualified-identifier
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