v3.x: OAI/OpenAPI-Specification/tree/v3.{1,2,3}-dev/tests/schema/pass

I consider the following examples from the dev branches of the different OAI versions incorrect:

operation-object-example.yaml

OpenAPI-Specification/tests/schema/pass/operation-object-example.yaml

Lines 6 to 18 in 551e3df

    
           /pets/{id}: 
        
             put: 
        
               tags: 
        
                 - pet 
        
               summary: Updates a pet in the store with form data 
        
               operationId: updatePetWithForm 
        
               parameters: 
        
                 - name: petId 
        
                   in: path 
        
                   description: ID of pet that needs to be updated 
        
                   required: true 
        
                   schema: 
        
                     type: string

petId is not a parameter of the Path

in v3.1, v3.2, v3.3

security-scheme-object-examples

OpenAPI-Specification/tests/schema/pass/security-scheme-object-examples.yaml

Lines 58 to 59 in 551e3df

    
           external: 
        
             $ref: 'https://example.com/api/openapi.json#/components/externalDocs/ThingExternalDocs'

https://example.com/api/openapi.json is an invalid ref

in v3.1, v3.2, v3.3

media-type-examples

OpenAPI-Specification/tests/schema/pass/media-type-examples.yaml

Lines 12 to 17 in 85f1be3

    
             mediaTypes: 
        
               StreamingPets: 
        
                 description: | 
        
                   Streaming sequence of JSON pet representations, 
        
                   suitable for use with any of the streaming JSON 
        
                   media types.

omponents.mediaTypes.StreamingPets.MediaType.description - MediaTypes do not have a description

in v3.2, v3.3

yes, the parameter name should be id, not petId.
the syntax of this $ref is valid, and since it refers to an external document, we do not know whether it is valid or not, so there is nothing to fix here.
description was added to the schema via commit 747ccc8, but it appears that the specification text was not also amended. We should fix the specification, as the intent to add description is valid.

Hi,

thanks for your input.

For 2 - the syntax is valid, but -to me- having an unresolvable reference violates the structural rules of the JSON Schema OAI builds upon and I'm not aware of exceptions within OAI to allow this.
Can you point me somewhere to look this up?

It's not an unresolveable reference. It's a reference to another document. When parsing this document, we can't expect that all $refs to external documents are already "known", otherwise it would be impossible to have two documents that each referenced each other. Only at runtime, when the $ref is being resolved and we want to access the data in that other document, can we determine if the $ref is invalid or not.

However, I do note another issue with this example: the $ref is pointing to ...openapi.json#/components/externalDocs/... which is not a valid destination (there is no externalDocs property under components). This should instead be pointing to .../components/securitySchemes/....

fix some tests, as noted in OAI#5575

I prepared a fix in #5580 and #5581.

The specification for the media type object has been amended in #5583 and #5584.

Would it be possible to reference a resource which allows using the security-scheme-object-examples.yaml example for runtime?

Navigation Menu

Repository navigation

v3.x: OAI/OpenAPI-Specification/tree/v3.{1,2,3}-dev/tests/schema/pass #5575

operation-object-example.yaml

security-scheme-object-examples

media-type-examples

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	/pets/{id}:
	put:
	tags:
	- pet
	summary: Updates a pet in the store with form data
	operationId: updatePetWithForm
	parameters:
	- name: petId
	in: path
	description: ID of pet that needs to be updated
	required: true
	schema:
	type: string

	external:
	$ref: 'https://example.com/api/openapi.json#/components/externalDocs/ThingExternalDocs'

	mediaTypes:
	StreamingPets:
	description: \|
	Streaming sequence of JSON pet representations,
	suitable for use with any of the streaming JSON
	media types.

v3.x: OAI/OpenAPI-Specification/tree/v3.{1,2,3}-dev/tests/schema/pass #5575

Description

operation-object-example.yaml

security-scheme-object-examples

media-type-examples

Activity

karenetheridge commented on Oct 27, 2026

commonism commented on Oct 29, 2026

karenetheridge commented on Oct 29, 2026

karenetheridge commented on Oct 29, 2026

karenetheridge commented on Oct 29, 2026

commonism commented on Oct 30, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions