-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
copy ttl, class diagram and changelog to 2024-12 folder
- Loading branch information
1 parent
5ec7ef5
commit 852b63b
Showing
3 changed files
with
1,874 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| 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/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| # 2.2.0-dev | ||
|
|
||
| ## Ideas | ||
| - Add filters/triggers to Subscription information for server-side Notifications filtering | ||
| - Define API for stream data from sensor | ||
|
|
||
| # 2.1.0 | ||
|
|
||
|
|
||
|
|
||
| ## ONE Record API Specification | ||
|
|
||
| ### Changed | ||
|
|
||
| - Align documentation and ontology using always hasErrorDetail/ErrorDetail. | ||
| - Align LogisticsEvent filtering option to Kebab case | ||
| - Rename eventType into event-code for LogisticsEvent filtering option | ||
|
|
||
| ### Added | ||
|
|
||
| - Sort, limit and skip parameters in Get logistics events of a logistics object | ||
| - hasRevision and hasLastRevision for each logistics object body | ||
| - Verification request to signal error or anomalies in a logistics object | ||
|
|
||
| ### Removed | ||
|
|
||
| - overview of data classes and properties as CSV file to supporting documents, all information can be found in the ontology or in the data model page | ||
|
|
||
| ## ONE Record API Ontology | ||
|
|
||
| ### Changed | ||
|
|
||
| - in the AuditTrail, the AuditTrail#hasChangeRequest changes to AuditTrail#hasActionRequest | ||
|
|
||
|
|
||
| ### Added | ||
|
|
||
| - hasActionRequest object property | ||
| - hasVerificationRequest object property | ||
| - ChangeRequest has an additional opetion property hasVerificationRequest | ||
| - Verification class | ||
| - VerificationRequest class | ||
| - hasVerification object property | ||
|
|
||
| # 2.0.0 | ||
|
|
||
| --- | ||
|
|
||
| ## ONE Record API Specification | ||
|
|
||
| ### Changed | ||
|
|
||
| - restructured Introduction section | ||
| - use Logistics Object instead of its abbreviation LO | ||
| - use Logistics Object URI / Organization URI for the complete URI of a Logistics Object, i.e. https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c | ||
| - use logisticsObjectID for the unique identifier part of the URI, i.e. 1a8ded38-1804-467c-a369-81a411416b7c | ||
| - use Data Holder instead of Data Onwer | ||
| - redesign the Update Action Requests section | ||
| - use the Collection object to return a list of Logistics Events | ||
|
|
||
|
|
||
| ### Removed | ||
|
|
||
| - removed Memento (incl. TimeGate, Timemap) | ||
| - removed implicit endpoints; define URI structure of Logistics Objects | ||
| - removed Link HTTP header, because URI and endpoint structure is defined | ||
| - removed required ttl/turtle as supported content-type | ||
| - removed acl endpoint | ||
|
|
||
|
|
||
| ### Added | ||
|
|
||
| - added UTF-8 as default content encoding | ||
| - added 1 as default revision number for AuditTrail and LogisticsObjects | ||
| - added class diagram as supporting document | ||
| - added overview of data classes and properties as CSV file to supporting documents, | ||
| - added two reference OpenAPI specifications as supporting documents (minimum = to be ONE Record server compliant; recommended = for comfort features) | ||
| - added `Implementation Guidelines` section to reduce ambiguity | ||
| - added JSON files with examples mentioned in the API specification | ||
| - added overview of permissions for Access Delegation | ||
| - added ActionEnum to class diagram | ||
| - added Authentication and Authorization with OpenID Connect | ||
| - added security and endpoint information for all APIs | ||
| - added allow subscription for third parties | ||
| - added list of JSON-LD libraries in the `Implementation Guidelines` | ||
|
|
||
|
|
||
| --- | ||
|
|
||
| ## ONE Record API Ontology | ||
|
|
||
| ### Changed | ||
|
|
||
| - changed IRI structure to follow best practice | ||
| - renamed CompanyInformation to ServerInformation, because it mainly contains meta information about the ONE Record API and its configuration | ||
| - replaced ServerInformation#company and ServerInformation#companyId (formerly CompanyInformation) with ServerInformation#dataOwner | ||
| - merged PatchRequest into ChangeRequest | ||
| - renamed Operation#op enums to UPPERCASE, e.g. changed del to DELETE | ||
| - renamed Details to ErrorDetail | ||
| - renamed ChangeRequest#requestingParty to ChangeRequest#requestedBy | ||
| - renamed ChangeRequest#timestamp to ChangeRequest#requestedAt | ||
| - changed ChangeRequest#requestingParty<Branch> to ChangeRequest#requestedBy (https://onerecord.iata.org/ns/cargo#Organization) | ||
| - renamed ErrorDetail#attribute to ErrorDetail#property | ||
| - renamed ServerInformation#supportedLogisticsObjects to ServerInformation#supportedLogisticsObjectTypes | ||
| - changed property type of Notification#topic, Notification#changedProperties, OperationObject#datatype, ServerInformation#serverEndpoint, ServerInformation#supportedLogisticsObjects, ErrorDetail#property, ErrorDetail#resource, Subscription#callbackUrl, Subscription#topic, Subscription#subscribedTo | ||
| - renamed Subscription#myCompanyIdentifier to Subscription#subscriber | ||
| - changed Subscription#cacheFor (xsd:int) to Subscription#expiresAt (xsd:dateTime) | ||
| - renamed DelegationRequest#operations to DelegationRequest#permissions | ||
| - renamed api#status (used in SubscriptionRequest, ChangeRequest DelegationRequest) to api#requestStatus | ||
| - renamed ServerInformation#hasDataOnwer into ServerInformation#hasDataHolder | ||
| - changed Subscription#notifyRequestStatusChange from mandatory to optional | ||
| - changed Change#notifyRequestStatusChange from mandatory to optional | ||
| - changed AccessDelegation#notifyRequestStatusChange from mandatory to optional | ||
|
|
||
|
|
||
| ### Removed | ||
|
|
||
| - removed not used classes, data properties, object properties | ||
| - removed Memento (classes, data properties, object properties) | ||
| - removed ServerInformation#companyId | ||
| - removed AuditTrail#errors | ||
| - removed AuditTrail#loInitialSnapshot | ||
| - removed ChangeRequest#requestorCompanyIdentifier | ||
| - removed ServerInformation#errors | ||
| - removed Subscription#subscribedTo | ||
| - replaced LogisticsObjectRef data class and use https://onerecord.iata.org/ns/cargo#LogisticsObject instead | ||
| - removed Subscription#secret | ||
| - removed DelegationRequest#action | ||
| - removed Subscription#callbackUrl | ||
| - removed cargo ontology data classes | ||
| - removed ServerInformation#hasSupportedLogisticsObjectType | ||
| - removed Subscription#subscribeToLogisticsEvents | ||
|
|
||
| ### Added | ||
|
|
||
| - added Notification#changedProperties | ||
| - added further enums to notification#eventType, i.e. LOGISTICS_EVENT_RECEIVED, CHANGE_REQUEST_ACCEPTED, CHANGE_REQUEST_FAILED, CHANGE_REQUEST_PENDING, CHANGE_REQUEST_REJECTED, DELEGATION_REQUEST_PENDING, DELEGATION_REQUEST_ACCEPTED, DELEGATION_REQUEST_REJECTED, DELEGATION_REQUEST_FAILED, SUBSCRIPTION_REQUEST_PENDING, SUBSCRIPTION_REQUEST_ACCEPTED, SUBSCRIPTION_REQUEST_REJECTED, SUBSCRIPTION_REQUEST_FAILED | ||
| - added PENDING enum to ChangeRequest#requestStatus | ||
| - added Operation#s to enable updating not only properties of primitive types, e.g. int, string, but also embedded objects, e.g. Shipment#totalGrossWeight<Value> in LogisticsObjects | ||
| - added Notification#triggeringChangeRequest | ||
| - added SubscriptionRequest. Subscription is the response for the scenario where publisher initiates the Subscription and asks the subscribers for their Subscription information. SubscriptionRequest is used for scenario where the subscriber initiates a SubscriptionRequest towards the Publisher. | ||
| - added Subscription#topicType to indicate if topic is a LogisticsObject type or a specific LogisticsObjectIdentifier | ||
| - added ServerInformation#supportedApiVersion | ||
| - added ActionRequest as superclass for SubscriptionRequest, ChangeRequest, and DelegationRequest | ||
| - added providesNotificationsEndpoint (xsd:boolean) to ServerInformation | ||
| - added AccessDelegation and Change for ActionRequests | ||
| - import cargo ontology with `owl:imports cargo` | ||
| - changed min/max cardinalities to exact cardinalities (`qualifiedCardinality`) | ||
| - introduced Named Individuals to represent ENUMs | ||
| - added Notification#hasLogisticsObjectType | ||
| - added Subscription#includeSubscriptionEventType | ||
| - added enumeration SubscriptionEventType | ||
| - added Collection class |
229 changes: 229 additions & 0 deletions
229
2024-12-standard/API-Security/ONE-Record-API-Class-Diagram.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,229 @@ | ||
| # ONE Record API Class Diagram | ||
|
|
||
| **Version:** 2.1.0 **Status:** Submitted to COTB | ||
|
|
||
| ```mermaid | ||
| classDiagram | ||
| direction LR | ||
| class LogisticsObject{ | ||
| } | ||
| class Organization{ | ||
| } | ||
| class AccessDelegation{ | ||
| + hasDescription: xsd:string [0..1] | ||
| + hasPermission[]: Permission [1..*] | ||
| + isRequestedFor[]: Organization [1..*] | ||
| + notifyRequestStatusChange: xsd:boolean = FALSE | ||
| + hasLogisticsObject[]: LogisticsObject [1..*] | ||
| } | ||
| AccessDelegation "1" --> "1..*" Permission | ||
| AccessDelegation "1" --> "1..*" Organization: requestedFor | ||
| AccessDelegation "1" --> "1..*" LogisticsObject | ||
| class ActionRequest { | ||
| <<Abstract>> | ||
| + hasError[]: Error [*] | ||
| + isRequestedAt: xsd:dateTime | ||
| + isRequestedBy: Organization | ||
| + isRevokedBy: Organization [0..1] | ||
| + hasRequestStatus: RequestStatus = REQUEST_PENDING | ||
| + isRevokedAt: xsd:dateTime [0..1] | ||
| } | ||
| ActionRequest <|-- AccessDelegationRequest | ||
| ActionRequest <|-- ChangeRequest | ||
| ActionRequest <|-- SubscriptionRequest | ||
| ActionRequest <|-- VerificationRequest | ||
| ActionRequest "1" --> "0..*" Error | ||
| ActionRequest "1" --> "1..*" Organization : requestedBy | ||
| ActionRequest --> RequestStatus | ||
| ActionRequest "1" --> "1..*" Organization : revokedBy | ||
| class AccessDelegationRequest{ | ||
| + hasAccessDelegation: AccessDelegation | ||
| } | ||
| AccessDelegationRequest "1" --> "1" AccessDelegation | ||
| class ChangeRequest{ | ||
| + hasChange: Change | ||
| } | ||
| ChangeRequest "1" --> "1" LogisticsObject | ||
| ChangeRequest "1" --> "1" Change | ||
| class SubscriptionRequest{ | ||
| + hasSubscription: Subscription | ||
| } | ||
| SubscriptionRequest "1" --> "1" Subscription | ||
| class AuditTrail{ | ||
| + hasActionRequest[]: ActionRequest [*] | ||
| + hasLatestRevision: xsd:positiveInteger | ||
| } | ||
| AuditTrail "1" --> "*" ChangeRequest | ||
| class Change{ | ||
| + hasDescription: xsd:string [0..1] | ||
| + hasOperation[]: Operation [1..*] | ||
| + hasLogisticsObject: LogisticsObject | ||
| + hasRevision: xsd:positiveInteger | ||
| + notifyRequestStatusChange: xsd:boolean = FALSE | ||
| + hasVerificationRequest[]: VerificationRequest [0..*] | ||
| } | ||
| Change "1" --> "1" LogisticsObject | ||
| Change "1" --> "1..*" Operation | ||
| class Collection{ | ||
| + hasItem: Object [0..*] | ||
| + hasTotalItems: xsd:nonNegativeInteger [0..1] | ||
| } | ||
| class Error{ | ||
| + hasErrorDetail[]: ErrorDetail [1..*] | ||
| + hasTitle: xsd:string | ||
| } | ||
| Error "1" --> "*" ErrorDetail | ||
| class ErrorDetail{ | ||
| + hasCode: xsd:string [0..1] | ||
| + hasMessage: xsd:string [0..1] | ||
| + hasProperty: xsd:anyURI [0..1] | ||
| + hasResource: xsd:anyURI [0..1] | ||
| } | ||
| class Notification{ | ||
| + hasChangedProperty[]: xsd:anyURI [*] | ||
| + hasEventType: NotificationEventType | ||
| + isTriggeredBy: ActionRequest [0..1] | ||
| + hasLogisticsObject: LogisticsObject [0..1] | ||
| + hasLogisticsObjectType: xsd:anyURI [0..1] | ||
| } | ||
| Notification "1"--> "0..1" LogisticsObject | ||
| Notification "1" --> "1" NotificationEventType | ||
| Notification "1" --> "0..1" ActionRequest | ||
| class Operation{ | ||
| + o: OperationObject | ||
| + op: PatchOperation | ||
| + p: xsd:anyURI | ||
| + s: xsd:string | ||
| } | ||
| Operation "1" --> "1" OperationObject | ||
| Operation --> PatchOperation | ||
| class OperationObject{ | ||
| + hasDatatype: xsd:anyURI | ||
| + hasValue: xsd:string | ||
| } | ||
| class ServerInformation{ | ||
| + hasDataHolder: Organization | ||
| + hasServerEndpoint: xsd:anyURI | ||
| + hasSupportedApiVersion[]: xsd:string [1..*] | ||
| + hasSupportedContentType[]: xsd:string [1..*] | ||
| + hasSupportedEncoding[]: xsd:string [*] | ||
| + hasSupportedLanguage[]: xsd:string [1..*] | ||
| + hasSupportedOntology[]: xsd:anyURI [1..*] | ||
| + hasSupportedOntologyVersion[]: xsd:anyURI [1..*] | ||
| } | ||
| ServerInformation "1" --> "1" Organization | ||
| class Subscription{ | ||
| + hasContentType[]: xsd:string [*] | ||
| + hasDescription: xsd:string [0..1] | ||
| + expiresAt: xsd:dateTime [0..1] | ||
| + hasSubscriber: Organization | ||
| + hasTopicType: TopicType | ||
| + notifyRequestStatusChange: xsd:boolean = FALSE | ||
| + sendLogisticsObjectBody: xsd:boolean = FALSE | ||
| + includeSubscriptionEventType[]: SubscriptionEventType [1..*] | ||
| + hasTopic: xsd:anyURI | ||
| } | ||
| Subscription "1" --> "1" Organization: hasSubscriber | ||
| Subscription --> TopicType | ||
| Subscription "1" --> "1..*" SubscriptionEventType | ||
| class NotificationEventType{ | ||
| <<Enumeration>> | ||
| LOGISTICS_OBJECT_CREATED | ||
| LOGISTICS_OBJECT_UPDATED | ||
| LOGISTICS_EVENT_RECEIVED | ||
| CHANGE_REQUEST_PENDING | ||
| CHANGE_REQUEST_ACCEPTED | ||
| CHANGE_REQUEST_REJECTED | ||
| CHANGE_REQUEST_FAILED | ||
| CHANGE_REQUEST_REVOKED | ||
| ACCESS_DELEGATION_REQUEST_PENDING | ||
| ACCESS_DELEGATION_REQUEST_ACCEPTED | ||
| ACCESS_DELEGATION_REQUEST_REJECTED | ||
| ACCESS_DELEGATION_REQUEST_FAILED | ||
| ACCESS_DELEGATION_REQUEST_REVOKED | ||
| SUBSCRIPTION_REQUEST_PENDING | ||
| SUBSCRIPTION_REQUEST_ACCEPTED | ||
| SUBSCRIPTION_REQUEST_REJECTED | ||
| SUBSCRIPTION_REQUEST_FAILED | ||
| SUBSCRIPTION_REQUEST_REVOKED | ||
| VERIFICATION_REQUEST_PENDING | ||
| VERIFICATION_REQUEST_ACKNOWLEDGED | ||
| VERIFICATION_REQUEST_REJECTED | ||
| VERIFICATION_REQUEST_FAILED | ||
| VERIFICATION_REQUEST_REVOKED | ||
| } | ||
| class PatchOperation{ | ||
| <<Enumeration>> | ||
| ADD | ||
| DELETE | ||
| } | ||
| class Permission{ | ||
| <<Enumeration>> | ||
| GET_LOGISTICS_EVENT | ||
| GET_LOGISTICS_OBJECT | ||
| PATCH_LOGISTICS_OBJECT | ||
| POST_LOGISTICS_EVENT | ||
| } | ||
| class TopicType{ | ||
| <<Enumeration>> | ||
| LOGISTICS_OBJECT_TYPE | ||
| LOGISTICS_OBJECT_URI | ||
| } | ||
| class RequestStatus{ | ||
| <<Enumeration>> | ||
| REQUEST_PENDING | ||
| REQUEST_ACCEPTED | ||
| REQUEST_REJECTED | ||
| REQUEST_FAILED | ||
| REQUEST_REVOKED | ||
| REQUEST_ACKNOWLEDGED | ||
| } | ||
| class SubscriptionEventType{ | ||
| <<Enumeration>> | ||
| LOGISTICS_OBJECT_CREATED | ||
| LOGISTICS_OBJECT_UPDATED | ||
| LOGISTICS_EVENT_RECEIVED | ||
| } | ||
| class VerificationRequest{ | ||
| + hasVerification: Verification | ||
| } | ||
| VerificationRequest"1" --> "1" Verification | ||
| class Verification{ | ||
| + hasLogisticsObject: LogisticsObject | ||
| + hasError[]: Error[1..*] | ||
| + hasRevision: xsd:positiveInteger | ||
| + notifyRequestStatusChange: xsd:boolean = FALSE | ||
| } | ||
| Verification "1" --> "1" LogisticsObject | ||
| Verification "1" --> "1..*" Error | ||
| ``` |
Oops, something went wrong.