Add x-sap-ai-hint extension

.gitignore

@@ -1,2 +1,4 @@
 node_modules
-dist
+dist
+.claude/
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Added
+
+- `x-sap-ai-hint` extension for Info Object, Operation Object, Parameter Object, and Schema Object. 
+  - Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element, intentionally kept separate from human-readable `description` fields so that end-user-facing documentation and AI-targeted guidance can evolve independently.
+
+---
+
+## 2024-11-18 (#31)
+
+### Changed
+
+- Updated description of `x-sap-dpp-field-semantics` to clarify meaning and usage.
+
+## 2024-10-24 (#32)
+
+### Added
+
+- `x-sap-odm-semantic-key` on Schema Object. A human-readable identifier used to identify business objects by the end-user. Carries an array of key name/values pairs.
+
+## 2024-09-30 (#30)
+
+### Added
+
+- `x-sap-dpp-entity-semantics` on Schema Object. Primary meaning of the personal data in the annotated entity set (`sap:DataSubject`, `sap:DataSubjectDetails`, `sap:Other`).
+- `x-sap-dpp-data-subject-role` on Schema Object. Role of the data subjects in the set (e.g. employee, customer).
+- `x-sap-dpp-data-subject-role-description` on Schema Object. Language-dependent description of the data subject role.
+- `x-sap-dpp-field-semantics` on Schema Object. Primary meaning of personal data in a property; drives audit log tracking.
+- `x-sap-dpp-is-potentially-personal` on Schema Object. Flags a property as containing potentially personal data.
+- `x-sap-dpp-is-potentially-sensitive` on Schema Object. Flags a property as containing potentially sensitive personal data.
+
+## 2024-06-17 (#23, #25, #26, #27, #28)
+
+### Added
+
+- GitHub Actions CI workflow (build on push/PR) and release workflow (publish to npmjs.com).
+
+### Changed
+
+- Cleaned up npm package metadata and repository URL.
+
+## 2024-06-10 (#24)
+
+### Added
+
+- `x-sap-deprecated-operation` on Operation Object. Carries structured deprecation metadata: `deprecationDate` (RFC 3339 date), and either `successorOperationRef` (URI reference) or `successorOperationId` (operationId string) — exactly one successor field is required.
+
+## 2024-03-26 (#20)
+
+### Added
+
+- `x-sap-operation-intent` on Operation Object. Communicates the semantic intent of an operation (`create-single`, `read-collection`, `update-single`, `upsert-collection`, `action`, etc.).
+
+## 2024-03-01 (#22)
+
+### Added
+
+- `x-sap-ord-id` at OpenAPI Object (root) level. Links the API resource to its corresponding ORD ID using the pattern `<namespace>:apiResource:<name>:<version>`.
+
+## 2024-02-29 (#16)
+
+### Changed
+
+- `x-sap-ext-overview` value items now have a proper JSON Schema: each item can be a plain string or an object with `text` (string) and `format` (`plain` | `markdown`).
+
+## 2024-01-26 (#19)
+
+### Fixed
+
+- Aligned naming of deprecation-related attributes in documentation for consistency across extensions.
+
+## 2024-01-17 (#18)
+
+### Changed
+
+- Improved the primitive type mapping table in README with corrected JSON examples.
+
+## 2023-11-16 (#17)
+
+### Added
+
+- `x-sap-odm-oid-reference-entity-name` on Schema Object. Specifies the ODM entity name of a referenced entity on a property that holds a foreign OID reference.
+
+## 2023-04-21 (#13)
+
+### Added
+
+- Primitive type mapping table in README covering ABAP, CAP, Java, OData, SQL, and OpenAPI type/format correspondences.
+
+## 2023-04-04 (#9, #10, #11, #12)
+
+### Added
+
+- `x-sap-root-entity` on Schema Object. Boolean flag indicating that the annotated schema is a root entity (a globally addressable business object root).
+
+### Fixed
+
+- Corrected examples in the OpenAPI v2.0 schema documentation.
+- Removed incorrect DECFLOAT34 example from the type mapping.
+
+## 2023-02-28 (#4)
+
+### Changed
+
+- **Breaking**: removed lowercase enum values (`rest`, `soap`, `odata`, `odatav4`) from `x-sap-api-type`. Only uppercase values (`REST`, `SOAP`, `ODATA`, `ODATAV4`) are now valid.
+
+## 2023-02-24 (#3)
+
+### Added
+
+- `x-sap-precision` on Schema Object. Maximum number of significant decimal digits (integer ≥ 1).
+- `x-sap-scale` on Schema Object. Maximum number of decimal digits to the right of the decimal point (integer ≥ 0).
+
+## 2023-02-10
+
+### Added
+
+- `x-sap-odm-entity-name` on Schema Object. Name of the ODM entity concept the schema represents, used by consumers to find APIs exposing the same entity.
+- `x-sap-odm-oid` on Schema Object. Marks the annotated field as the ODM Object Identifier (OID) that uniquely identifies an ODM root entity across a customer landscape.
+
+## 2022-11-29 — Initial release
+
+### Added
+
+- OpenAPI v2.0 and v3.0 SAP extension schemas with generator toolchain (`src/generate-specs.ts`).
+- Root-level extensions (OpenAPI Object):
+  - `x-sap-compliance-level` — expected compliance level (`sap:base:v1`, `sap:core:v1`, `sap:core:v2`).
+  - `x-sap-shortText` — short display description of the API.
+  - `x-sap-software-min-version` — minimum required software version.
+  - `x-sap-api-type` — API protocol type (`REST`, `SOAP`, `ODATA`, `ODATAV4`).
+  - `x-sap-ext-overview` — stakeholder-specific metadata as name/values pairs.
+  - `x-sap-stateInfo` — API lifecycle state (`Beta`, `Active`, `Deprecated`, `Decommissioned`) with optional deprecation and decommission dates and a successor URL.
+  - `x-sap-direction` — API traffic direction (`inbound`, `outbound`, `mixed`).
+  - `x-sap-extensible` — extensibility metadata with `supported` (`no`, `manual`, `automatic`) and optional `description`.
+- OAuth flow URL relaxation: `authorizationUrl`, `tokenUrl`, and `refreshUrl` made non-required to accommodate SAP-specific flows.

