Skip to content

Hide properties and entities that have been deprecated for 2-3 releases #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Fannon wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Hide properties and entities that have been deprecated for 2-3 releases #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
744a319
Hide properties and entities that have been deprecated for 3 releases
Fannon Feb 26, 2026
24af399
Also hide systemInstanceAware
Fannon Feb 26, 2026
de061d5
Merge branch 'main' into hide-deprecated-entities-and-properties
Fannon Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,18 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA

## [unreleased]

### Changed

- Hidden deprecated properties from documentation using `x-hide: true`:
Copy link
Copy Markdown
Member

@maiargu maiargu Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think changes done to the UI by appling x-hide don't need to be added to the changelog file, the exposed npm package JSON schema did not change at all for consumers

Copy link
Copy Markdown
Member Author

@Fannon Fannon Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd still prefer to keep it in, because many read the documentation as a page and the changelog might at least give a hint why some things have now disappeared. Better over-communicate here :) But yes, for JSON Schema / NPM consumption, it's not changing anything

- `policyLevel` and `customPolicyLevel` (deprecated since v1.9.9) - use `policyLevels` instead
- `entityTypeMappings` (deprecated since v1.11.0) - use `exposedEntityTypes` instead
- `systemInstanceAware` (deprecated since v1.12.0) - use `perspective` instead
- Related definitions: `EntityTypeMapping`, `ApiModelSelectorOData`, `ApiModelSelectorJsonPointer`, `EntityTypeOrdIdTarget`, `EntityTypeCorrelationIdTarget`
- Updated documentation to reference current concepts instead of deprecated ones:
- Changed `policyLevel`/`customPolicyLevel` references to `policyLevels` in spec index
- Changed `systemInstanceAware` references to `perspective` in access strategy docs and FAQ
- Removed deprecated property usage from example files (`systemInstanceAware`, `policyLevel`, `customPolicyLevel`)

## [1.14.1]

### Changed
Expand Down
2 changes: 1 addition & 1 deletion docs/help/faq/adopt-ord-as-provider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Now becomes a necessity to implement ORD as a REST API, where the GET operations
The response (of at least some requests) will depend on tenant context, customizations and extensions.

