seriousme / openapi-schema-validator

If i have a file file structure like:

api.v0.yaml
v0/auth.v0.yaml

I want to validate api.v0.yaml that references v0/auth.v0.yaml.

  /v0/auth/register:
    post:
      $ref: v0/auth.v0.yaml#/paths/~1v0~1auth~1register/post
      tags:
        - Auth
      summary: Register a new account

I get must NOT have unevaluated properties, which I understand is expected behaviour from the README, I can't figure out how to use <instance>.addSpecRef(subSpecification, uri) to get this working.

Thanks

Hi,

thanks for asking.
The $ref does not refer to a file, but contains a schema reference ;-)

So if you change the reference to http://example.com/subspec#/paths/~1v0~1auth~1register/post and then use:

const validator = new Validator();
await validator.addSpecRef('./v0/auth.v0.yaml', 'http://www.example.com/subspec');
const res = await validator.validate("./api.v0.yaml");

Then it should work.

Hope this helps !

Kind regards,
Hans

Thanks for spotting a bug in the README, the arguments to await validator.addSpecRef should indeed be switched.
See:

openapi-schema-validator/test/test-validation.js

Lines 214 to 219 in aca3046

    
           test(`addSpecRef works`, async (t) => { 
        
             t.plan(5); 
        
             const validator = new Validator(); 
        
             await validator.addSpecRef(subSpecYamlFileName, subSpecUri); 
        
             await validator.addSpecRef(subSpec2YamlFileName); 
        
             const res = await validator.validate(mainSpecYamlFileName);

Sorry for any confusion caused.

Kind regards,
Hans

FYI: Just published https://github.com/seriousme/openapi-schema-validator/releases/tag/v1.6.1 with an updated README.md

Thanks, for whatever reason I still can't get it working. I can add the reference without an error but still get message: 'must NOT have unevaluated properties'

If I get some time later tonight I will put together a working example of the issue.

issue_example.zip

Have a working example here, let me know if I am missing something?

Steps to run example:

unzip and cd into root directory
npm install
npm run validate api.v0.yaml

Hi,

thanks for the example.
I think there is some misunderstanding about the use of references.
A reference is like a pointer to some other place in the schema. Typically in the same file, but by using the addSpecRef you can include contents from other files in your schema as well.

In your example you are referencing a place in the subschema that does not exist, so the field is effectively empty and therefore it gives you message: 'must NOT have unevaluated properties'.

The file you refer to is typically not a full openapi schema but just a fragment of such schema. See main-spec.v3.yaml that imports sub-spec.v3.yaml and sub-spec2.v3.yaml in

openapi-schema-validator/test/test-validation.js

Lines 214 to 219 in aca3046

    
           test(`addSpecRef works`, async (t) => { 
        
             t.plan(5); 
        
             const validator = new Validator(); 
        
             await validator.addSpecRef(subSpecYamlFileName, subSpecUri); 
        
             await validator.addSpecRef(subSpec2YamlFileName); 
        
             const res = await validator.validate(mainSpecYamlFileName);

Hope this helps.

Kind regards,
Hans

Okay, we can close this. My example should have used /post instead of /get and I think that reference was correct, but I don't want to to take up any more of your time until I can be sure.

updated_example.zip

I updated my example to something that I think should work following the example you provided. Can you explain why this does not work?

Ok, I forgot to mention one thing :-(

JSONschema allows you to have $ref's all over the place.
OpenApi 3.1.0 not so much :-(

Eg a path item can contain a $ref, but an operation object is not allowed to hold a $ref.

The spec also defines explicitly what you can put into components

Best way to start imho is to draft a simple spec in a doc. Then move parts to the components section (typically at the bottom) using internal refs and if that all works you can start moving those parts into separate files as shown in the test definition above.

Hope this helps.

Kind regards,
Hans

Thanks for the info, I will take your word for it until I have more time to research further.

	test(`addSpecRef works`, async (t) => {
	t.plan(5);
	const validator = new Validator();
	await validator.addSpecRef(subSpecYamlFileName, subSpecUri);
	await validator.addSpecRef(subSpec2YamlFileName);
	const res = await validator.validate(mainSpecYamlFileName);

Add local file reference to README