Merge pull request #209 from IATA-Cargo/LogisticsEvents_Collections

Logistics events collections

working_draft/API/CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -49,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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`
 
 
 ---
@@ -116,3 +118,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - added Notification#hasLogisticsObjectType
 - added Subscription#includeSubscriptionEventType 
 - added enumeration SubscriptionEventType
+- added Collection class 

working_draft/API/ONE-Record-API-Class-Diagram.md

@@ -74,6 +74,11 @@ classDiagram
     Change "1" --> "1" LogisticsObject
     Change "1" --> "1..*" Operation
     
+    class Collection{    
+        + hasItem: Object [0..*]
+     	+ hasTotalItems: xsd:nonNegativeInteger [0..1]    
+    }
+
     class Error{        
         + hasErrorDetail[]: ErrorDetails [1..*]
         + hasTitle: xsd:string

working_draft/API/ONE-Record-API-Ontology.csv

@@ -45,4 +45,6 @@ False;https://onerecord.iata.org/ns/api#Notification;https://onerecord.iata.org/
 False;https://onerecord.iata.org/ns/api#Subscription;https://onerecord.iata.org/ns/api#topicType;http://www.w3.org/2001/XMLSchema#string;0..1;LOGISTICS_OBJECT_IDENTIFIER,LOGISTICS_OBJECT_TYPE;Specifies if the topic is a LogisticsObject type or a Logistics Object Identifier
 False;https://onerecord.iata.org/ns/api#Notification;https://onerecord.iata.org/ns/api#triggeredByChangeRequest;https://onerecord.iata.org/ns/api#ChangeRequest;0..1;;Optional URI to the ChangeRequest that triggered a Notification if the eventType is one of CHANGE_REQUEST_ACCEPTED, CHANGE_REQUEST_REJECT, or CHANGE_REQUEST_FAILED
 False;https://onerecord.iata.org/ns/api#OperationObject;https://onerecord.iata.org/ns/api#value;http://www.w3.org/2001/XMLSchema#string;0..1;;Updated value for the field
-False;https://onerecord.iata.org/ns/api#Notification;https://onerecord.iata.org/ns/api#hasLogisticsObjectType;http://www.w3.org/2001/XMLSchema#anyURI;0..1;;The type of cargo:LogisticsObject in the notification e.g. https://onerecord.iata.org/ns/cargo#Piece
+False;https://onerecord.iata.org/ns/api#Notification;https://onerecord.iata.org/ns/api#hasLogisticsObjectType;http://www.w3.org/2001/XMLSchema#anyURI;0..1;;The type of cargo:LogisticsObject in the notification e.g. https://onerecord.iata.org/ns/cargo#Piece
+False;https://onerecord.iata.org/ns/api#Collection;https://onerecord.iata.org/ns/api#hasItem;http://www.w3.org/2002/07/owl#Thing;0..N;;Item that is contained in a collection
+False;https://onerecord.iata.org/ns/api#Collection;https://onerecord.iata.org/ns/api#hasTotalItems;http://www.w3.org/2001/XMLSchema#nonNegativeInteger;0..1;;The number of total items contained in a collection

working_draft/API/ONE-Record-API-Ontology.ttl

@@ -120,6 +120,13 @@ owl:minQualifiedCardinality rdf:type owl:AnnotationProperty .
               rdfs:label "has Event Type"@en .
 
 
+###  https://onerecord.iata.org/ns/api#hasItem
+:hasItem rdf:type owl:ObjectProperty ;
+         rdfs:domain :Collection ;
+         rdfs:comment "Item that is contained in a collection"@en ;
+         rdfs:label "has Item"@en .
+
+
 ###  https://onerecord.iata.org/ns/api#hasLogisticsAgent
 :hasLogisticsAgent rdf:type owl:ObjectProperty ;
                    rdfs:domain :AccessPermissions ;
@@ -414,6 +421,14 @@ owl:minQualifiedCardinality rdf:type owl:AnnotationProperty .
           rdfs:label "Topic"@en .
 
 
+###  https://onerecord.iata.org/ns/api#hasTotalItems
+:hasTotalItems rdf:type owl:DatatypeProperty ;
+               rdfs:domain :Collection ;
+               rdfs:range xsd:nonNegativeInteger ;
+               rdfs:comment "The number of total items contained in a collection"@en ;
+               rdfs:label "Total items"@en .
+
+
 ###  https://onerecord.iata.org/ns/api#hasValue
 :hasValue rdf:type owl:DatatypeProperty ;
           rdfs:domain :OperationObject ;
@@ -719,6 +734,21 @@ owl:minQualifiedCardinality rdf:type owl:AnnotationProperty .
                rdfs:label "Change Request"@en .
 
 
+###  https://onerecord.iata.org/ns/api#Collection
+:Collection rdf:type owl:Class ;
+            rdfs:subClassOf [ rdf:type owl:Restriction ;
+                              owl:onProperty :hasItem ;
+                              owl:someValuesFrom owl:Thing
+                            ] ,
+                            [ rdf:type owl:Restriction ;
+                              owl:onProperty :hasTotalItems ;
+                              owl:qualifiedCardinality "1"^^xsd:nonNegativeInteger ;
+                              owl:onDataRange xsd:nonNegativeInteger
+                            ] ;
+            rdfs:comment "Used as response of endpoints returning a collection of more than one graph, i.e. more than one not linked subjects."@en ;
+            rdfs:label "Collection"@en .
+
+
 ###  https://onerecord.iata.org/ns/api#Error
 :Error rdf:type owl:Class ;
        rdfs:subClassOf [ rdf:type owl:Restriction ;
@@ -1109,6 +1139,17 @@ owl:minQualifiedCardinality rdf:type owl:AnnotationProperty .
                                ] .
 
 
+###  https://onerecord.iata.org/ns/cargo#LogisticsAgent
+cargo:LogisticsAgent rdf:type owl:Class .
+
+
+###  https://onerecord.iata.org/ns/cargo#LogisticsObject
+cargo:LogisticsObject rdf:type owl:Class .
+
+
+###  https://onerecord.iata.org/ns/cargo#Organization
+cargo:Organization rdf:type owl:Class .
+
 
 #################################################################
 #    Individuals

working_draft/API/ONE-Record-API-OpenAPI.recommended.yaml

@@ -580,7 +580,7 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/LogisticsEvent'
+                  $ref: '#/components/schemas/LogisticsEventCollection'
     post:
       tags:
       - Logistics Events
@@ -3235,6 +3235,22 @@ components:
           type: string
         https://onerecord.iata.org/ns/cargo#skeletonIndicator:
           type: boolean
+    LogisticsEventCollection:
+      type: object
+      properties:
+        '@id':
+          type: string
+        '@type':
+          uniqueItems: true
+          type: array
+          items:
+            type: string
+        https://onerecord.iata.org/ns/api#hasItem:
+          type: array
+          items:
+            $ref: '#/components/schemas/LogisticEvent'
+        https://onerecord.iata.org/ns/api#hasTotalItem:
+          type: integer          
     LogisticsService:
       type: object
       properties:

working_draft/API/docs/action-requests.md

@@ -224,11 +224,10 @@ This API action can be used the holder/publisher of a Logistics Object to approv
 For example, as a publisher, this API action is used to change the status of a received Subscription Request on a ONE Record server using the PATCH HTTP method. 
 
 !!! note 
-        Although the updating the state of of a Subscription Request is specified in the ONE Record API specification, 
-        it is not required to expose an API endpoint for this API action to be compliant with the ONE Record standard. 
-        The reason for this is that _only the holder of the logistics object_ MAY accept or reject a subscription request with any business logic or technology.         
+    Although the updating the state of of a Subscription Request is specified in the ONE Record API specification, it is not required to expose an API endpoint for this API action to be compliant with the ONE Record standard. 
+    The reason for this is that _only the holder of the logistics object_ MAY accept or reject a subscription request with any business logic or technology.         
 
-        Nevertheless, this API action specification is included for reference, because in many cases, the use of HTTP PATCH is the preferred solution to update resources with REST APIs.
+    Nevertheless, this API action specification is included for reference, because in many cases, the use of HTTP PATCH is the preferred solution to update resources with REST APIs.
 
 
 ## Endpoint

working_draft/API/docs/examples/LogisticsEvents_empty_list.json

@@ -0,0 +1,9 @@
+{
+    "@context": {
+      "cargo": "https://onerecord.iata.org/ns/cargo#",
+      "api": "https://onerecord.iata.org/ns/api#"
+    },
+    "@id": "https://1r.example.com/logistics-objects/2a7d1338-9033-13xc-b665-81a411418978/logistics-events",
+    "@type": "api:Collection",
+    "api:hasTotalItems": 0
+  }

working_draft/API/docs/examples/LogisticsEvents_filtered_list.json

@@ -1,30 +1,32 @@
 {
   "@context": {
-    "cargo": "https://onerecord.iata.org/ns/cargo#"
+    "cargo": "https://onerecord.iata.org/ns/cargo#",
+    "api": "https://onerecord.iata.org/ns/api#"
   },
-  "@graph": [
-    {
-      "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c/logistics-events/afb4b8cf-288a-459c-97fd-ccd538ec527f",
-      "@type": "cargo:LogisticsEvent",
-      "cargo:creationDate": {
-        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
-        "@value": "2023-04-01T10:38:01.000Z"
-      },
-      "cargo:eventDate": {
-        "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
-        "@value": "2023-04-01T10:38:01.000Z"
-      },
-      "cargo:eventCode": "DEP",
-      "cargo:eventName": "Consignment departed on a specific flight",
-      "cargo:eventTimeType": "Actual",
-      "cargo:linkedObject": {
-        "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c",
-        "@type": "cargo:Shipment"
-      },
-      "cargo:recordedBy": {
-        "@id": "https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda",
-        "@type": "cargo:Company"
-      }
+  "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c/logistics-events",
+  "@type": "api:Collection",
+  "api:hasTotalItems": 1,
+  "api:hasItems": {
+    "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c/logistics-events/afb4b8cf-288a-459c-97fd-ccd538ec527f",
+    "@type": "cargo:LogisticsEvent",
+    "cargo:creationDate": {
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
+      "@value": "2023-04-01T10:38:01.000Z"
+    },
+    "cargo:eventDate": {
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
+      "@value": "2023-04-01T10:38:01.000Z"
+    },
+    "cargo:eventCode": "DEP",
+    "cargo:eventName": "Consignment departed on a specific flight",
+    "cargo:eventTimeType": "Actual",
+    "cargo:linkedObject": {
+      "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c",
+      "@type": "cargo:Shipment"
+    },
+    "cargo:recordedBy": {
+      "@id": "https://1r.example.com/logistics-objects/957e2622-9d31-493b-8b8f-3c805064dbda",
+      "@type": "cargo:Company"
     }
-  ]
+  }
 }

working_draft/API/docs/examples/LogisticsEvents_list.json

@@ -1,8 +1,12 @@
 {
   "@context": {
-    "cargo": "https://onerecord.iata.org/ns/cargo#"
+    "cargo": "https://onerecord.iata.org/ns/cargo#",
+    "api": "https://onerecord.iata.org/ns/api#"
   },
-  "@graph": [
+  "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c/logistics-events",
+  "@type": "api:Collection",
+  "api:hasTotalItems": 2,
+  "api:hasItem": [
     {
       "@id": "https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b3c/logistics-events/afb4b8cf-288a-459c-97fd-ccd538ec527f",
       "@type": "cargo:LogisticsEvent",

working_draft/API/docs/implementation-guidelines.md

@@ -38,6 +38,16 @@ Furthermore, the following requirements MUST be fulfilled:
 - A JSON-LD document MUST include an `@type` property that specifies the type of the data object, i.e. the ONE Record Logistics Object class (https://onerecord.iata.org/ns/cargo#Sensor in the previous example 1 and example 2).
 - A JSON-LD document MUST include an `@language` property in the `@context` property that specifies the language of the returned data object, if the language differs from the default language `en-US`.
 
+During the implementation phase, it is highly recommended to utilize a JSON-LD library. Below is a compilation of libraries for the most commonly used programming languages:
+
+- JavaScript: 
+    - [https://rdf.js.org](https://rdf.js.org)
+- Java 
+    - [https://rdf4j.org](https://rdf4j.org)
+    - [https://jena.apache.org](https://jena.apache.org)
+- Python 
+    - [https://wiki.python.org/moin/RdfLibraries](https://wiki.python.org/moin/RdfLibraries)
+
 !!! note
 
     The [OpenAPI specification](assets/ONE-Record-API-OpenAPI.yaml) includes only schemas that can be used to generate the expanded JSON-LD document form.

working_draft/API/docs/logistics-events.md

@@ -301,14 +301,45 @@ The following HTTP query parameters MUST be supported:
 ## Response
 
 A successful request MUST return a `HTTP/1.1 200 OK` status code. 
-The body of the response includes all logistics events matching the specified query parameters.
 The response body is formatted accordingly to the format that has been requested in the `Accept` request header.
+The body of the response is composed by a [Collection](https://onerecord.iata.org/ns/api#Collection) object containing all [LogisticsEvent](https://onerecord.iata.org/ns/cargo#LogisticsEvent) matching the specified query parameters.
+
+```mermaid
+classDiagram   
+    direction LR   
+
+    class Collection{    
+        + hasItem: LogisticsEvents [0..*]
+     	+ hasTotalItems: xsd:nonNegativeInteger [0..1]    
+    }
+    
+    class LogisticsEvent{
+
+    }
+    Collection "1" --> "0..*" LogisticsEvent
+
+```
+
+
+The ONE Record API employs the [Collection](https://onerecord.iata.org/ns/api#Collection) class to return an array of objects. This class encompasses two properties:
+
+- [api:hasItem](https://onerecord.iata.org/ns/api#hasItem) returns the array of objects.
+- [api:hasTotalItem](https://onerecord.iata.org/ns/api#hasTotalItem) returns the count of elements within the returned array.
+
+In this particular case, @id property in the response body MUST be equal to the Endpoint defined in the [Endpoint section](#endpoint_2) (i.e.: https://1r.example.com/logistics-objects/2a7d1338-9033-13xc-b665-81a411418978/logistics-events). 
+
+
 
 !!! note
-        The response body contains the keyword `@set` to indicate the ordering of the logistics events.
-        This is a preparation for future sorting and pagination filters.
-        (cf. [https://www.w3.org/TR/json-ld11/#sets](https://www.w3.org/TR/json-ld11/#sets))
 
+    The ONE Record standard fully adopts the JSON-LD specification, and as a result, the presence of the [api:hasItem](https://onerecord.iata.org/ns/api#hasItem) property of [Collection](https://onerecord.iata.org/ns/api#Collection) is contingent on the number of Logistics Events returned byt the specified query. Specifically:
+        
+    - If the specified query returns zero Logistics Events, [api:hasItem](https://onerecord.iata.org/ns/api#hasItem) may not appear in the JSON, and [api:hasTotalItem](https://onerecord.iata.org/ns/api#hasTotalItem) must be 0.
+    - When the specified query returns exactly one Logistics Event, [api:hasItem](https://onerecord.iata.org/ns/api#hasItem) will directly represent that Logistics Event, and [api:hasTotalItem](https://onerecord.iata.org/ns/api#hasTotalItem) must be 1.
+    - In cases where the specified query returns multiple Logistics Events, [api:hasItem](https://onerecord.iata.org/ns/api#hasItem) will be an array containing those Logistics Events, and [api:hasTotalItem](https://onerecord.iata.org/ns/api#hasTotalItem) must be equal to the number of Logistics Events retrieved by the specified query.
+
+    During the implementation phase, it is highly recommended to utilize a JSON-LD library for parsing responses.
+    To discover JSON-LD libraries for various programming languages, consult the [implementation guidelines](./implementation-guidelines.md#serialization-and-data-formats).
 
 The following HTTP headers parameters MUST be present in the response:
 
@@ -378,4 +409,27 @@ Content-Language: en-US
 
 --8<-- "examples/LogisticsEvents_filtered_list.json"
 ```
-_([examples/LogisticsEvents_filtered_list.json](examples/LogisticsEvents_filtered_list.json))_
+_([examples/LogisticsEvents_filtered_list.json](examples/LogisticsEvents_filtered_list.json))_
+
+## Example C3
+
+Get an empty list of events.
+
+Request:
+
+```http
+GET /logistics-objects/2a7d1338-9033-13xc-b665-81a411418978/logistics-events HTTP/1.1
+Host: 1r.example.com
+Accept: application/ld+json; version=2.0.0-dev
+```
+
+Response:
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/ld+json; version=2.0.0-dev
+Content-Language: en-US
+
+--8<-- "examples/LogisticsEvents_empty_list.json"
+```
+_([examples/LogisticsEvents_empty_list.json](examples/LogisticsEvents_empty_list.json))_