diff --git a/CHANGELOG.md b/CHANGELOG.md index 705afe8..6b63ee8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA - Allow apostrophe for plural proper nouns in Short Descriptions in Policy Level `sap:core:v1`, e.g. `partners'`. +### Changed + +- Removed constraint that `describedSystemInstance` MUST be same as system instance providing the ORD information + ## [1.9.8] ### Added diff --git a/docs/details/articles/data-product.md b/docs/details/articles/data-product.md index a15a8c3..a7479ad 100644 --- a/docs/details/articles/data-product.md +++ b/docs/details/articles/data-product.md @@ -4,9 +4,9 @@ description: A Data Product is a data set exposed for consumption outside the bo title: Data Product --- -# Data Product BETA +# Data Product -> 🚧 Please note that the [Data Products](../../spec-v1/interfaces/document#data-product) concept is currently in [Beta Status](#beta-status). +> 🚧 Please note that the [Data Products](../../spec-v1/interfaces/document#data-product) concept still has some missing and some beta properties. ## Definition @@ -35,7 +35,7 @@ The following aspects of the definition are essential: (1) [data](#data-aspect), * Above we say that Data Products are consumed via APIs, but to be precise, they are consumed via APIs or Events (we treat events as a special form of API). In this doc, we generally use the term APIs to include Events (it is just more readable than always saying "APIs and/or Events"). * There is a clear expectation that the APIs are described via [metadata](#metadata-aspect) for machine- and human-readable documentation. -* For Data Products only certain types of API Protocols and qualities (performant mass read) are adequate. +* For Data Products only certain types of API Protocols and qualities (performant mass read) are adequate. E.g. SAP uses [Delta Sharing](https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md), which we additionally describe with [CSN Interop](https://sap.github.io/csn-interop-specification/) for richer metadata. * Data Products are also expected to describe their data lineage. This is done via Data Product input ports, which are described in details as an ORD [Integration Dependency](../../spec-v1/interfaces/document#integration-dependency) ### Metadata Aspect @@ -76,13 +76,13 @@ Data Products are exposed by **Producers** so that they can be used by **Consume * Data Product Consumers are applications or services that access and use the data from Data Products. Consumers can be of various types and cover both transactional and analytical applications. An application that processes operational data can be as Data Product consumer, as can analytical products like SAP Datasphere and SAP Analytics Cloud (SAC). * The Data Product Directory ([ORD Aggregator](../../spec-v1/#ord-aggregator)) is used by Consumers to find and discover available Data Products. -## Beta Status +## Current Status -Please note that the Data Product concept is currently in BETA. +Please note that the Data Product concept still contains some BETA properties. This has the following implications -* The interface contract is potentially subject to changes, although we aim to avoid breaking changes if possible. +* The beta-level properties are potentially subject to changes, although we aim to avoid breaking changes if possible. * Many data product relevant attributes are currently **not explicitly defined** in the specification yet. * Some attributes should be handled via documentation, e.g. Service Level Agreements via [dataProductLinks](../../spec-v1/interfaces/document#data-product_dataproductlinks) of `type`: [`service-level-agreement`](../../spec-v1/interfaces/document#data-product-link_type) * Such attributes need to be defined through generic extensibility mechanisms like `labels` and `documentationLabels` or added as text to the documentation. diff --git a/docs/index.md b/docs/index.md index 6e8f2a6..0f0d336 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,8 +12,8 @@ sidebar_position: 0
Open Resource Discovery (ORD) is a protocol that **allows applications and services to self-describe their resources and capabilities** (e.g. ports and adapters). -Typically, ORD is used to describe [APIs](./spec-v1/interfaces/document#api-resource) and [Events](./spec-v1/interfaces/document#event-resource), but it also supports higher-level concepts like [Entity Types](./spec-v1/interfaces/document#entity-type) (Domain / Business Objects) and [Data Products](./details/articles/data-product.md). -With [Integration Dependencies](./spec-v1/interfaces/document#integration-dependency) the use of external resources can be stated, too. +ORD can describe [APIs](./spec-v1/interfaces/document#api-resource), [Events](./spec-v1/interfaces/document#event-resource) and higher-level concepts like [Entity Types](./spec-v1/interfaces/document#entity-type) (Domain / Business Objects) and [Data Products](./details/articles/data-product.md). +With [Integration Dependencies](./spec-v1/interfaces/document#integration-dependency) the use of external resources can be stated. In case that the standardized concepts or attributes are not sufficient, there are extensibility attributes and [Capabilities](./spec-v1/interfaces/document#capability). All of the described artifacts can share relationships, taxonomy and [grouping](./details/articles/grouping-and-bundling.md) concepts, enabling a **well connected metadata graph**. diff --git a/docs/spec-extensions/policy-levels/sap-core-v1.md b/docs/spec-extensions/policy-levels/sap-core-v1.md index 303117b..8f8e5ae 100644 --- a/docs/spec-extensions/policy-levels/sap-core-v1.md +++ b/docs/spec-extensions/policy-levels/sap-core-v1.md @@ -141,7 +141,6 @@ The following constraints apply in addition to the constraints defined in the [O - Packages MUST NOT be shared by multiple provider (source) systems - Packages MUST NOT contain mixed resource types. E.g., a Package must only contain either APIs or Events, but never both together. - Packages MUST NOT contain content of mixed `visibility` - - SAP Business Accelerator Hub publishing becomes slow if too much content is in a Package (> 100 resources). Consider creating smaller packages that are split around the aspect of what needs to be published in one transaction. - The vendor of a Package MUST be set and be equal to one of the allowed values: `sap:vendor:SAP:`, `customer:vendor:Customer:`. ### Consumption Bundle diff --git a/docs/spec-v1/interfaces/document.md b/docs/spec-v1/interfaces/document.md index 133277f..392901f 100644 --- a/docs/spec-v1/interfaces/document.md +++ b/docs/spec-v1/interfaces/document.md @@ -28,7 +28,7 @@ The constraints and considerations on [ORD Documents](../index.md#ord-document) |
$schema
OPTIONAL
|
string
|
Optional [URL](https://tools.ietf.org/html/rfc3986) to the Open Resource Discovery document schema (defined as a JSON Schema).
If provided, this enables code intelligence and validation in supported editors (like VSCode) and tools.
JSON Schema Format: `uri-reference`
Recommended Values:
| |
openResourceDiscovery
MANDATORY
|
string
|
Version of the Open Resource Discovery specification that is used to describe this document.
Allowed Values:
Example Values:
| |
description
OPTIONAL
|
string
|
Optional description of the ORD document itself.
Please note that this information is NOT further processed or considered by an ORD aggregator.

Notated in [CommonMark](https://spec.commonmark.org/) (Markdown).
Minimum Length: `1`
Example Values:
| -|
describedSystemInstance
OPTIONAL
|
[System Instance](#system-instance)
|
Information on the **system instance** that this ORD document describes.

This information is optional, but RECOMMENDED to add, as it makes the ORD document self contained.
The described system instance MUST be identical to the system instance that provides the ORD information.
| +|
describedSystemInstance
OPTIONAL
|
[System Instance](#system-instance)
|
Information on the **system instance** that this ORD document describes.

This information is optional, but RECOMMENDED to add, as it makes the ORD document self contained.
| |
policyLevel
RECOMMENDED
|
string
|
The [policy level](../../spec-extensions/access-strategies/) (aka. compliance level) that the described resources need to be compliant with.
Depending on the chosen policy level, additional expectations and validations rules will be applied.

The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.

Default Value: `"none"`
Allowed Values:
Introduced in Version: 1.3.0
Example Values:
| |
customPolicyLevel
OPTIONAL
|
string
|
If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.

MUST only be provided if `policyLevel` is set to `custom`.
MUST be a valid [Specification ID](../index.md#specification-id).
Regex Pattern: ^(\[a-z0-9\]+(?:\[.\]\[a-z0-9\]+)\*):(\[a-zA-Z0-9.\_\\-\]+):(v0\|v\[1-9\]\[0-9\]\*)$
Maximum Length: `255`
Example Values:
| |
apiResources
OPTIONAL
|
Array<[API Resource](#api-resource)>
|
Array of all API Resources that are described in this ORD document.
| @@ -561,7 +561,7 @@ For example, OpenAPI definition, OData Metadata, etc. | Property | Type | Description | | -------- | ---- | ----------- | -|
type
MANDATORY
|
string
|
Type of the API Resource Definition
If "custom" is chosen, a customType MUST be provided
Allowed Values:
Example Values:
| +|
type
MANDATORY
|
string
|
Type of the API Resource Definition
If "custom" is chosen, a customType MUST be provided
Allowed Values:
Example Values:
| |
customType
OPTIONAL
|
string
|
If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.

MUST be a valid [Specification ID](../index.md#specification-id).

MUST only be provided if `type` is set to `custom`.
Regex Pattern: ^(\[a-z0-9\]+(?:\[.\]\[a-z0-9\]+)\*):(\[a-zA-Z0-9.\_\\-\]+):v(\[0-9\]+)$
Maximum Length: `255`
Example Values:
| |
mediaType
MANDATORY
|
string
|
The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.
A consuming application can use this information to know which file format parser it needs to use.
For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON.

If no Media Type is registered for the referenced file,
`text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.

Allowed Values:
Example Values:
| |
url
MANDATORY
|
string
|
[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.

It is RECOMMENDED to provide a relative URL (to base URL).
JSON Schema Format: `uri-reference`
Example Values:
| diff --git a/static/spec-v1/interfaces/Configuration.xlsx b/static/spec-v1/interfaces/Configuration.xlsx index b2aa055..c2b47d0 100644 Binary files a/static/spec-v1/interfaces/Configuration.xlsx and b/static/spec-v1/interfaces/Configuration.xlsx differ diff --git a/static/spec-v1/interfaces/Document.annotated.schema.json b/static/spec-v1/interfaces/Document.annotated.schema.json index 1428724..39586dc 100644 --- a/static/spec-v1/interfaces/Document.annotated.schema.json +++ b/static/spec-v1/interfaces/Document.annotated.schema.json @@ -2926,7 +2926,7 @@ }, { "const": "sap-csn-interop-effective-v1", - "description": "CSN Interop Effective is a standardized and interoperable flavor of [CSN](https://cap.cloud.sap/docs/cds/csn)and a notation for compact representations of [CDS](https://cap.cloud.sap/docs/cds/) models.\nThe `mediaType` MUST be be set to `application/json`." + "description": "[CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable [CSN](https://cap.cloud.sap/docs/cds/csn) export, used to describe [CDS](https://cap.cloud.sap/docs/cds/) models.\nThe `mediaType` MUST be be set to `application/json`." }, { "const": "custom", @@ -5009,7 +5009,7 @@ }, "describedSystemInstance": { "$ref": "#/definitions/SystemInstance", - "description": "Information on the **system instance** that this ORD document describes.\n\nThis information is optional, but RECOMMENDED to add, as it makes the ORD document self contained.\nThe described system instance MUST be identical to the system instance that provides the ORD information." + "description": "Information on the **system instance** that this ORD document describes.\n\nThis information is optional, but RECOMMENDED to add, as it makes the ORD document self contained." }, "policyLevel": { "type": "string", diff --git a/static/spec-v1/interfaces/Document.schema.json b/static/spec-v1/interfaces/Document.schema.json index 7365e31..736ab3a 100644 --- a/static/spec-v1/interfaces/Document.schema.json +++ b/static/spec-v1/interfaces/Document.schema.json @@ -2754,7 +2754,7 @@ }, { "const": "sap-csn-interop-effective-v1", - "description": "CSN Interop Effective is a standardized and interoperable flavor of [CSN](https://cap.cloud.sap/docs/cds/csn)and a notation for compact representations of [CDS](https://cap.cloud.sap/docs/cds/) models.\nThe `mediaType` MUST be be set to `application/json`." + "description": "[CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable [CSN](https://cap.cloud.sap/docs/cds/csn) export, used to describe [CDS](https://cap.cloud.sap/docs/cds/) models.\nThe `mediaType` MUST be be set to `application/json`." }, { "const": "custom", @@ -4745,7 +4745,7 @@ }, "describedSystemInstance": { "$ref": "#/definitions/SystemInstance", - "description": "Information on the **system instance** that this ORD document describes.\n\nThis information is optional, but RECOMMENDED to add, as it makes the ORD document self contained.\nThe described system instance MUST be identical to the system instance that provides the ORD information." + "description": "Information on the **system instance** that this ORD document describes.\n\nThis information is optional, but RECOMMENDED to add, as it makes the ORD document self contained." }, "policyLevel": { "type": "string", diff --git a/static/spec-v1/interfaces/Document.xlsx b/static/spec-v1/interfaces/Document.xlsx index 82a01cd..10bdba0 100644 Binary files a/static/spec-v1/interfaces/Document.xlsx and b/static/spec-v1/interfaces/Document.xlsx differ