diff --git a/.gitignore b/.gitignore index 76add87..7bb2694 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ node_modules -dist \ No newline at end of file +dist +.claude/ +.DS_Store \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..519afaa --- /dev/null +++ b/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 `:apiResource::`. + +## 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. diff --git a/sap-extensions/extensions.json b/sap-extensions/extensions.json index de50544..8bac1c5 100644 --- a/sap-extensions/extensions.json +++ b/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" diff --git a/sap-schemas/v2.0/README.md b/sap-schemas/v2.0/README.md index 872904e..78e2d27 100644 --- a/sap-schemas/v2.0/README.md +++ b/sap-schemas/v2.0/README.md @@ -689,3 +689,92 @@ 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 +- Maximum length: 4000 characters + +### Best practices + +> See also: [AI-Ready APIs guideline](https://pages.github.tools.sap/CPA/api-guidelines/common-guidelines/ai-ready-apis/) for the broader context on AI-optimized descriptions. + +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." +``` diff --git a/sap-schemas/v3.0/README.md b/sap-schemas/v3.0/README.md index 556ced5..4b9ef4f 100644 --- a/sap-schemas/v3.0/README.md +++ b/sap-schemas/v3.0/README.md @@ -662,3 +662,89 @@ 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/v3.0.3#info-object) + - [Operation Object](https://spec.openapis.org/oas/v3.0.3#operation-object) + - [Parameter Object](https://spec.openapis.org/oas/v3.0.3#parameter-object) + - [Schema Object](https://spec.openapis.org/oas/v3.0.3#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 + +### Best practices + +> See also: [AI-Ready APIs guideline](https://pages.github.tools.sap/CPA/api-guidelines/common-guidelines/ai-ready-apis/) for the broader context on AI-optimized descriptions. + +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 + +Structure `x-sap-ai-hint` values using **lightweight, semantically structured Markdown** — well-structured content enables AI systems to more reliably extract meaning, identify conditions, and route decisions: + +- **Use consistent labels** — mirror the categories above (e.g., **Precondition:**, **Side effects:**, **When NOT to use:**) so AI systems can extract meaning beyond visual formatting. +- **Keep content atomic** — one idea per bullet or line; avoid long prose paragraphs. +- **Reuse patterns across APIs** — predictability across operations matters more than stylistic variation. +- **Lightweight Markdown only** — bullets, bold labels, `inline code` for fields and identifiers. Avoid tables and deep nesting. + +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: "OData-style filter expression, e.g. customerId eq 'C1001' and + status eq 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." + +components: + schemas: + CurrencyCode: + type: string + x-sap-ai-hint: "ISO 4217 three-letter code (e.g. USD, EUR). Do not use currency symbols." +```