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?

What is the end goal here? The test suite is validating document syntax, not deeper things like whether the document actually makes sense for a real-world application.

I want to use them for unit testing in aiopenapi3.
Currently the pass tests are xfail due to the defects I reported in this issue.

Merge pull request #5580 from karenetheridge/ether/v3.3-fix-test-exam…

fix some tests, as noted in #5575

Merge pull request #5581 from karenetheridge/ether/v3.2-fix-test-exam…

URIs that reference local locations can be validated at load time (for example $ref: '#/components/schemas/IDoNotExist' is unambiguously invalid and can never become valid after loading additional documents), but anything targeting an external resource cannot be known to be invalid when the document is loaded. This test suite is designed to be run where each document is treated individually, so any additional reference testing would not be appropriate to run here.

I agree and this is perfectly valid within the theory of JSON Schema.

In practice, you need all description documents at hand when generating openapi clients.
Therefore the example is currently not usable and I'm asking for it to be changed to allow using it as input data for client generation.

fix some tests, as noted in #5575

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

karenetheridge commented on Oct 30, 2026

commonism commented on Nov 1, 2026

karenetheridge commented on Nov 3, 2026

commonism commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions