machine-actionable description, specification, documentation

[smrgeoinfo]

RE https://webapi-discovery.github.io/rfcs/rfc0001.html#definitions, I didn't find the 'definitions' in that article to be particularly useful.
Here's a proposal that should be less ambiguous: Machine-actionable description-- (was Machine-readable API Definition) a document conforming to some specification that describes the API in a way that is useful for machine(software) agents

Specification-- "A document that describes the technical characteristics of an artifact or practice, possibly including a description of what it should do, or an explicit set of requirements that it must satisfy." (http://purl.obolibrary.org/obo/IAO_0000115). Ideally, an API a specification should state the requirements that an endpoint conforming the the specification must meet, and conformance test to verify that those requirements are met. This document is intended as the authoritative description of the service for use by developers implementing the service (server side) or client software.

Documentation -- human readable description of API operations, input and output formats and information models, request syntax, and error codes, along with examples. Useful (but not the authority) to developers and general users of the service.

[MikeRalphson]

I find little evidence that "machine-actionable" is a more common or accurate term than "machine-readable", nor do I particularly find your definition an improvement.

The API industry is trying to standardise certain terms, in this effort "specification" is reserved for API description specifications (such as OpenAPI, AsyncAPI etc) whereas API description, definition or document is used for the documentation of the contract of an API. Including conformance testing in this seems unnecessary.

Limiting "documentation" to human readable descriptions is potentially confusing depending on the decision to use schema:endpointDescription or schema:documentation.

[smrgeoinfo]

Just FYI here's what I could infer from the text you reference:

from http://nordicapis.com/difference-api-documentation-specification-definition/ The difference between API Definition, Specification, and Documentation is a difference between human and machine readability, purpose, and goal.

API Definition -- definition of an API and its structure...geared toward machine-readability. ... focused on the concept of machine consumption

Specification-- informing about and documenting the API for human readability and “larger picture” understanding,...concerned with the overall behavior of the API, and how it links to other APIs

Documentation-- informing about and documenting the API with specific, direct examples and “in the grass” details. meant to be read, understood, and used by humans utilizing the API... including examples of how developers can use each function, and the constraints that the API allows...three tiers — top-level (basic understanding for basic functionality), functional understanding (remove abstraction from the rest of the documentation), and technical understanding (represents a reference from which to draw... referenceable in table format, with enough details to understand without being overwhelming).

I'd be curious to see what other interested parties might think about which definitions are more useful? I don't think its a good idea to close issues so quickly. Maybe someone else has an opinion that might be useful.