sap-extensions/extensions.json

@@ -54,6 +54,28 @@
         }
       }
     },
+    {
+      "paths": [
+        "definitions.schema.properties",
+        "definitions.Schema.properties",
+        "definitions.operation.properties",
+        "definitions.Operation.properties",
+        "definitions.Parameter.properties",
+        "definitions.bodyParameter.properties",
+        "definitions.headerParameterSubSchema.properties",
+        "definitions.queryParameterSubSchema.properties",
+        "definitions.formDataParameterSubSchema.properties",
+        "definitions.pathParameterSubSchema.properties",
+        "definitions.info.properties",
+        "definitions.Info.properties"
+      ],
+      "properties": {
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
+        }
+      }
+    },
     {
       "paths": [
         "properties"

sap-schemas/v2.0/README.md

@@ -689,3 +689,96 @@ Constraints:
 
 - OPTIONAL
 - Default: `true`
+
+## AI extensions
+
+### `x-sap-ai-hint`
+
+- Type: `String` (Markdown recommended, plain text accepted)
+- Used at:
+  - [Info Object](https://spec.openapis.org/oas/v2.0#info-object)
+  - [Operation Object](https://spec.openapis.org/oas/v2.0#operation-object)
+  - [Parameter Object](https://spec.openapis.org/oas/v2.0#parameter-object) (body, query, header, path, and formData parameters)
+  - [Schema Object](https://spec.openapis.org/oas/v2.0#schema-object)
+- Description: Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Intentionally kept separate from human-readable `description` fields so that end-user-facing documentation and AI-targeted guidance can evolve independently.
+
+`x-sap-ai-hint` serves two roles depending on whether a `description` is already present:
+
+- **Complementary** — when a `description` exists for human readers, use `x-sap-ai-hint` to add AI-specific context that would clutter or be out of place in the human-facing description: routing guidance, preconditions, side effects, related operations, or disambiguation against similar elements.
+- **Standalone** — when no `description` is present (common for internal or machine-generated APIs), `x-sap-ai-hint` can serve as the sole description, written entirely for AI consumption rather than end-user documentation.
+
+In both cases, the content should be optimized for an AI agent that needs to decide _whether_ and _how_ to use the element — not for a developer reading reference docs.
+
+Constraints:
+
+- OPTIONAL
+- MAY contain markdown
+- Markdown SHOULD be used for structured content, e.g. lists, options, tabular data, etc.
+- Maximum length: 4000 characters
+
+### Best practices
+
+Unlike human-facing descriptions, `x-sap-ai-hint` can be explicit about pre- and post-conditions, invocation patterns, and semantic context that would clutter end-user documentation. Focus on what an AI agent needs to decide _whether_ and _how_ to use the element.
+
+Some useful things to include, depending on the element:
+
+- **Business context** — what business activity this covers, and when to prefer it over similar operations or schemas
+- **Preconditions** — required permissions, scopes, or system state the agent should verify first
+- **Side effects** — what gets created, modified, or triggered as a result
+- **Common patterns** — typical workflows or call sequences this element participates in
+- **Format and value constraints** — coding standards (ISO, internal enums, picklists), indexed vs. non-indexed fields, what happens on constraint violations
+- **Disambiguation** — when a field name is misleading or overlaps with something similar elsewhere
+- **When NOT to use** — especially useful when multiple operations or schemas cover overlapping domains; stating the boundary explicitly helps agents route correctly
+
+Plain text is accepted. Where content is structured (sections, conditions, lists), it SHOULD use **lightweight Markdown** — well-structured content enables AI systems to more reliably extract meaning, identify conditions, and route decisions:
+
+#### Key principles
+
+- **Structure over prose** — break information into clearly separated units rather than long paragraphs.
+- **Semantic labeling** — use consistent, explicit labels to identify intent (e.g., **Precondition**, **Side effects**, **Business context**, **When NOT to use**). This improves machine interpretability beyond visual formatting.
+- **Consistency across APIs** — reuse the same labels and structure patterns across similar operations and schemas. Predictability matters more than stylistic variation.
+- **Lightweight Markdown only** — prefer bullets, bold labels, and `inline code` for fields and identifiers. Avoid tables and deep nesting, which may reduce parsing reliability.
+- **Keep content atomic and scannable** — one idea per bullet or line to support extraction and reasoning.
+
+Example:
+
+```yaml
+info:
+  title: Sales Order API
+  version: 1.0.0
+  x-sap-ai-hint:
+    "Manages the order-to-cash lifecycle. Start with GET /sales-orders to
+    find orders, then use the returned orderId for all downstream operations. All amounts
+    use ISO 4217 currency codes and ISO 8601 dates throughout."
+
+paths:
+  /sales-orders:
+    get:
+      summary: List Sales Orders
+      description: Returns a paginated list of sales order headers.
+      # description is for human readers; x-sap-ai-hint adds agent-specific context
+      x-sap-ai-hint:
+        "Use to search or filter orders by customer, date range, or status.
+        Returns headers only — fetch line items via GET /sales-orders/{orderId}/items.
+        Requires read_orders scope. Not suitable for bulk exports; use the reporting
+        API for large data volumes."
+      parameters:
+        - name: filter
+          in: query
+          x-sap-ai-hint:
+            "Comma-separated field=value pairs, e.g. customerId=C1001,status=2.
+            Only indexed fields (customerId, createdAt, status) are filterable — other
+            fields return 400."
+    post:
+      summary: Create Sales Order
+      x-sap-ai-hint:
+        "Creates a draft sales order. The customer account must exist and
+        be active (verify via GET /customers/{id}). Returns the new orderId. Does not
+        reserve inventory or trigger fulfillment — call POST /sales-orders/{orderId}/submit
+        to initiate the fulfillment workflow."
+
+definitions:
+  CurrencyCode:
+    type: string
+    x-sap-ai-hint: "ISO 4217 three-letter code (e.g. USD, EUR). Do not use currency symbols."
+```

sap-schemas/v2.0/schema.json

@@ -310,6 +310,10 @@
         },
         "license": {
           "$ref": "#/definitions/license"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       }
     },
@@ -486,6 +490,10 @@
         "security": {
           "$ref": "#/definitions/security"
         },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
+        },
         "x-sap-operation-intent": {
           "type": "string",
           "enum": [
@@ -744,6 +752,10 @@
         },
         "schema": {
           "$ref": "#/definitions/schema"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       },
       "additionalProperties": false
@@ -825,6 +837,10 @@
         },
         "multipleOf": {
           "$ref": "#/definitions/multipleOf"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       }
     },
@@ -910,6 +926,10 @@
         },
         "multipleOf": {
           "$ref": "#/definitions/multipleOf"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       }
     },
@@ -995,6 +1015,10 @@
         },
         "multipleOf": {
           "$ref": "#/definitions/multipleOf"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       }
     },
@@ -1076,6 +1100,10 @@
         },
         "multipleOf": {
           "$ref": "#/definitions/multipleOf"
+        },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
         }
       }
     },
@@ -1338,6 +1366,10 @@
           "default": true,
           "description": "Property contains potentially sensitive personal data. Sensitive personal data is a category of personal data that needs special handling. The determination which personal data is sensitive may differ for different legal areas or industries. Examples of sensitive personal data: 1. Special categories of personal data, such as data revealing racial or ethnic origin, political opinions, religious or philosophical beliefs, trade union membership, genetic data, biometric data, data concerning health or sex life or sexual orientation. 2. Personal data subject to professional secrecy. 3. Personal data relating to criminal or administrative offenses. 4. Personal data concerning insurances and bank or credit card accounts."
         },
+        "x-sap-ai-hint": {
+          "type": "string",
+          "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently."
+        },
         "x-sap-oauth-body-parameter": {
           "$ref": "#/definitions/schema",
           "description": "To describe additional authentication parameters to be passed during oauth authentication flow."