Sync collections and specifications reference

The following are frequently asked questions about Postman’s Spec Hub feature. Use these questions to learn about different behavior when generating and syncing between collections and specifications in Spec Hub.

Sync from a collection to specification

This section includes behavior when generating an API specification from a collection, or syncing changes from a collection to a specification. Learn more about generating a specification from a collection and keeping them in sync.

What happens when multiple methods in the same path of a collection share the same path parameters?

The parameters are consolidated into path-level parameters. If any updates, like changes to descriptions or data type schemas, are made to the shared parameters in the collection, users must ensure these updates are applied consistently across all methods under that path.

If inconsistencies are detected in the path parameters across methods, the system defaults to using the last defined instance of the path parameter within that path.

What if multiple requests in a collection share the same method and path but have different query parameters?

Query parameters from the first request in the collection are prioritized and added as operation-level parameters in the specification.

What if examples or example fields exist in a specification but not a collection?

Examples or example values explicitly defined in the specification remain unchanged and preserved, even when related schemas or components are updated. By default, the system doesn’t generate or sync values from collections to specifications.

How are examples handled in OpenAPI 2.0 responses?

OpenAPI 2.0 responses support only a single examples object. When generating a collection from a specification, Postman uses the first example available. During synchronization, any updates to the response body in the collection are applied to the first example in the specification.

What if a request exists in a specification but not a collection?

The request is preserved in the specification to prevent accidental or unintentional data loss.

What if requests in the collection have automatically added headers, such as Accept or Content-Type?

Only user-defined headers are included in the specification. This helps ensure that the generated specifications are clear and accurate.

What if requests or responses in a collection have non-JSON bodies?

The system only generates and synchronizes request bodies in JSON format (application/json content type). If a path in the collection has a request body in a format other than JSON (such as text/plain or application/xml content types), the request body isn’t included in the specification. All non-JSON request bodies are preserved in the collection.

Can collection requests have body payloads with non-JSON formats?

Postman doesn’t support non-JSON body types, like form-data or multipart. These request bodies are excluded from the specification.

What if a specification has references to reusable components?

When you generate a collection from a specification with reusable components, the entire reference object is copied to requests in the generated collection. If you make changes to the requests and then sync the changes back to the specification, references are converted into inline components in the specification. This ensures that any detected updates are accurately reflected in the output.

What happens if users make changes in a collection and specification at the same time?

Changes in a collection may overwrite the changes in a specification. All changes to the specification are lost in this scenario. It’s recommended that you don’t apply changes to the specification and collection at the same time to prevent data loss.

The following exceptions apply:

• Changes to vendor extensions won’t be overwritten.
• Changes to endpoints and operations won’t be overwritten.

Are vendor extensions retained in a specification?

All x- vendor extensions are preserved in the specification. Vendor extensions aren’t removed or modified, ensuring that any organization-specific metadata remains complete.

How does Postman handle multiple hosts when syncing a collection to an OpenAPI 2.0 specification?

OpenAPI 2.0 only supports a single host value. When generating or syncing a specification from a collection, Postman uses the first host encountered in the collection’s requests and applies it to the specification.

How are consumes and produces handled in OpenAPI 2.0?

When syncing to an OpenAPI 2.0 specification, Postman adds the consumes (request content type) and produces (response content type) fields at the operation (method) level for each endpoint.

Is the basePath generated when creating an OpenAPI 2.0 specification from a collection?

No, Postman doesn’t generate the basePath when creating an OpenAPI 2.0 specification from a collection. However, if a basePath already exists in the specification, it’s retained during synchronization.

How does Postman handle webhooks in OpenAPI 3.1?

In OpenAPI 3.1, Postman automatically generates webhooks object from collection requests inside a Webhooks folder. These webhooks are included by default, and synchronized during a two-way sync.

What JSON schema version does Postman use when generating an OpenAPI 3.1 specification?

Postman uses the default JSON schema 2020-12 dialect when generating an OpenAPI 3.1 specification from a collection.

Sync from a specification to collection

This section includes behavior when generating a collection from an API specification, or syncing changes from a specification to a collection. Learn more about generating a collection from a specification and keeping them in sync.

What if a parameter is missing a description at the operation level in a specification?

The parameter in the collection inherits the description from the common path-level parameter in the specification.

What if a request exists in a collection but not a specification?

The request is preserved in the collection to prevent accidental or unintentional data loss.

What happens if users make changes in a specification and collection at the same time?

Changes in a specification may overwrite the changes in a collection. All changes to the collection are lost in this scenario. It’s recommended that you don’t apply changes to the specification and collection at the same time to prevent data loss.

The following exceptions apply:

• Changes to vendor extensions won’t be overwritten.
• Changes to endpoints and operations won’t be overwritten.

Will changing the name of a specification also change the name of its generated collection?

No. Updating the name of a specification and syncing it to its generated collection won’t update the name of the generated collection. The name of a collection is generated only at the time of creating it and remains unchanged thereafter to prevent introducing a breaking change to the mapping.

Are custom or unsupported JSON schema keywords preserved during sync for OpenAPI 3.1?

Yes. During a two-way sync, Postman preserves any JSON schema keywords present in the OpenAPI 3.1 specification, even if they’re not supported by collection types. These properties are restored when syncing back, ensuring no schema data is lost.

How does Postman handle the type keyword when it’s defined as an array in OpenAPI 3.1?

OpenAPI 3.1 lets you define the type keyword as an array, but Postman Collections only support a single type value. During two-way sync, Postman preserves the original type array from the specification and restores it when syncing changes back, ensuring that no type information is lost.