Skip to content
Draft
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA

## [unreleased]

### Added

- Added `namespaces` property to ORD Configuration to support namespace document references
- This allows ORD providers to specify where namespace definitions (as used in ORD IDs) can be retrieved

## [1.14.0]

### Added
Expand Down
10 changes: 10 additions & 0 deletions examples/configuration/configuration-1.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
]
}
],
"namespaces": [
{
"url": "/namespaces.json",
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

TODO: We should add this as an example in the /examples folder, too.
We can do this along with then defining the JSON Schema for it.

"accessStrategies": [
{
"type": "open"
}
]
}
],
"capabilities": {
"selector": true
}
Expand Down
243 changes: 243 additions & 0 deletions examples/documents/document-lifecycle.json
Comment thread
Fannon marked this conversation as resolved.
Outdated
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
{
"$schema": "https://open-resource-discovery.github.io/specification/spec-v1/interfaces/Document.schema.json",
"openResourceDiscovery": "1.12",
"description": "This is an example ORD document which is unprotected and openly accessible.",
"perspective": "system-version",
"policyLevels": ["sap:core:v1"],
"describedSystemInstance": {
"baseUrl": "https://ord-reference-application.cfapps.sap.hana.ondemand.com"
},
"policyLevel": "sap:core:v1",
"apiResources": [
{
"ordId": "sap.xref:apiResource:astronomyLifecycle:v0",
"title": "Astronomy API",
"shortDescription": "The Astronomy API allows you to discover...",
"description": "A longer description of this API with **markdown** \n## headers\n etc...",
"version": "0.3.3",
"lastUpdate": "2023-02-03T06:44:10Z",
"visibility": "public",
"releaseStatus": "sunset",
"deprecationDate": "2020-02-03T15:47:04+00:00",
"sunsetDate": "2023-02-03T06:44:10Z",
"successors": ["sap.xref:apiResource:astronomyLifecycle:v1", "sap.xref:apiResource:astronomyLifecycle:v2"],
"partOfPackage": "sap.xref:package:ord-reference-app-apis-lifecycle:v1",
"partOfConsumptionBundles": [
{
"ordId": "sap.xref:consumptionBundle:noAuth:v1"
}
],
"apiProtocol": "rest",
"apiResourceLinks": [
{
"type": "api-documentation",
"url": "/swagger-ui.html?urls.primaryName=Astronomy%20V1%20API"
}
],
"resourceDefinitions": [
{
"type": "openapi-v3",
"mediaType": "application/json",
"url": "../sap.xref_apiResource_astronomy_v1/openapi-v3.json",
"accessStrategies": [
{
"type": "open"
}
]
}
],
"entryPoints": ["/astronomy/v1"],
"extensible": {
"supported": "no"
},
"exposedEntityTypes": [
{
"ordId": "sap.xref:entityType:Constellation:v1"
}
]
},
{
"ordId": "sap.xref:apiResource:astronomyLifecycle:v1",
"title": "Astronomy API (Successor Test)",
"shortDescription": "The Astronomy API allows you to discover...",
"description": "A longer description of this API with **markdown** \n## headers\n etc...",
"version": "1.0.3",
"lastUpdate": "2023-02-03T06:44:10Z",
"visibility": "public",
"releaseStatus": "deprecated",
"deprecationDate": "2023-02-03T15:47:04+00:00",
"sunsetDate": "2026-01-08T15:47:04+00:00",
"successors": ["sap.xref:apiResource:astronomyLifecycle:v2"],
"partOfPackage": "sap.xref:package:ord-reference-app-apis-lifecycle:v1",
"partOfConsumptionBundles": [
{
"ordId": "sap.xref:consumptionBundle:noAuth:v1"
}
],
"apiProtocol": "rest",
"apiResourceLinks": [
{
"type": "api-documentation",
"url": "/swagger-ui.html?urls.primaryName=Astronomy%20V1%20API"
}
],
"compatibleWith": [
{
"ordId": "sap.xref:apiResource:astronomySP:v1",
"maxVersion": "1.0"
}
],
"resourceDefinitions": [
{
"type": "openapi-v3",
"mediaType": "application/json",
"url": "../sap.xref_apiResource_astronomy_v1/openapi-v3.json",
"accessStrategies": [
{
"type": "open"
}
]
}
],
"entryPoints": ["/astronomy/v1"],
"extensible": {
"supported": "no"
},
"entityTypeMappings": [
{
"entityTypeTargets": [
{
"ordId": "sap.xref:entityType:Constellation:v1"
}
]
}
]
},
{
"ordId": "sap.xref:apiResource:astronomyLifecycle:v2",
"title": "Astronomy API (most recent)",
"shortDescription": "The Astronomy API allows you to discover...",
"description": "A longer description of this API with **markdown** \n## headers\n etc...",
"version": "2.0.5",
"lastUpdate": "2023-02-03T06:44:10Z",
"visibility": "public",
"releaseStatus": "active",
"partOfPackage": "sap.xref:package:ord-reference-app-apis-lifecycle:v1",
"partOfConsumptionBundles": [
{
"ordId": "sap.xref:consumptionBundle:noAuth:v1"
}
],
"apiProtocol": "rest",
"apiResourceLinks": [
{
"type": "api-documentation",
"url": "/swagger-ui.html?urls.primaryName=Astronomy%20V1%20API"
}
],
"compatibleWith": [
{
"ordId": "sap.xref:apiResource:astronomySP:v1",
"maxVersion": "1.0"
}
],
"resourceDefinitions": [
{
"type": "openapi-v3",
"mediaType": "application/json",
"url": "../sap.xref_apiResource_astronomy_v1/openapi-v3.json",
"accessStrategies": [
{
"type": "open"
}
]
}
],
"entryPoints": ["/astronomy/v1"],
"extensible": {
"supported": "no"
},
"entityTypeMappings": [
{
"entityTypeTargets": [
{
"ordId": "sap.xref:entityType:Constellation:v1"
}
]
}
]
},
{
"ordId": "sap.xref:apiResource:astronomySPI:v1",
"title": "Astronomy API (SPI)",
"shortDescription": "Abstract Contract for Astronomy API",
"description": "A longer description of this API with **markdown** \n## headers\n etc...",
"version": "1.0.3",
"lastUpdate": "2023-02-03T06:44:10Z",
"visibility": "public",
"releaseStatus": "active",
"partOfPackage": "sap.xref:package:ord-reference-app-apis-lifecycle:v1",
"partOfConsumptionBundles": [
{
"ordId": "sap.xref:consumptionBundle:noAuth:v1"
}
],
"apiProtocol": "rest",
"apiResourceLinks": [
{
"type": "api-documentation",
"url": "/swagger-ui.html?urls.primaryName=Astronomy%20V1%20API"
}
],
"compatibleWith": [
{
"ordId": "sap.s4com:apiResource:SomeSharedContract:v1",
"maxVersion": "1.0"
}
],
"resourceDefinitions": [
{
"type": "openapi-v3",
"mediaType": "application/json",
"url": "../sap.xref_apiResource_astronomy_v1/openapi-v3.json",
"accessStrategies": [
{
"type": "open"
}
]
}
],
"entryPoints": ["/astronomy/v1"],
"extensible": {
"supported": "no"
},
"entityTypeMappings": [
{
"entityTypeTargets": [
{
"ordId": "sap.xref:entityType:Constellation:v1"
}
]
}
]
}
],
"packages": [
{
"ordId": "sap.xref:package:ord-reference-app-apis-lifecycle:v1",
"title": "ORD Reference Application APIs (Deprecation Test)",
"shortDescription": "This is a reference application for the Open Resource Discovery protocol",
"description": "This reference application demonstrates how Open Resource Discovery (ORD) can be implemented, demonstrating different resources and discovery aspects",
"version": "1.0.0",
"partOfProducts": ["sap.xref:product:ord-reference-app:"],
"vendor": "sap:vendor:SAP:",
"tags": ["reference application"]
}
],
"tombstones": [
{
"ordId": "sap.xref:apiResource:astronomyLifecycle:v0",
"removalDate": "2021-03-12T06:44:10Z"
}
]
}
52 changes: 52 additions & 0 deletions spec/v1/Configuration.schema.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,15 @@ definitions:
items:
"$ref": "#/definitions/V1DocumentDescription"

