Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Consideration for validating and linting the OAS with IBM's openapi-validator #24

Closed
lewismc opened this issue Jul 11, 2019 · 4 comments
Closed

Consideration for validating and linting the OAS with IBM's openapi-validator #24

lewismc opened this issue Jul 11, 2019 · 4 comments
Assignees
@Schpidi @cmheazel

Comments

@lewismc
Copy link
Member

lewismc commented Jul 11, 2019

Unfortunately I was unable to contribute to the development of the coverages OAS at the hackathon in London.
I would however like to propose that we use IBM's openapi-validator to further standardize the way that the coverages OAS looks.
The results of running the validator are as follows

lint-openapi openapi.yaml

[Warning] No .validaterc file found. The validator will run in default mode.
To configure the validator, create a .validaterc file.

errors

  Message :   Property type+format is not well-defined.
  Path    :   components.schemas.extent.properties.temporal.items.type
  Line    :   526

  Message :   Property type+format is not well-defined.
  Path    :   components.schemas.collectionGeoJSON.properties.timeStamp.type
  Line    :   547

warnings

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./.get.operationId
  Line    :   36

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./conformance.get.operationId
  Line    :   54

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections.get.operationId
  Line    :   73

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}.get.operationId
  Line    :   98

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages.get.operationId
  Line    :   136

  Message :   tag is not defined at the global level: Coverages
  Path    :   paths./collections/{collectionId}/coverages.get.tags
  Line    :   131

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}.get.operationId
  Line    :   222

  Message :   tag is not defined at the global level: Coverages
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}.get.tags
  Line    :   219

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/domainset.get.operationId
  Line    :   265

  Message :   tag is not defined at the global level: Coverages
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/domainset.get.tags
  Line    :   262

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/rangetype.get.operationId
  Line    :   308

  Message :   tag is not defined at the global level: Coverages
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/rangetype.get.tags
  Line    :   305

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}.get.parameters.0
  Line    :   100

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages.get.parameters.0
  Line    :   138

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}.get.parameters.0
  Line    :   224

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}.get.parameters.1
  Line    :   232

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/domainset.get.parameters.0
  Line    :   267

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/domainset.get.parameters.1
  Line    :   275

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/rangetype.get.parameters.0
  Line    :   310

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   paths./collections/{collectionId}/coverages/{coverageId}/rangetype.get.parameters.1
  Line    :   318

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.collectionId
  Line    :   653

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.coverageId
  Line    :   662

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.exception
  Line    :   347

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.exception.properties.code.description
  Line    :   352

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.exception.properties.description.description
  Line    :   354

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.root
  Line    :   356

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.root.properties.links.description
  Line    :   361

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.req-classes
  Line    :   382

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.req-classes.properties.conformsTo.description
  Line    :   387

  Message :   Property names must be lower snake case.
  Path    :   components.schemas.req-classes.properties.conformsTo
  Line    :   387

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.link
  Line    :   396

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.link.properties.href.description
  Line    :   401

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.link.properties.rel.description
  Line    :   403

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.link.properties.type.description
  Line    :   406

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.link.properties.hreflang.description
  Line    :   409

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.content
  Line    :   412

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.content.properties.links.description
  Line    :   418

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.content.properties.collections.description
  Line    :   435

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.collectionInfo
  Line    :   439

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionInfo.properties.links.description
  Line    :   457

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.extent
  Line    :   483

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.extent.properties.crs.enum.0
  Line    :   493

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.extent.properties.trs.enum.0
  Line    :   516

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.collectionGeoJSON
  Line    :   528

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.type.description
  Line    :   534

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.features.description
  Line    :   538

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.links.description
  Line    :   542

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.timeStamp.description
  Line    :   546

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.numberMatched.description
  Line    :   549

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.collectionGeoJSON.properties.numberReturned.description
  Line    :   552

  Message :   Property names must be lower snake case.
  Path    :   components.schemas.collectionGeoJSON.properties.timeStamp
  Line    :   546

  Message :   Property names must be lower snake case.
  Path    :   components.schemas.collectionGeoJSON.properties.numberMatched
  Line    :   549

  Message :   Property names must be lower snake case.
  Path    :   components.schemas.collectionGeoJSON.properties.numberReturned
  Line    :   552

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.collectionGeoJSON.properties.type.enum.0
  Line    :   537

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.featureGeoJSON
  Line    :   555

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.featureGeoJSON.properties.type.description
  Line    :   562

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.featureGeoJSON.properties.properties.description
  Line    :   568

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.featureGeoJSON.properties.type.enum.0
  Line    :   565

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.geometryGeoJSON
  Line    :   575

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.geometryGeoJSON.properties.type.description
  Line    :   580

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.0
  Line    :   583

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.1
  Line    :   584

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.2
  Line    :   585

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.3
  Line    :   586

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.4
  Line    :   587

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.5
  Line    :   588

  Message :   Enum values must be lower snake case.
  Path    :   components.schemas.geometryGeoJSON.properties.type.enum.6
  Line    :   589

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.domainSetJSON
  Line    :   590

  Message :   Schema properties must have a description with content in it.
  Path    :   components.schemas.domainSetJSON.properties.type.description
  Line    :   595

  Message :   Schema must have a non-empty description.
  Path    :   components.schemas.rangeTypeJSON
  Line    :   597

