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?

Only applies when you generate a specification from a collection.

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. The system doesn’t generate or synchronize examples from collections to specifications.

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

Only applies when you sync changes from a collection to a specification.

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 applies when you generate a specification from a collection.

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

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?

Only applies when you sync changes from a collection to a specification.

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?

Only applies when you sync changes from a collection to 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.

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

The system only generates and syncs 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.

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?

Only applies when you sync changes from a specification to a collection.

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?

Only applies when you sync changes from a specification to a collection.

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.