Carnegie Mellon University · API Governance Rules

Carnegie Mellon University API Rules

Spectral linting rules defining API design standards and conventions for Carnegie Mellon University.

7 Rules error 1 warn 5 info 1

View Rules File View on GitHub

Rule Categories

cmu

Rules

warn

cmu-info-contact

API info object should provide contact information.

$.info

warn

cmu-info-description

API info object should have a description.

$.info

error

cmu-servers-https

figshare KiltHub-backing API servers should use HTTPS.

$.servers[*].url

warn

cmu-operation-tags

Every operation should be tagged so endpoints are grouped (articles, collections, etc.).

$.paths[*][get,post,put,delete]

warn

cmu-article-doi-present

Article response schemas should expose a DOI property (persistent identifier convention).

$.components.schemas.Article.properties

warn

cmu-article-public-url

Article schemas should expose a public HTML url for citation/discovery.

$.components.schemas.Article.properties

info

cmu-snake-case-fields

figshare object fields follow snake_case naming.

$.components.schemas.Author.properties.*~

Spectral Ruleset

formats: [oas3]
rules:
  cmu-info-contact:
    description: API info object should provide contact information.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy
  cmu-info-description:
    description: API info object should have a description.
    severity: warn
    given: $.info
    then:
      field: description
      function: truthy
  cmu-servers-https:
    description: figshare KiltHub-backing API servers should use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"
  cmu-operation-tags:
    description: Every operation should be tagged so endpoints are grouped (articles, collections, etc.).
    severity: warn
    given: $.paths[*][get,post,put,delete]
    then:
      field: tags
      function: truthy
  cmu-article-doi-present:
    description: Article response schemas should expose a DOI property (persistent identifier convention).
    severity: warn
    given: $.components.schemas.Article.properties
    then:
      field: doi
      function: truthy
  cmu-article-public-url:
    description: Article schemas should expose a public HTML url for citation/discovery.
    severity: warn
    given: $.components.schemas.Article.properties
    then:
      field: url_public_html
      function: truthy
  cmu-snake-case-fields:
    description: figshare object fields follow snake_case naming.
    severity: info
    given: $.components.schemas.Author.properties.*~
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*$"