From 04397c1c830f79e65ab8e17828073f91eb995a04 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Mon, 2 Mar 2026 13:09:08 +0000 Subject: [PATCH 1/2] fix(spec): refactor complexity_comfort signal --- docs/publishing/overview-template.md | 3 ++- docs/specification/spec.md | 28 ++++++++++++++++++++++------ package.json | 2 +- 3 files changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/publishing/overview-template.md b/docs/publishing/overview-template.md index a32d989..e77da63 100644 --- a/docs/publishing/overview-template.md +++ b/docs/publishing/overview-template.md @@ -98,7 +98,8 @@ The framework works with OpenAPI 3.x and 2.x specifications. It's implementation - **[Full Specification](specification.md)** — Complete technical specification with normative requirements - **[Framework Repository](https://github.com/jentic/api-ai-readiness-framework)** — full source specification, contribution guidelines, and issue tracking - **[Jentic Public APIs](https://github.com/jentic/jentic-public-apis)** — Collection of scored API specifications demonstrating the framework in practice -- **Blog Posts**: + +**Blog Posts**: - [Why Most APIs Fail in AI Systems and How to Fix It](https://thenewstack.io/why-most-apis-fail-in-ai-systems-and-how-to-fix-it/) (The New Stack) - [Is Your OpenAPI AI-Ready?](https://jentic.com/blog/is-your-open-api-ai-ready) (Jentic) - [Scoring APIs for AI](https://jentic.com/blog/scoring-apis-for-ai) (Jentic) diff --git a/docs/specification/spec.md b/docs/specification/spec.md index a89039a..de3eb43 100644 --- a/docs/specification/spec.md +++ b/docs/specification/spec.md @@ -1,6 +1,6 @@ # Jentic API AI-Readiness Framework (JAIRF) Specification -## Version 0.2.0 +## Version 1.0.0 This document uses the key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY as defined in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. @@ -587,14 +587,20 @@ API usability for agents degrades as endpoint count grows — but only after a c **Formula:** ```text -normalised_endpoint_count = min(1, total_operations / endpoint_baseline) +normalised_endpoint_count = max(0, min(1, (total_operations - 50) / 150)) ``` Where: - `total_operations` is the count of unique forward-callable operations (method + path pairs). [Callbacks](https://spec.openapis.org/oas/v3.2.0.html#callback-object) and [webhooks](https://spec.openapis.org/oas/v3.2.0.html#oas-webhooks) MUST NOT be counted as endpoints. -- `endpoint_baseline` is set at `50`. +- Penalties begin at 50 operations and reach maximum at 200 operations, with linear interpolation between these thresholds. +Examples: + +- 50 operations: 0% penalty (comfort zone boundary) +- 100 operations: 33% penalty (moderate complexity) +- 150 operations: 67% penalty (substantial complexity) +- 200+ operations: 100% penalty (monolithic) ##### Normalised Schema Depth (normalised_schema_depth) @@ -606,20 +612,30 @@ Agent reasoning difficulty can be correlated to object depth, degree of polymorp **Formula:** ```text -normalised_schema_depth = min(1, max_schema_depth / depth_baseline) +normalised_schema_depth = min(1, (max_schema_depth / depth_baseline) × pct_schemas_exceeding) ``` Where: - `max_schema_depth` is the deepest nesting found across all schemas -- `depth_baseline` is set at `8`. +- `pct_schemas_exceeding` is the proportion of schemas exceeding the depth threshold: + pct_schemas_exceeding = count(schemas with depth > depth_baseline) / total_schemas +- `depth_baseline` is set at `18` Schemas referenced by callbacks/webhooks MUST be included in `normalised_schema_depth`, because they contribute to the overall semantic model complexity. +The penalty is proportional to schema depth prevalence, not just maximum depth. An API where 1% of schemas exceed the threshold (outliers) receives 1% of the maximum penalty, while an API where 80% of schemas exceed (uniform complexity) receives 80% of the maximum penalty. This directly models agent operational experience. Agents encounter complexity proportional to its prevalence in the schema set, not based solely on the existence of a single deep schema. + +Examples: + +- 1% of schemas exceed threshold: 1% of max penalty applied (outlier case) +- 50% of schemas exceed threshold: 50% of max penalty applied +- 80% of schemas exceed threshold: 80% of max penalty applied (uniform complexity) + #### Distinctiveness (distinctiveness) ```text -distinctiveness = 1- avg_semantic_similarity +distinctiveness = 1 - avg_semantic_similarity ``` #### Pagination (pagination) diff --git a/package.json b/package.json index a256653..572b322 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "api-ai-readiness-framework", - "version": "0.1.0", + "version": "1.0.0", "description": "A technical specification for the Jentic API AI-Readiness Framework (JAIRF). Defines the signals, dimensions, scoring model, and normalisation rules used to evaluate how interpretable, operable, and trustworthy APIs are for AI systems and autonomous agents.", "main": "index.js", "directories": { From 0ef9890f6b88da63e69512c363ea76490b6eb502 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Mon, 2 Mar 2026 13:11:46 +0000 Subject: [PATCH 2/2] chore(docs): fix linting issues --- docs/publishing/overview-template.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/publishing/overview-template.md b/docs/publishing/overview-template.md index e77da63..8a89557 100644 --- a/docs/publishing/overview-template.md +++ b/docs/publishing/overview-template.md @@ -100,9 +100,10 @@ The framework works with OpenAPI 3.x and 2.x specifications. It's implementation - **[Jentic Public APIs](https://github.com/jentic/jentic-public-apis)** — Collection of scored API specifications demonstrating the framework in practice **Blog Posts**: - - [Why Most APIs Fail in AI Systems and How to Fix It](https://thenewstack.io/why-most-apis-fail-in-ai-systems-and-how-to-fix-it/) (The New Stack) - - [Is Your OpenAPI AI-Ready?](https://jentic.com/blog/is-your-open-api-ai-ready) (Jentic) - - [Scoring APIs for AI](https://jentic.com/blog/scoring-apis-for-ai) (Jentic) + +- [Why Most APIs Fail in AI Systems and How to Fix It](https://thenewstack.io/why-most-apis-fail-in-ai-systems-and-how-to-fix-it/) (The New Stack) +- [Is Your OpenAPI AI-Ready?](https://jentic.com/blog/is-your-open-api-ai-ready) (Jentic) +- [Scoring APIs for AI](https://jentic.com/blog/scoring-apis-for-ai) (Jentic) ## Contributing