diff --git a/CHANGELOG.md b/CHANGELOG.md index d5a6d800..15ec44b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA ### Added - Added missing property `$id` to annotation extension schemas +- ADDED: Added `@ORD` annotation vocabulary + - Added `@ORD.ordIds` to correlate CSN Service and Entity to its ORD API Resource, Event Resource and Entity Type equivalents. - Added clarification that `key: true` also implies `notNull: true` ## [1.0.3] diff --git a/spec-toolkit.config.json b/spec-toolkit.config.json index e8943d8b..ce171864 100644 --- a/spec-toolkit.config.json +++ b/spec-toolkit.config.json @@ -102,6 +102,19 @@ "description": "@ODM for One Domain Model (ODM) related annotations." } }, + { + "type": "specExtension", + "id": "ord", + "sourceFilePath": "./spec/v1/annotations/ord.yaml", + "sourceIntroFilePath": "./spec/v1/annotations/ord.md", + "targetDocumentId": "csn-interop-effective", + "targetLink": "../spec-v1/csn-interop-effective", + "mdFrontmatter": { + "title": "@ORD", + "sidebar_position": 9, + "description": "@ORD for Open Resource Discovery related annotations." + } + }, { "type": "specExtension", "id": "personal-data", @@ -110,7 +123,7 @@ "targetDocumentId": "csn-interop-effective", "mdFrontmatter": { "title": "@PersonalData", - "sidebar_position": 9, + "sidebar_position": 10, "description": "@PersonalData to annotate DPP relevant information." } }, @@ -122,7 +135,7 @@ "targetDocumentId": "csn-interop-effective", "mdFrontmatter": { "title": "@Semantics", - "sidebar_position": 10, + "sidebar_position": 11, "description": "@Semantics annotations." } } diff --git a/spec/v1/annotations/ord.md b/spec/v1/annotations/ord.md new file mode 100644 index 00000000..ccb89457 --- /dev/null +++ b/spec/v1/annotations/ord.md @@ -0,0 +1,14 @@ +> BETA This annotation is beta and should be reviewed for completion and correctness. + +## Introduction + +[Open Resource Discovery](https://sap.github.io/open-resource-discovery/) (ORD) is a complementary standard to CSN Interop. +It's purpose is to provide a decentralized protocol for metadata publishing and discovery of applications and services. +From ORD perspective, CSN Interop is a possible resource definition format that can be attached to API and Event resources. + +On the ORD level, more high-level context can be found and expressed, that is shared across different protocols and standards. +Also it covers (global) taxonomy and relationships between high-level concepts. + +With this annotations it's possible to connect the CSN Interop concepts back to the high-level ORD concepts. + +> 🔗 Visit the public [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) page. diff --git a/spec/v1/annotations/ord.yaml b/spec/v1/annotations/ord.yaml new file mode 100644 index 00000000..b5988c67 --- /dev/null +++ b/spec/v1/annotations/ord.yaml @@ -0,0 +1,20 @@ +$schema: "http://json-schema.org/draft-07/schema#" +title: "ORD" +x-extension: + targetDocument: "./spec/v1/CSN-Interop-Effective.schema.yaml" + targetLink: "../spec-v1/csn-interop-effective" + +definitions: + "@ORD.ordIds": + type: array + items: + type: string + pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(apiResource|eventResource|entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)$ + description: |- + The [ORD ID](https://sap.github.io/open-resource-discovery/spec-v1#ord-id) of the CSN definition. + It can be an array, because a single CDS [Service](../spec-v1/csn-interop-effective#i18n) can be exposed via multiple concrete API or Event protocols. + examples: + - ["sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v1"] + x-extension-targets: + - "Entity" + - "Service" diff --git a/spec/v1/examples/airline.json b/spec/v1/examples/airline.json index 34c180a3..6720affd 100644 --- a/spec/v1/examples/airline.json +++ b/spec/v1/examples/airline.json @@ -15,7 +15,8 @@ "definitions": { "AirlineService": { "kind": "service", - "doc": "This is describing the service that exposes the CDS entities through an API." + "doc": "This is describing the service that exposes the CDS entities through an API.", + "@ORD.ordIds": ["sap.foo:apiResource:AirlineDeltaShare:v1"] }, "AirlineService.Airline": { "kind": "entity", @@ -24,6 +25,7 @@ "@ObjectModel.modelingPattern": { "#": "ANALYTICAL_DIMENSION" }, + "@ORD.ordIds": ["sap.foo:entityType:Airline:v1"], "elements": { "AirlineID": { "@EndUserText.label": "Airline",