All APIs.json Rules

This is the catch all of the APIs.json rules.

Ruleset Definition

"apis-json-apis-aid-error": {"description":"This property ensures that each APIs indexed within an APIs.json can have a unique identifier expressed as an `aid`. API identifiers (AID) are a standardized format for allowing API producers to establish a unique identifier for each API they publish using APIs.json, which will have the aid for the APIs.json prepended to each APIs aid. You can find details about the <a href=\"https://apisjson.org/schema/aid/\">aid property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/identifiers/api-identifier/\" target=\"_blank\">API Unique Identifiers</a> more via API Evangelist.","message":"APIs MUST have a aid property.","given":"$.apis.*","severity":"error","then":{"field":"aid","function":"truthy"}},"apis-json-apis-aid-info": {"description":"This property ensures that each APIs indexed within an APIs.json can have a unique identifier expressed as an `aid`. API identifiers (AID) are a standardized format for allowing API producers to establish a unique identifier for each API they publish using APIs.json, which will have the aid for the APIs.json prepended to each APIs aid. You can find details about the <a href=\"https://apisjson.org/schema/aid/\">aid property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/identifiers/api-identifier/\" target=\"_blank\">API Unique Identifiers</a> more via API Evangelist.","message":"API has an aid property.","given":"$.apis.*","severity":"info","then":{"field":"aid","function":"falsy"}},"apis-json-apis-baseURL-error": {"description":"This is the base URL used for an API defined using APIs.json, providing a reference for developers to use when onboarding and making calls to an API, but it is also used as a way of referencing an API, and validating what domain it is part of. You can find details about the <a href=\"https://apisjson.org/schema/base-url/\">baseUrl property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/environments/base-url/\" target=\"_blank\">Base URLs</a> more via API Evangelist.","message":"APIs MUST have a baseUrl property.","given":"$.apis.*","severity":"error","then":{"field":"baseURL","function":"truthy"}},"apis-json-apis-baseURL-info": {"description":"This is the base URL used for an API defined using APIs.json, providing a reference for developers to use when onboarding and making calls to an API, but it is also used as a way of referencing an API, and validating what domain it is part of. You can find details about the <a href=\"https://apisjson.org/schema/base-url/\">baseUrl property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/environments/base-url/\" target=\"_blank\">Base URLs</a> more via API Evangelist.","message":"APIs has a baseUrl property.","given":"$.apis.*","severity":"info","then":{"field":"baseURL","function":"falsy"}},"apis-json-apis-contact-email-error": {"description":"Providing an email address is a quick way to provide support for each API being indexed. Depending on whether it is public or private, the email may be an individual or wider, and associated with a team. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/email/\" target=\"_blank\">support emails</a> more via API Evangelist.","message":"API contact COULD have email.","given":"$.apis.*.contact.*","severity":"error","then":{"field":"email","function":"truthy"}},"apis-json-apis-contact-email-info": {"description":"Providing an email address is a quick way to provide support for each API being indexed. Depending on whether it is public or private, the email may be an individual or wider, and associated with a team. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/email/\" target=\"_blank\">support emails</a> more via API Evangelist.","message":"API contact has email.","given":"$.apis.*.contact.*","severity":"info","then":{"field":"email","function":"falsy"}},"apis-json-apis-contact-error": {"description":"The contact object provides the ability to associate a vCard that represents an individual or any organization entity with common contact information like a name, email, or other reference, providing a standardized way of supporting an API. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/contact/\" target=\"_blank\">support contact</a> more via API Evangelist.","message":"API COULD have a contact.","severity":"warn","given":["$.apis.*"],"then":{"field":"contact","function":"truthy"}},"apis-json-apis-contact-fn-error": {"description":"The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an API. It could be a persons name or wider for a domain, team, or other bounded context, providing the reference needed for support or feedback. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/name/\" target=\"_blank\">support name</a> more via API Evangelist.","message":"API contact COULD have FN.","given":"$.apis.*.contact.*","severity":"error","then":{"field":"FN","function":"truthy"}},"apis-json-apis-contact-fn-info": {"description":"The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an API. It could be a persons name or wider for a domain, team, or other bounded context, providing the reference needed for support or feedback. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/name/\" target=\"_blank\">support name</a> more via API Evangelist.","message":"API contact has FN.","given":"$.apis.*.contact.*","severity":"info","then":{"field":"FN","function":"falsy"}},"apis-json-apis-contact-info": {"description":"The contact object provides the ability to associate a vCard that represents an individual or any organization entity with common contact information like a name, email, or other reference, providing a standardized way of supporting an API. You can find details about the <a href=\"https://apisjson.org/schema/apis-contact/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/contact/\" target=\"_blank\">support contact</a> more via API Evangelist.","message":"API has a contact.","severity":"info","given":["$.apis.*"],"then":{"field":"contact","function":"falsy"}},"apis-json-apis-description-info": {"description":"The description of each API is how you make your first impression on consumers, and is what will likely show in portals, networks, search, and other ways that API consumers discover APIs and onboard with them. Make the description of an API talk about what it does, and the value it brings to consumers, not about the structure and standards used--those can be expressed in other ways. You can find details about the <a href=\"https://apisjson.org/schema/description/\">description property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/descriptions/api-descriptions/\" target=\"_blank\">API descriptons</a> more via API Evangelist.","message":"API has a description.","given":"$.apis.*","severity":"info","then":{"field":"description","function":"falsy"}},"apis-json-apis-humanURL-info": {"description":"The human URL for an API provides a link for any business or technical consumer to use when learning more about an API and onboarding with it. In some cases it can be directly to documentation, but ideally each API has its own landing page with a simple and intuitive URL, and has links to all of the properties API consumers will need for an API. You can find details about the <a href=\"https://apisjson.org/schema/human-url/\">humanUrl property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/documentation/human-url/\" target=\"_blank\">Human URLs</a> more via API Evangelist.","message":"APIs has a human URL.","given":"$.apis.*","severity":"info","then":{"field":"humanURL","function":"falsy"}},"apis-json-apis-image-info": {"description":"A dedicated image for each API, providing a visual representation of the resource or capability being made available via an API helps make it more approachable and visually appealing in portals, documentation, and via other content format. Images should be simple, consistent, and should avoid just being company logos and other less precise visual representations. You can find details about the <a href=\"https://apisjson.org/schema/images/\">images property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/images/apis-json-images/\" target=\"_blank\">API images</a> more via API Evangelist.","message":"API has an image.","given":"$.apis.*","severity":"info","then":{"field":"image","function":"falsy"}},"apis-json-apis-info": {"description":"The APIs property provides the ability to define one or many APIs, as part of a larger collection or contract. What constitutes an API s up to the maintainer of the collection, and will vary depending on what the APIs.json contract is defining between producer and consumer. Depending on the scope of an API the sweet spot for the number of APIs is about 250, but could go up to 300 or 400 when necessary, keeping API definitions serving the purpose of the APIs.json artifact. You can find details about the <a href=\"https://apisjson.org/schema/apis/\">baseUrl property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/bounded-context/apis/\" target=\"_blank\">APIs</a> more via API Evangelist.","message":"There is an APIs property.","given":"$","severity":"info","then":{"field":"apis","function":"falsy"}},"apis-json-apis-name-info": {"description":"The name of your API is one of the most important design decision you can make, and will be one you will have to live with throughout the life of your API. Take the time to make sure the API accurately describes the API, and avoid using common words about the patterns and infrastructure used--keep the name of the API simple, easy to read, and meaningful to the consumer of the API. You can find details about the <a href=\"https://apisjson.org/schema/name/\">name property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/naming/api-names/\" target=\"_blank\">API names</a> more via API Evangelist.","message":"API has a name.","given":"$.apis.*","severity":"info","then":{"field":"name","function":"falsy"}},"apis-json-apis-properties-about-info": {"description":"API Properties About","message":"Has an about property.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(about|About)\\b"}}]},"apis-json-apis-properties-authentication-info": {"description":"API Properties Authentication","message":"Has authentication.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Authentication)\\b"}}]},"apis-json-apis-properties-blog-feed-info": {"description":"API Properties Blog Feed","message":"Offering a blog feed that is dedicated to your API helps increase engagement with consumers and help ensure they are more aware of what is happening.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(blog-feed|BlogFeed)\\b"}}]},"apis-json-apis-properties-blog-info": {"description":"API Properties Blog","message":"Offering a blog that is dedicated to your API helps increase engagement with consumers and help ensure they are more aware of what is happening.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(blog|Blog)\\b"}}]},"apis-json-apis-properties-change-log-info": {"description":"API Properties Change Change Log","message":"Has change log.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-change-log|change-log|Change Log|Changelog|ChangeLog)\\b"}}]},"apis-json-apis-properties-compare-info": {"description":"API Properties Change Compare","message":"Has API compare.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(compare|Compare)\\b"}}]},"apis-json-apis-properties-deprecation-policy-info": {"description":"API Properties Deprecation Policy","message":"Offering a deprecation policy page helping ensure consumers are aware of the deprecation strategy surrounding using an API, and how long it will be available for use.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-deprecation-policy|deprecation-policy|Deprecation|Deprecation Policy|DeprecationPolicy)\\b"}}]},"apis-json-apis-properties-documentation-info": {"description":"API Properties Documentation","message":"There is a documentation property.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(documentation|Documentation)\\b"}}]},"apis-json-apis-properties-environments-production-info": {"description":"API Properties Environments Production","message":"Offering a production environment makes it easy for consumers to access the details they need to work with an API in production.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-environment-production)\\b"}}]},"apis-json-apis-properties-environments-sandbox-info": {"description":"API Properties Environments Sandbox","message":"Has a sandbox.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-environment-sandbox)\\b"}}]},"apis-json-apis-properties-forum-info": {"description":"API Properties Forum","message":"Provides a dedicated forum to supporting an API and the community of consumers, ensuring that discussions around API usage is self-service.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Forums|Forums|Discussions)\\b"}}]},"apis-json-apis-properties-getting-started-info": {"description":"API Properties Getting Started","message":"Has a getting started.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(GettingStarted)\\b"}}]},"apis-json-apis-properties-github-organization-info": {"description":"API Properties GitHub Organization","message":"Provides a dedicated GitHub organizations as part API operations, offering up a link to all of the resources available across all APIs being made available.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(github-organization|GitHubOrganization)\\b"}}]},"apis-json-apis-properties-github-repository-info": {"description":"API Properties GitHub Repository","message":"Has a GitHub repository.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(github-repository|GitHubRepository)\\b"}}]},"apis-json-apis-properties-insomnia-collection-info": {"description":"API Properties Insomnia Collection","message":"Has a Insomnia Collection.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(RunInInsomnia)\\b"}}]},"apis-json-apis-properties-license-info": {"description":"API Properties Legal License","message":"Offering a dedicated licensing page helps ensure consumers are aware of the licensing for an API, SDKs, and other supporting resources.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-license|License|license|InterfaceLicense)\\b"}}]},"apis-json-apis-properties-lifecycle-info": {"description":"API Properties Lifecycle","message":"Providing an overview of how an API is version, providing details on semantic or date-based lifecycle, helping consumers understand more about change management in place.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(lifecycle|Lifecycle|Life Cycle)\\b"}}]},"apis-json-apis-properties-openapi-info": {"description":"API Properties OpenAPI","message":"API has and OpenAPI.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(openapi|OpenAPI)\\b"}}]},"apis-json-apis-properties-performance-info": {"description":"API Properties Performance","message":"Offering information regarding the performance of an API, making available processes, tests, results, and the other evidence of API performance.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Performance|PerformanceTesting)\\b"}}]},"apis-json-apis-properties-plans-info": {"description":"API Properties Plans","message":"Has a plans page.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-plans|Plans)\\b"}}]},"apis-json-apis-properties-policies-info": {"description":"API Properties Policies","message":"Has a policies page.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-policies|Policies)\\b"}}]},"apis-json-apis-properties-portal-info": {"description":"API Properties Portal","message":"Has a portal","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-developer-portal|developer-portal|portal|Portal|Portals|DeveloperPortal)\\b"}}]},"apis-json-apis-properties-postman-collection-info": {"description":"API Properties Postman Collection","message":"Has a Postman Collection.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(PostmanCollection)\\b"}}]},"apis-json-apis-properties-postman-public-workspace-info": {"description":"API Properties Postman Public Workspace","message":"Providing a public Postman workspace","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(postman-public-workspace)\\b"}}]},"apis-json-apis-properties-pricing-info": {"description":"API Properties Pricing","message":"Has a pricing page.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Pricing)\\b"}}]},"apis-json-apis-properties-privacy-policy-info": {"description":"API Properties Privacy Policy","message":"Offering a dedicated privacy policy page helps ensure consumers are aware of the privacy requirements surrounding using an API.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-privacy-policy|privacy-policy|Privacy|Privacy Policy|PrivacyPolicy)\\b"}}]},"apis-json-apis-properties-rate-limits-info": {"description":"API Properties Rate Limits","message":"Offers details regarding rate limits in place against an API as well as the wider platform around it, helping consumers understand the limitations of API integration.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(rate-limits|RateLimits|Rate Limits)\\b"}}]},"apis-json-apis-properties-road-map-info": {"description":"API Properties Road Map","message":"Has road map.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-road-map|road-map|Roadmap|Road Map|RoadMap)\\b"}}]},"apis-json-apis-properties-rules-info": {"description":"API Properties Rules","message":"Has a rules page.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-rules|Rules)\\b"}}]},"apis-json-apis-properties-sdk-go-info": {"description":"API Properties SDK Go","message":"Offering a Go SDK for consumers to use will save them time when it comes to onboarding and integrating an API into their applications.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-sdk-go)\\b"}}]},"apis-json-apis-properties-sdk-info": {"description":"API Properties SDK","message":"Has an SDK.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(sdk|sdks|SDKs)\\b"}}]},"apis-json-apis-properties-sdk-java-info": {"description":"API Properties Java Node","message":"Offering a Java SDK for consumers to use will save them time when it comes to onboarding and integrating an API into their applications.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-sdk-java)\\b"}}]},"apis-json-apis-properties-sdk-node-info": {"description":"API Properties SDK Node","message":"Offering a Node SDK for consumers to use will save them time when it comes to onboarding and integrating an API into their applications.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-sdk-node)\\b"}}]},"apis-json-apis-properties-sdk-python-info": {"description":"API Properties SDK Python","message":"Offering a Python SDK for consumers to use will save them time when it comes to onboarding and integrating an API into their applications.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-sdk-python)\\b"}}]},"apis-json-apis-properties-security-info": {"description":"API Properties Security","message":"Offering information regarding the security of an API, making available processes, tests, results, and the other evidence of API security.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Security|SecurityTesting)\\b"}}]},"apis-json-apis-properties-signup-info": {"description":"API Properties Management Signup","message":"Has a sign up.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(X-signup|signup|Sign Up|SignUp|Signup)\\b"}}]},"apis-json-apis-properties-status-info": {"description":"API Properties Status","message":"Has an status page.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(x-status|status|Status|StatusPage)\\b"}}]},"apis-json-apis-properties-support-email-info": {"description":"API Properties Email email","message":"Offering a dedicated email channel for your API makes it very simple for consumers to get the support they need when using your API.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(email|Email)\\b"}}]},"apis-json-apis-properties-support-issues-info": {"description":"API Properties Support Issues","message":"Offering a support using GitHub issues offers an easy way to encourage consumers to submit issues and communicate in a self-service way.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(issues|x-issues|Issues)\\b"}}]},"apis-json-apis-properties-support-support-info": {"description":"API Properties Support Support","message":"Offering a formal support page and channel helps make it easy for consumers to find the help they need with putting aPIs to work.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(support|Support)\\b"}}]},"apis-json-apis-properties-terms-of-service-info": {"description":"API Properties Terms of Service","message":"Offering a dedicated terms of service page helps ensure consumers are aware of what is expected when it comes to using a service.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-terms-of-service|terms-of-service|Terms of Service|TOS|TermsOfService)\\b"}}]},"apis-json-apis-properties-uptime-monitor-info": {"description":"API Properties Uptime Monitor","message":"Has an uptime monitor.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(api-uptime-monitor|uptime-monitor|UptimeMonitor)\\b"}}]},"apis-json-apis-properties-url-info": {"description":"API Properties URL","message":"API Properties URL","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"url","function":"pattern","functionOptions":{"notMatch":"^((http|https)://)[-a-zA-Z0-9@:%._\\+~#?&//=]{2,256}\\.[a-z]{2,6}\\b([-a-zA-Z0-9@:%._\\+~#?&//=]*)$"}}]},"apis-json-apis-properties-use-cases-info": {"description":"API Properties Use Cases","message":"Providing a list of use cases for an API, defining the who, what, how, and why of API consumption, helping map to operations.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(UseCases)\\b"}}]},"apis-json-apis-properties-versioning-info": {"description":"API Properties Versioning","message":"Providing an overview of how an API is version, providing details on semantic or date-based versioning, helping consumers understand more about change management in place.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(Versions|Versioning)\\b"}}]},"apis-json-apis-properties-video-info": {"description":"API Properties Video","message":"Offering a video channel that is dedicated to your API helps increase engagement with consumers and help ensure they are more aware of what is happening.","severity":"info","given":["$.apis.*.properties.*","$.common.*"],"then":[{"field":"type","function":"pattern","functionOptions":{"notMatch":"\\b(videos|Videos)\\b"}}]},"apis-json-apis-tags-info": {"description":"Tags for API","message":"API has tags object.","given":"$.apis.*","severity":"info","then":{"field":"tags","function":"falsy"}},"apis-json-apis-tags-upper-case-error": {"description":"Upper Case Tag for API","message":"API Tags Upper Case","severity":"error","given":"$.apis.*.tags.*","then":{"function":"pattern","functionOptions":{"match":"[A-Z]\\w*"}}},"apis-json-apis-tags-upper-case-info": {"description":"Upper Case Tag for API","message":"API Tags Upper Case","severity":"info","given":"$.apis.*.tags.*","then":{"function":"pattern","functionOptions":{"notMatch":"[A-Z]\\w*"}}},"apis-json-common-info": {"description":"The common property is where all of the properties that apply across multiple APIs are stored. If the APIs.json is maintained by the API producer they are usually the common services supported via the developer portal, but if not, they could be external services offered by community, platform, or other entities. You can find details about the <a href=\"https://apisjson.org/schema/common/\">baseUrl property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/discovery/common/\" target=\"_blank\">common discovery properties</a> more via API Evangelist.","message":"There is an common property.","given":"$","severity":"info","then":{"field":"common","function":"falsy"}},"apis-json-created-info": {"description":"The created property is all about setting the timestamp for when an APIs.json index, contract, or other type is established--drawing a line in the sand for when everything started. The created property works in concert with the modified property and other change manage properties to understand and get a handle on the inevitable change that occurs across any API platform. You can find details about the <a href=\"https://apisjson.org/schema/created/\">created property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/change/created/\" target=\"_blank\">how created property is used to manage change</a> more via API Evangelist.","message":"There is a created date.","given":"$","severity":"info","then":{"field":"created","function":"falsy"}},"apis-json-description-info": {"description":"The description property is where you provide full details the purpose an APIs.json serves. This description is likely more higher level than any of the descriptions for any single API, and be more about the contract, index, blueprint, or the other reasons why the APIs.json is of value. Don't make the description too long, but also don't make it too short--it is likely the first impression you will make via portals, repos, and other ways an APIs.json will be discovered. You can find details about the <a href=\"https://apisjson.org/schema/description/\">description property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/descriptions/apis-json-descriptions/\" target=\"_blank\">APIs.json</a> more via API Evangelist.","message":"There is a description.","given":"$","severity":"info","then":{"field":"description","function":"falsy"}},"apis-json-image-info": {"description":"Images for APIs.json help make them more visible when rendered as a search or individual node, used as part of an API portal, or other ways. The image should represent the entity logo, line of business, or other meaningful visual representation of the bounded context represented within the APis.json. You can find details about the <a href=\"https://apisjson.org/schema/images/\">images property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/images/apis-json-images/\" target=\"_blank\">using images</a> more via API Evangelist.","message":"There is an image.","given":"$","severity":"info","then":{"field":"image","function":"falsy"}},"apis-json-maintainers-email-info": {"description":"The maintainers email is to provide a quick way to contact the maintainer of an APIs.json contract. The email is just one of multiple vCard properties that can exist, but provides the simplest way to engage with stakeholders involved in maintaining an APIs.json artifact. You can find details about the <a href=\"https://apisjson.org/schema/maintainers-email/\">maintainers email property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/email/\" target=\"_blank\">email support</a> more via API Evangelist.","message":"There is a email property for maintainers.","given":"$.maintainers.*","severity":"info","then":{"field":"email","function":"falsy"}},"apis-json-maintainers-fn-info": {"description":"The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an APIs.json contract or index. It could be a persons name or wider for a domain, team, or other bounded context, providing the reference needed for support or feedback. You can find details about the <a href=\"https://apisjson.org/schema/maintainers-fn/\">API contact property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/name/\" target=\"_blank\">support name</a> more via API Evangelist.","message":"There is a FN property for maintainers.","given":"$.maintainers.*","severity":"info","then":{"field":"FN","function":"falsy"}},"apis-json-maintainers-info": {"description":"The maintainers property is for identifying the entity who is maintaining an APIs.json contract, index, or other type. The maintainer may or may not be an API producer, and the maintainer property is used to provide access to the contact information for the maintainer, but is also used to validate the authoritative nature of the contract itself. You can find details about the <a href=\"https://apisjson.org/schema/maintianers/\">maintainers property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/support/names/\" target=\"_blank\">support</a> more via API Evangelist.","message":"There is a maintainer object.","given":"$","severity":"info","then":{"field":"maintainers","function":"falsy"}},"apis-json-modified-info": {"description":"The modified property of an APIs.json is meant to be updated with the date of when any changes were made to the contract or index. The modified properties works in concert with the created property, as well as other change management properties employed to help get a handle on the changes that are inevitable across API operations. You can find details about the <a href=\"https://apisjson.org/schema/modified/\">modified property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/change/modified/\" target=\"_blank\">modified property and change management</a> more via API Evangelist.","message":"There is a modified date.","given":"$","severity":"info","then":{"field":"modified","function":"falsy"}},"apis-json-name-info": {"description":"The name of an APIs.json file is different than the name of your API, and is intended to describe the purpose of the APIs.json artifact, and what it provides for API producers, consumers, and other stakeholders. The name should be short and concise, describing the intent in bringing the the collection together, leaving the names of APIs to describe what each API does. You can find details about the <a href=\"https://apisjson.org/schema/names/\">names property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/naming/apis-json-names/\" target=\"_blank\">APIs.json names</a> more via API Evangelist.","message":"There is a name.","severity":"info","given":"$","then":{"field":"name","function":"falsy"}},"apis-json-specification-aid-info": {"description":"Ensures that each APIs.json has a unique identifier expressed as an `aid`. APIs.json identifiers are a standardized format for allowing API producers to establish a unique identifier for each API contract they provide using APIs.json, which will then be prepended to each APIs defined. You can find details about the standard for APIs.json unique identifier on API Commons [need link], and explore <a href=\"https://apievangelist.com/guidance/identifiers/apis-json-identifier/\" target=\"_blank\">APIs.json Unique Identifiers</a> via API Evangelist.","message":"There is an aid.","severity":"info","given":"$","then":{"field":"aid","function":"falsy"}},"apis-json-specification-type-info": {"description":"The specification type for an APIs.json sets the tone for how the APIs.json will be processed, providing a way to namespace different ways of leveraging the machine-readable contents of the APIs/json. The most common is a simple index of one or many APIs, but originally templates and examples were also allowed. Contracts, blueprints, and a handful of other types have recently been added, expanding the ways in which the APIs.json specification can be used beyond just API discovery. You can find details about the <a href=\"https://apisjson.org/schema/type/\">type property for APIs.json</a>.","message":"There is a specification type.","severity":"info","given":"$","then":{"field":"type","function":"falsy"}},"apis-json-specification-version-info": {"description":"The specification version of an APIs.json defines what properties are supported by the APIs.json artifact. New core properties, as well as property types are being added with each version to support a variety of solutions, and expand how APIs.json is used across API operations. You can find details about the <a href=\"https://apisjson.org/schema/specification-version/\">specification version property for APIs.json</a>.","message":"There is a specification version.","severity":"info","given":"$","then":{"field":"specificationVersion","function":"falsy"}},"apis-json-tags-info": {"description":"Tags applied to an APIs.json should provide a handful of high-level tags that describe the purpose and intent of an APIs.json. These could be tags that describe the search node, or tags specifically for the individual APIs that are of concern for a specific API contract between producer and consumer. Tags provide the bounded context needed to help make APIs more tangible and meaningful for both API producers and consumers. You can find details about the <a href=\"https://apisjson.org/schema/tags/\">tags property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/bounded-context/apis-json-tags/\" target=\"_blank\">tagging</a> more via API Evangelist.","message":"There is a tags object.","given":"$","severity":"info","then":{"field":"tags","function":"falsy"}},"apis-json-tags-upper-case-error": {"description":"Tags are useful for defining the bounded context of API operations, and it helps to ensure they are consistently capitalized for better display within documentation and other resources. Emsuring that the first letter is upper cased, acronyms properly cased, and other terms, helps make sure things are readable, and act as a vocabulary for API operations. You can find details about the <a href=\"https://apisjson.org/schema/tags/\">tags property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/bounded-context/apis-json-tags/\" target=\"_blank\">tagging</a> more via API Evangelist.","message":"Tags Upper Case","severity":"error","given":"$.tags.*","then":{"function":"pattern","functionOptions":{"match":"[A-Z]\\w*"}}},"apis-json-tags-upper-case-info": {"description":"Tags are useful for defining the bounded context of API operations, and it helps to ensure they are consistently capitalized for better display within documentation and other resources. Emsuring that the first letter is upper cased, acronyms properly cased, and other terms, helps make sure things are readable, and act as a vocabulary for API operations. You can find details about the <a href=\"https://apisjson.org/schema/tags/\">tags property for APIs.json</a>, and explore <a href=\"https://apievangelist.com/guidance/bounded-context/apis-json-tags/\" target=\"_blank\">tagging</a> more via API Evangelist.","message":"Tags Upper Case","severity":"info","given":"$.tags.*","then":{"function":"pattern","functionOptions":{"notMatch":"[A-Z]\\w*"}}},"apis-json-url-info": {"description":"The URL for an APIs.json provides a link to the source of an APIs.json, but also determines whether or not an APIs.json is authoritative or not. The URL is a locator, but can also be used as an identifier that can be used to ensure the authenticity and origin of APIs.json. The URL is regularly validated as part of API operations and the solutions using the APIs.json. You can find details about the <a href=\"https://apisjson.org/schema/url/\">url property for APIs.json</a>.","message":"There is a URL.","given":"$","severity":"info","then":{"field":"url","function":"falsy"}},

Back to All of the Rulesets

All APIs.json Rules

This Page

Open & Ask

Ruleset Definition