namespaces:
type: array
description: |-
List of namespace documents that can be retrieved.

TODO: Link to JSON Schema that defines the namespace JSON format.
items:
"$ref": "#/definitions/V1NamespaceDescription"

capabilities:
"$ref": "#/definitions/V1Capabilities"

Expand Down Expand Up @@ -180,6 +189,49 @@ definitions:
- url
- accessStrategies

############################################################################################################

V1NamespaceDescription:
type: object
title: Ord V1 Namespace Description
description: |-
Describes a namespace document that is available for retrieval.
x-ums-type: "ignore"
properties:
url:
type: string
format: uri-reference
description: |-
URL or relative URL to the namespace document.

It is RECOMMENDED to provide a relative URL (to `baseUrl`).
If a `baseUrl` is given, the relative URLs will be resolved with it.

If the URL is not relative to the system providing this information or no well-known URI is used,
either the baseUrl or a full URL to the document MUST be provided.
examples:
- "/namespaces.json"
- "../../namespaces.json"
- "https://example.com/namespaces.json"

accessStrategies:
type: array
description: |-
List of supported access strategies for retrieving the namespace document from the ORD provider.

An ORD Consumer/ORD Aggregator MAY freely choose any of the listed strategies.

items:
$ref: "#/definitions/AccessStrategy"
minItems: 1

additionalProperties: false
required:
- url
- accessStrategies

############################################################################################################

#/definitions/V1Capabilities"
V1Capabilities:
type: object
Expand Down
29 changes: 29 additions & 0 deletions src/generated/spec/v1/types/Configuration.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ export interface OrdV1Support {
* For more details how to implement this correctly, please refer to the [ORD configuration endpoint](../index.md#ord-configuration-endpoint) section and the [considerations on the granularity of ORD documents](../index.md#considerations-on-the-granularity-of-ord-documents).
*/
documents?: OrdV1DocumentDescription[];
/**
* List of namespace documents that can be retrieved.
*
* TODO: Link to JSON Schema that defines the namespace JSON format.
*/
namespaces?: OrdV1NamespaceDescription[];
capabilities?: OrdV1Capabilities;
}
/**
Expand Down Expand Up @@ -111,6 +117,29 @@ export interface OrdV1DocumentAccessStrategy {
*/
customDescription?: string;
}
/**
* Describes a namespace document that is available for retrieval.
*/
export interface OrdV1NamespaceDescription {
/**
* URL or relative URL to the namespace document.
*
* It is RECOMMENDED to provide a relative URL (to `baseUrl`).
* If a `baseUrl` is given, the relative URLs will be resolved with it.
*
* If the URL is not relative to the system providing this information or no well-known URI is used,
* either the baseUrl or a full URL to the document MUST be provided.
*/
url: string;
/**
* List of supported access strategies for retrieving the namespace document from the ORD provider.
*
* An ORD Consumer/ORD Aggregator MAY freely choose any of the listed strategies.
*
* @minItems 1
*/
accessStrategies: [OrdV1DocumentAccessStrategy, ...OrdV1DocumentAccessStrategy[]];
}
/**
* List of capabilities that are supported by the ORD provider.
*/
Expand Down