As you can see there are some issues here which relate closely to those raised in #23 for example.

Does anyone have preference on this issue? I would like to know whether I should invest the time to address the issues flagged by the linter before I go ahead and do so.
Thanks
@Schpidi
Copy link
Member

Schpidi commented Jul 19, 2019

Good idea to use a validator.
Regarding case, we decided to use all lower case #11 (comment)

@lewismc
Copy link
Member Author

lewismc commented Jul 19, 2019

OK @Schpidi. Well let me know if I should address the issues or not. Thanks

@Schpidi
Copy link
Member

Schpidi commented Sep 14, 2020

At https://github.com/Schpidi/ogcapi-coverages-1 I'm working to get a complete valid version of the schemas from which the relevant parts can be used in the various OAPI repos.

I'm using the spectral linter which is quite happy right now using spectral lint -v ogcapi-coverages-1.yaml.

The IBM validator reports some issues. I guess we should try to follow the recommendations shouldn't we?

lint-openapi ogcapi-coverages-1.yaml 

errors

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.rangeSubset
  Line    :   363

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.scaleFactor
  Line    :   373

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.scaleAxis
  Line    :   382

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.scaleSize
  Line    :   391

  Message :   Parameter names must follow case convention: lower_snake_case
  Path    :   components.parameters.scaleExtent
  Line    :   400

warnings

  Message :   Swagger object should not contain circular references.
  Path    :   paths./api.get.responses.200.content.application/json.schema
  Line    :   58

  Message :   A paginated list operation must include a "limit" property in the response body schema.
  Path    :   paths./collections.get.responses.200.content.application/json.schema.properties
  Line    :   118

  Message :   operationIds should follow naming convention: operationId verb should be list
  Path    :   paths./collections.get.operationId
  Line    :   107

  Message :   operationIds should follow naming convention: operationId verb should be get
  Path    :   paths./collections/{coverageid}.get.operationId
  Line    :   138

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./.get.operationId
  Line    :   31

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./api.get.operationId
  Line    :   50

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./conformance.get.operationId
  Line    :   72

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections.get.operationId
  Line    :   107

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}.get.operationId
  Line    :   138

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}/coverage.get.operationId
  Line    :   169

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}/coverage/domainset.get.operationId
  Line    :   215

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}/coverage/rangetype.get.operationId
  Line    :   244

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}/coverage/rangeset.get.operationId
  Line    :   272

  Message :   operationIds must follow case convention: lower_snake_case
  Path    :   paths./collections/{coverageid}/coverage/metadata.get.operationId
  Line    :   308

  Message :   schema $refs must follow this format: *#/components/schemas*
  Path    :   paths./api.get.responses.200.content.application/json.schema.$ref
  Line    :   59

@Schpidi Schpidi self-assigned this Sep 14, 2020
@cmheazel cmheazel self-assigned this Apr 20, 2021
jerstlouis added a commit to jerstlouis/ogcapi-coverages that referenced this issue Jul 23, 2021
@jerstlouis
Migrated improved OpenAPI schemas from schema-work branch (opengeospa…
2700423 
…tial#24,opengeospatial#26,opengeospatial#96,opengeospatial#100)
jerstlouis added a commit that referenced this issue Jul 28, 2021
@jerstlouis
Migrated improved OpenAPI schemas from schema-work branch (#24,#26,#96,…
d8e5ebf 
…#100)
@jerstlouis
Copy link
Member

2021-07-28: Last week Stephan confirmed that the latest schema from OpenAPI branch passed linting with Spectral with no errors. Now that the OpenAPI definitions from schema-work branch are merged into master, please file a new issue if new errors are discovered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Schpidi Schpidi

@cmheazel cmheazel

Labels
None yet
Projects
OGC API - Coverages - Part 1: Core
Status: Done
Milestone
No milestone
Development

No branches or pull requests
4 participants
@Schpidi @lewismc @jerstlouis @cmheazel