In practice it's more realistic that such an implementation will be a mix between static and dynamic metadata.
Since static metadata is much cheaper and easier to provide, it's recommended to only use run-time dynamic generation of metadata where necessary. In ORD it's possible to indicate this on a per resource basis via the `systemInstanceAware` attribute see [definition](../../spec-v1/index.md#system-instance-aware).
Since static metadata is much cheaper and easier to provide, it's recommended to only use run-time dynamic generation of metadata where necessary. In ORD it's possible to split metadata into separate ORD documents with different [perspectives](../../spec-v1/concepts/perspectives.md) (e.g. `system-version` for static and `system-instance` for dynamic metadata).

> 🚧 The [ORD Reference Application](https://ord-reference-application.cfapps.sap.hana.ondemand.com/) showcases a mix between static and dynamic metadata. The source-code for it is yet to be made public, though.

Expand Down
2 changes: 1 addition & 1 deletion docs/spec-extensions/access-strategies/basic-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,4 @@ Global-Tenant-Id: c6c80b52-ecc1-47f8-9303-0d55fb67fd41
### General Remarks

> ℹ If the metadata is not different across tenants (system-instance-unaware), the response is static and the same across tenants.
> In this case, this should be indicated via `systemInstanceAware`: `false` to avoid unnecessary requests for each tenant.
> In this case, the ORD document should use `perspective`: `system-version` instead of `system-instance` to avoid unnecessary requests for each tenant.
2 changes: 1 addition & 1 deletion docs/spec-extensions/access-strategies/open.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,4 @@ Global-Tenant-Id: c6c80b52-ecc1-47f8-9303-0d55fb67fd41
### General Remarks

> ℹ If the metadata is not different across tenants (system-instance-unaware), the response is static and the same across tenants.
> In this case, this should be indicated via `systemInstanceAware`: `false` to avoid unnecessary requests for each tenant.
> In this case, the ORD document should use `perspective`: `system-version` instead of `system-instance` to avoid unnecessary requests for each tenant.
4 changes: 2 additions & 2 deletions docs/spec-v1/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,7 @@ Which attributes support information reuse and how it works is described in the
##### Document Level Inheritance

Some ORD information is described on the document root level and applies to all information that the ORD Document contains.
In some cases (like `policyLevel`), it is also possible to override the values locally.
In some cases (like `policyLevels`), it is also possible to override the values locally.

##### Package Level Inheritance

Expand Down Expand Up @@ -521,7 +521,7 @@ The following rules need to be implemented by ORD aggregators:
- This ensures that consumers can rely on `lastUpdate` to be always available and to understand if a change happened, even if the ORD Provider did not update it at the source
- Ideally this situation doesn't happen and the ORD Providers update `lastUpdate`. Then the date can also better reflect the time when the change happened, not when it was detected.
- The aggregator MUST apply all defined inheritances from root document properties to all the ORD information that it contains.
- `policyLevel` (and the corresponding `customPolicyLevel`) MUST be inherited to the resource / Package level, with the latter taking precedence.
- `policyLevels` MUST be inherited to the resource / Package level, with the latter taking precedence.
- The aggregator MUST apply all defined inheritances from `Package` properties to all the ORD resources that it contains.
- `vendor`, `partOfProducts`, `tags`, `countries`, `industry`, and `lineOfBusiness` MUST be merged without duplicates.
- `labels` MUST be merged without duplicated values.
Expand Down
1 change: 0 additions & 1 deletion examples/documents/document-1.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,6 @@
"lastUpdate": "2022-12-19T15:47:04+00:00",
"visibility": "public",
"releaseStatus": "active",
"systemInstanceAware": false,
"minSystemVersion": "2024.4.0",
"policyLevels": ["sap.foo:custom:v1"],
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
Expand Down
3 changes: 1 addition & 2 deletions examples/documents/document-data-product.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,8 +191,7 @@
"Scope Items": [
"[Basic Bank Account Management (BFA)](https://rapid.sap.com/bp/#/scopeitems/BFA \\\" Link To BP \\\")"
]
},
"systemInstanceAware": true
}
},
{
"ordId": "sap.xref:dataProduct:AbstractCustomer:v1",
Expand Down
3 changes: 0 additions & 3 deletions examples/documents/document-special-protocols.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@
"lastUpdate": "2022-12-19T15:47:04+00:00",
"visibility": "internal",
"releaseStatus": "active",
"systemInstanceAware": true,
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
"apiProtocol": "sap-rfc",
"partOfConsumptionBundles": [
Expand Down Expand Up @@ -64,7 +63,6 @@
"lastUpdate": "2022-12-19T15:47:04+00:00",
"visibility": "internal",
"releaseStatus": "active",
"systemInstanceAware": true,
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
"apiProtocol": "websocket",
"direction": "mixed",
Expand All @@ -87,7 +85,6 @@
"lastUpdate": "2022-12-19T15:47:04+00:00",
"visibility": "internal",
"releaseStatus": "active",
"systemInstanceAware": true,
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
"partOfConsumptionBundles": [
{
Expand Down
6 changes: 2 additions & 4 deletions examples/implementation/nginx-no-auth/metadata/document-1.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"openResourceDiscovery": "1.12",
"openResourceDiscovery": "1.14",
"policyLevels": ["sap:core:v1"],
"apiResources": [
{
Expand All @@ -11,9 +11,7 @@
"lastUpdate": "2022-12-19T15:47:04+00:00",
"visibility": "public",
"releaseStatus": "active",
"systemInstanceAware": false,
"policyLevel": "custom",
"customPolicyLevel": "sap.foo:custom:v1",
"policyLevels": ["sap.foo:custom:v1"],
"partOfPackage": "sap.foo:package:ord-reference-app:v1",
"partOfConsumptionBundles": [
{
Expand Down
1 change: 1 addition & 0 deletions spec/v1/Configuration.schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ definitions:

systemInstanceAware:
type: boolean
x-hide: true
description: |-
Whether the information in the ORD document is **system-instance-aware**.
This is the case when the provided ORD document potentially differs between **system instances** (e.g. due to multi-tenancy, configuration or extensibility).
Expand Down
11 changes: 9 additions & 2 deletions spec/v1/Document.schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ properties:
Information on the [system version](../index.md#system-version) that this ORD document describes.
policyLevel: &policyLevel
type: string
x-hide: true
description: |
The [policy level](../../spec-extensions/policy-levels/) (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.
Expand All @@ -155,7 +156,6 @@ properties:
description: |-
No policy level chosen. Only the base rules on how to create correct ORD documents apply.
- const: custom
# TODO: Deprecate this?
description: |-
Custom policy level.
Further validation MAY be defined and implemented by the policy-level owner.
Expand All @@ -170,7 +170,7 @@ properties:

customPolicyLevel: &customPolicyLevel
type: string
# TODO: Deprecate this?
x-hide: true
description: |-
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.
Expand Down Expand Up @@ -1452,6 +1452,7 @@ definitions:

entityTypeMappings: &entityTypeMappings
type: array
x-hide: true
Copy link
Copy Markdown
Member

@swennemers swennemers Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure, if we can already hide it already. BAH is not yet supporting exposedEntityTypes, S/4 is still exposing it...

Copy link
Copy Markdown
Member Author

@Fannon Fannon Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but we would just hide it from documentation. For new adopters, we don't want them to implement / see this. Also it looks like there is now no consumer for it, except BAH using it to create the links (which would be simpler with exposedEntityTypes

Hiding this would greatly help cleaning things up, as it also removes some objects

Copy link
Copy Markdown
Member

@swennemers swennemers Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand, but the support for exposedEntityTypes is not given and we still want the links and we haven't updated all guidelines to use exposedEntityTypes, do we? So documentation is still needed until one can really use exposedEntityTypes.

Copy link
Copy Markdown
Member Author

@Fannon Fannon Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then let's push BAH to support it. And the guidelines should be updated already I guess.. we'd need to check

Copy link
Copy Markdown
Member Author

@Fannon Fannon Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@swennemers do you have strong objectsions? I would prefer to do this sooner than later, as it cleans up and reduces chances that deprecated features are used for new developments.

@maiargu - how easy would it be to support in spec-toolkit that we generate the markdown documentation twice, once with and once without hidden content? Is this something we should do from the beginning?

x-introduced-in-version: "1.6.0"
x-deprecated-in-version: "1.11.0"
x-deprecation-text: |-
Expand Down Expand Up @@ -1536,6 +1537,7 @@ definitions:

systemInstanceAware: &systemInstanceAware
type: boolean
x-hide: true
description: |-
Defines whether this ORD resource is **system-instance-aware**.
This is the case when the referenced resource definitions are potentially different between **system instances**.
Expand Down Expand Up @@ -4427,6 +4429,7 @@ definitions:
EntityTypeMapping:
title: Entity Type Mapping
type: object
x-hide: true
x-introduced-in-version: "1.6.0"
x-deprecated-in-version: "1.11.0"
x-deprecation-text: |-
Expand Down Expand Up @@ -4584,6 +4587,7 @@ definitions:
title: Api Model Selector (Odata)
x-introduced-in-version: "1.6.0"
x-deprecated-in-version: "1.11.0"
x-hide: true
x-deprecation-text: |-
Use the simplified `relatedEntityTypes` instead.

Expand Down Expand Up @@ -4625,6 +4629,7 @@ definitions:
title: Api Model Selector (Json Pointer)
x-introduced-in-version: "1.6.0"
x-deprecated-in-version: "1.11.0"
x-hide: true
x-deprecation-text: |-
Use the simplified `relatedEntityTypes` instead.

Expand Down Expand Up @@ -4706,6 +4711,7 @@ definitions:
title: Entity Type Target (ORD ID)
x-introduced-in-version: "1.6.0"
x-deprecated-in-version: "1.11.0"
x-hide: true
x-deprecation-text: |-
Use the simplified `relatedEntityTypes` instead.
x-ums-type: "custom"
Expand All @@ -4732,6 +4738,7 @@ definitions:
EntityTypeCorrelationIdTarget:
title: Entity Type Target (Correlation Id)
type: object
x-hide: true
description: |-
Define which entity type is the target of an entity type mapping

Expand Down
Loading