python-peps/peps/pep-0739/python-build-info-v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.schema.json",
  "type": "object",
  "title": "Static description file for the build details of Python installations",
  "required": [
    "schema_version",
    "platform",
    "language",
    "implementation"
  ],
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string",
      "description": "Schema version.\n\nThis is a constant value and MUST be ``1``, when using the schema described here. Future iterations of this schema MUST update this value.",
      "const": "1"
    },
    "base_prefix": {
      "type": "string",
      "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a relative path to directory where this file is contained.",
      "examples": [
        "/usr",
        "../.."
      ]
    },
    "platform": {
      "type": "string",
      "description": "System platform string.\n\nThis field SHOULD be equivalent to ``sysconfig.get_platform()``.",
      "examples": [
        "linux-x86_64"
      ]
    },
    "language": {
      "type": "object",
      "description": "Object containing details related to the Python language specification.\n\nIn addition to the required keys, implementations may choose to include extra keys with implementation-specific details.",
      "required": [
        "version"
      ],
      "additionalProperties": false,
      "properties": {
        "version": {
          "type": "string",
          "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field SHOULD be equivalent to ``sysconfig.get_python_version()``.",
          "examples": ["3.14"]
        }
      }
    },
    "implementation": {
      "type": "object",
      "description": "Object containing details related to Python implementation.\n\nThis section SHOULD be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.",
      "required": [
        "name",
        "version",
        "hexversion",
        "cache_tag"
      ],
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string",
          "description": "Lower-case name of the Python implementation.",
          "examples": ["cpython", "pypy"]
        },
        "version": {
          "type": "object",
          "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
          "required": ["major", "minor", "micro", "releaselevel", "serial"],
          "additionalProperties": false,
          "examples": [
            {
              "major": 3,
              "minor": 13,
              "micro": 1,
              "releaselevel": "final",
              "serial": 0
            },
            {
              "major": 7,
              "minor": 3,
              "micro": 16,
              "releaselevel": "final",
              "serial": 0
            }
          ],
          "properties": {
            "major": {
              "type": "number"
            },
            "minor": {
              "type": "number"
            },
            "micro": {
              "type": "number"
            },
            "releaselevel": {
              "type": "string",
              "enum": ["alpha", "beta", "candidate", "final"]
            },
            "serial": {
              "type": "number"
            }
          }
        }
      }
    },
    "interpreter": {
      "type": "object",
      "description": "Object containing details Python interpreter.\n\nThis section MUST be present if the Python installation provides an interpreter binary, otherwise this section will be missing.",
      "required": [
        "path"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "description": "The path to the Python interprer. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
          "examples": [
            "/usr/bin/python",
            "bin/python"
          ]
        }
      }
    },
    "abi": {
      "type": "object",
      "description": "Object containing details related to ABI.",
      "required": [
        "flags",
        "extension_suffix"
      ],
      "additionalProperties": false,
      "properties": {
        "flags": {
          "type": "array",
          "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags MUST be defined in the order they appear on the extension suffix.",
          "additionalProperties": true,
          "examples": [
            ["t", "d"]
          ]
        },
        "extension_suffix": {
          "type": "string",
          "description": "Suffix used for extensions built against the current implementation version.\n\nThis field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing.",
          "examples": [
            ".cpython-314-x86_64-linux-gnu.so"
          ]
        },
        "stable_abi_suffix": {
          "type": "string",
          "description": "Suffix used for extensions built against the stable ABI.\n\nThis field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.",
          "examples": [
            ".abi3.so"
          ]
        }
      }
    },
    "suffixes": {
      "type": "object",
      "description": "Valid module suffixes grouped by type.\n\nThis section SHOULD be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes, if the implementation provides such suffixes. However, if the Python implementation does not provide suffixes of the kind specified by any of the attributes, the equivalent sub-section is not required to be present. Additionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they MAY add a sub-section for them.",
      "examples": [
        {
          "source": [".py"],
          "bytecode": [".pyc"],
          "optimized_bytecode": [".pyc"],
          "debug_bytecode": [".pyc"],
          "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
        }
      ]
    },
    "libpython": {
      "type": "object",
      "description": "Object containing details related to the ``libpython`` library.\n\nThis section MUST by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.",
      "additionalProperties": false,
      "properties": {
        "dynamic": {
          "type": "string",
          "description": "The path to the dynamic ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
          "examples": [
            "/usr/lib/libpython3.14.so.1.0",
            "lib/libpython3.14.so.1.0"
          ]
        },
        "static": {
          "type": "string",
          "description": "The path to the static ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
          "examples": [
            "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
            "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
          ]
        },
        "link_to_libpython": {
          "type": "boolean",
          "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing."
        }
      }
    },
    "c_api": {
      "type": "object",
      "description": "Object containing details related to the Python C API, if available.\n\nThis section MUST be present if the Python implementation provides a C API, otherwise this section will be missing.",
      "required": [
        "headers"
      ],
      "additionalProperties": false,
      "properties": {
        "headers": {
          "type": "string",
          "description": "The path to the C API headers. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
          "examples": [
            "/usr/include/python3.14",
            "include/python3.14"
          ]
        },
        "pkgconfig_path": {
          "type": "string",
          "description": "The path to the pkg-config definition files. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python implementation provides pkg-config definition files for the C API, otherwise this section will be missing.",
          "examples": [
            "/usr/lib/pkgconfig",
            "lib/pkgconfig"
          ]
        }
      }
    },
    "arbitrary_data": {
      "type": "object",
      "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implamentations may choose what data to provide in this section.",
      "additionalProperties": true
    }
  }
}