Apache Polaris provides the following OpenAPI specifications:

• polaris-management-service.yml - Defines the management APIs for creating and managing principals, principal roles, catalogs and catalog roles.

• polaris-catalog-service.yaml - Defines the specification for the Apache Polaris Catalog API, which encompasses both the Apache Iceberg REST Catalog API and Apache Polaris-native APIs:

  • iceberg-rest-catalog-open-api.yaml - Contains the specification for Apache Iceberg Rest Catalog API.

  • polaris-catalog-apis - This folder contains the specifications for Apache Polaris-specific Catalog APIs:

    • generic-tables-api.yaml - Contains the specification for the Generic Tables API.

    • notifications-api.yaml - Contains the specification for the Notifications API.

    • policy-apis.yaml - Contains the specification for the Policy APIs.

    • oauth-tokens-api.yaml - Contains the specification for the internal OAuth Token endpoint, extracted from the Apache Iceberg REST Catalog API.

The specification files in the generated folder are automatically created using OpenAPI bundling tools such as Redocly CLI.

These files should not be manually edited. They are intended for preview purposes only, such as rendering a preview on a website.

Whenever the source specification files are updated, the generated files must be re-generated to reflect those changes.

Below are steps to generate bundled-polaris-catalog-service.yaml

npm install -g @redocly/cli

Without a global install, make spec-bundle falls back to npx -y @redocly/cli.

make spec-bundle

This runs redocly and then restores the license header, which redocly drops along with the rest of the leading comment block. The script behind the target is spec/bundle.sh.

The file iceberg-rest-catalog-open-api.yaml is copied from the upstream Iceberg REST catalog spec.

However, when copying it, you may need to make some nonfunctional changes to ensure that the generated Python types still allow all tests to pass. You can regenerate the Python client by running:

make client-regenerate

For more context, see PR #2192.