You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
False;https://onerecord.iata.org/ns/api#Operation;https://onerecord.iata.org/ns/api#s;http://www.w3.org/2001/XMLSchema#string;0..1;;Operation objects MUST have exactly one "s", subject, member. The value of this member MUST be one of IRI or blank node.
31
31
False;https://onerecord.iata.org/ns/api#Subscription;https://onerecord.iata.org/ns/api#secret;http://www.w3.org/2001/XMLSchema#string;0..1;;Either a secret or API Key that ensures that only companies with this subscription information can POST to the subscriber callback endpoint
32
32
False;https://onerecord.iata.org/ns/api#Subscription;https://onerecord.iata.org/ns/api#sendLogisticsObjectBody;http://www.w3.org/2001/XMLSchema#boolean;0..1;;Flag specifying if the publisher should send the whole logistics object or not in the notification object
33
-
False;https://onerecord.iata.org/ns/api#ServerInformation;https://onerecord.iata.org/ns/api#serverEndpoint;http://www.w3.org/2001/XMLSchema#anyURI;0..1;;ONE Record API endpoint in the Internet of Logistics
33
+
False;https://onerecord.iata.org/ns/api#ServerInformation;https://onerecord.iata.org/ns/api#serverEndpoint;http://www.w3.org/2001/XMLSchema#anyURI;0..1;;ONE Record API endpoint
34
34
False;https://onerecord.iata.org/ns/api#SubscriptionRequest;https://onerecord.iata.org/ns/api#status;http://www.w3.org/2001/XMLSchema#string;0..1;ACCEPTED,PENDING,REJECTED;PENDING, ACCEPTED or REJECTED
35
35
False;https://onerecord.iata.org/ns/api#Subscription;https://onerecord.iata.org/ns/api#includeSubscriptionEventType;https://onerecord.iata.org/ns/api#SubscriptionEventType;1..N;LOGISTICS_OBJECT_CREATED,LOGISTICS_OBJECT_UPDATED,LOGISTICS_EVENT_RECEIVED;An array used to indicate the specific types of notifications that the subscriber desires to receive from the publisher. The subscriber is required to specify their preferences on a per-type basis
36
36
False;https://onerecord.iata.org/ns/api#Subscription;https://onerecord.iata.org/ns/api#subscriber;https://onerecord.iata.org/ns/cargo#Organization;0..1;;Organization Identifier of the subscribing Organization
Copy file name to clipboardExpand all lines: working_draft/API/docs/access-delegations.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@ In ONE Record, parties can grant other parties access to their data (or parts of
2
2
The ONE Record standard allows parties to change or revoke these access rights to their data whenever they wish.
3
3
4
4
Before an organization can access a LogisticsObject of another organization, it needs to be authorized to do so and the server that hosts the logistics objects will determine whether to grant access.
5
-
Typically, when an participant in the Internet of Logistics creates a LogisticsObject and makes it available via its ONE Record API, the IoL participant will share the URI of that LogisticsObject with another IoL participant and grant them access by default.
5
+
Typically, when an participant creates a LogisticsObject and makes it available via its ONE Record API, the IoL participant will share the URI of that LogisticsObject with another IoL participant and grant them access by default.
6
6
7
7
For example, a freight forwarder creates a [Shipment](https://onerecord.iata.org/ns/cargo#Shipment), grants read access to an airline, and then sends the URI of the Logistics Object via a ONE Record Notification or other channel to the airline.
8
8
At this point, only the forwarder and the airline can access this specific LogisticsObject, but no one else.
Trust chains are based on business partnerships and trust in the transport chain.
164
-
It ensures that the company who has shared a logistics object on the Internet of Logistics, always knows who MAY access the data and at any time, it can revoke all or part of the chain of trust.
164
+
It ensures that the company who has shared a logistics object, always knows who MAY access the data and at any time, it can revoke all or part of the chain of trust.
165
165
166
166
Therefore, the concept described in the previous sections can be used by organizations to delegate access to their partners, which become 3rd parties.
167
167
In the example above, the airline can request that the forwarder gives access to their ground handler.
Copy file name to clipboardExpand all lines: working_draft/API/docs/api-features.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,17 +3,17 @@ The following features summarize all of the ONE Record API features
3
3
4
4
**Get ONE Record Server Information** Anyone who has access to a ONE Record server can retrieve the technical server meta information that contains information about supported features, supported ONE Record API version, supported ONE Record data model version, etc.
5
5
6
-
**Create and publish a Logistics Object** - Anyone who controls a ONE Record server can create a new Logistics Object based on the ONE Record data model specification. Once created the Logistics Object is associated with a unique URI that makes the Logistics Object available in the Internet of Logistics.
6
+
**Create and publish a Logistics Object** - Anyone who controls a ONE Record server can create a new Logistics Object based on the ONE Record data model specification. Once created the Logistics Object is associated with a unique URI that makes the Logistics Object available on the network.
7
7
8
8
**Read a Logistics Object** - Logistics Objects can be retrieved by calling the URI of that Logistics Object - its Logistics Object URI. Access rights to that Logistics Object URI is managed by the Holder of the Logistics Object.
9
9
10
10
**Update a Logistics Object** - As a fundamental principle, _only_ the Holder of a Logistics Object can make changes to it. Therefore, changes required by other parties are expressed as `Change Requests` that needs to be approved and executed by the actual holder.
11
11
12
12
**Subscribe to a Logistics Object for updates** - Once a Logistics Object has been created, the holder can propose subscriptions to other parties who will then be notified of any changes. Other parties may also request such a subscription at the discretion of the holder.
13
13
14
-
**Create Logistics Event linked with Logistics Objects** - Logistics Events like "arrival", "acceptance" etc. are central in the management of logistics and transport. Every participant in the Internet of Logistics with sufficient access rights can submit any type of Logistics Event to any published Logistics Object.
14
+
**Create Logistics Event linked with Logistics Objects** - Logistics Events like "arrival", "acceptance" etc. are central in the management of logistics and transport. Every participant in the network with sufficient access rights can submit any type of Logistics Event to any published Logistics Object.
15
15
16
-
**Read Logistics Event linked to a Logistics Object** - Every participant of the Internet of Logistics with sufficient permissions, can also query the Logistics Events associated with a Logistics Object.
16
+
**Read Logistics Event linked to a Logistics Object** - Every participant of the network with sufficient permissions, can also query the Logistics Events associated with a Logistics Object.
17
17
18
18
**Manage access to a Logistics Object** - Another fundamental principle of ONE Record is that only holders of Logistics Objects have fully control access rights to that Logistics Object. Therefore, only the holder of a Logistics Object can delegate permissions to users of the Logistics Object.
Copy file name to clipboardExpand all lines: working_draft/API/docs/concepts.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
## ONE Record API
2
2
3
-
The ONE Record API specifies the interface and interactions via standardized Web Application Programming Interface (API), which allows all participants in the Internet of Logistics to connect their IT systems to the IT systems of their partners, using state of the art web technologies.
3
+
The ONE Record API specifies the interface and interactions via standardized Web Application Programming Interface (API), which allows all participants in the network to connect their IT systems to the IT systems of their partners, using state of the art web technologies.
4
4
To achieve this, the ONE Record API specifies how data exchange between logistics and transport stakeholders can be achieved over HTTP.
5
5
The ONE Record API specification is associated with the [ONE Record Data Model](#one-record-data-model) that specifies the models and relationships within the transport and logistics data domain as common *"language"* between all stakeholders.
6
6
@@ -15,15 +15,15 @@ The `ONE Record API ontology` contains the data classes and their relationship u
15
15
Both ontologies are maintained on [GitHub](https://github.com/IATA-Cargo/ONE-Record).
16
16
Furthermore, an online documentation based on the ontology can be found in the Tools section on the [ONE Record Developer Portal](https://onerecord.iata.org/).
17
17
18
-
## Internet of Logistics Node (IoL Node)
18
+
## ONE Record Node
19
19
20
-
Each Internet of Logistics participant is technically represented as an Internet of Logistics Node (IoL Node) (also called ONE Record node).
21
-
Such an IoL node can have capabilities of a [ONE Record server](#one-record-server) and/or a [ONE Record client](#one-record-client).
20
+
Each participant is technically represented as an ONE Record node.
21
+
Such node can have capabilities of a [ONE Record server](#one-record-server) and/or a [ONE Record client](#one-record-client).
22
22
23
-
Typically, an IoL node represents a single organization.
24
-
However, there might exist scenarios where an IoL node is shared between (sub-)organizations.
23
+
Typically, a ONE Record node represents a single organization.
24
+
However, there might exist scenarios where an ONE Record node is shared between (sub-)organizations.
25
25
26
-
A single organization can also operate multiple IoL nodes, such as IoT devices that implement ONE Record clients to transmit data to ONE Record servers using the ONE Record standard.
26
+
A single organization can also operate multiple ONE Record nodes, such as IoT devices that implement ONE Record clients to transmit data to ONE Record servers using the ONE Record standard.
27
27
28
28
## ONE Record Server
29
29
@@ -34,7 +34,7 @@ In this document, the term ONE Record server is used when referring to an actual
34
34
35
35
## ONE Record Client
36
36
37
-
A ONE Record client is a technical representation of a stakeholder using ONE Record to exchange data in the Internet of Logistics.
37
+
A ONE Record client is a technical representation of a stakeholder using ONE Record to exchange data in the network.
38
38
Unlike a ONE Record server that responses to API requests, a ONE Record Client initiates interaction with a ONE Record server.
39
39
40
40
Each ONE Record server can also include a ONE Record client implementation in order to interact with other ONE Record server, i.e. by sending HTTP requests.
In ONE Record, each party in the Internet of Logistics, e.g., a shipper, airline, or public authorities like customs that acts as an holder or user of Logistics Objects, requires a globally unique identifier, a so-called `Organization URI`.
130
+
In ONE Record, each party in the ONE Record network, e.g., a shipper, airline, or public authorities like customs that acts as an holder or user of Logistics Objects, requires a globally unique identifier, a so-called `Organization URI`.
131
131
This MUST have a URI that points to a data object that inherits from [Organization](https://onerecord.iata.org/ns/cargo#Organization) which inherits from [LogisticsObject](https://onerecord.iata.org/ns/cargo#LogisticsObject). Therefore, the same URI structure as for Logistics Objects MUST be applied.
132
132
133
133
This data object can be a [Company](https://onerecord.iata.org/ns/cargo#Company), a [Carrier](https://onerecord.iata.org/ns/cargo#Carrier), or a [PublicAuthority](https://onerecord.iata.org/ns/cargo#PublicAuthority).
Copy file name to clipboardExpand all lines: working_draft/API/docs/glossary.md
+3-4Lines changed: 3 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,7 @@
5
5
| Authorization | A process that determines whether a IoL participant is allowed to access a specific Logistics Object |
6
6
| Cargo Operations & Technology Board (COTB) | Cargo Operations & Technology Board (COTB) reports to the Cargo Services Conference (CSC) at the International Air Transport Association. The COTB has authority over the ONE Record specifications. COTB decisions are formally endorsed by the CSC. ||
7
7
| Hashed Message Authentication Code (HMAC) | An authentication method to verify data integrity and authenticity of a message. |
8
-
| Identity & Authentication Provider (IAP) | A service that allows Internet of Logistics participants register and obtain an Public Key encrypted token identify themselves with ONE Record Servers and get access to Logistics Objects |
9
-
| Internet of Logistics (IoL) | A network of ONE Record Clients and Servers that can share Logistics Objects over the internet using the ONE Record standard data model, APIs and security |
8
+
| Identity & Authentication Provider (IAP) | A service that allows ONE Record netwokr participants register and obtain an Public Key encrypted token identify themselves with ONE Record Servers and get access to Logistics Objects |
10
9
| JavaScript Object Notation for Linked Data (JSON-LD) | JSON-LD is a lightweight Linked Data format. It is easy for humans to read and write. It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale. JSON-LD is an ideal data format for programming environments, REST Web services, and unstructured databases such as CouchDB and MongoDB. |
11
10
| JSON Web Key (JWK) | A JSON object that represents a set of public cryptographic keys. The properties of the object represent properties of the key, including its value. A JWK is used to verify JSON Web Tokens (JWT) issued by the Authorization Server. |
12
11
| JSON Web Key Set (JWKS) | A JSON object that contains a set of JWKs. The JSON object MUST have a keys property, which is an array of JWKs. |
@@ -16,9 +15,9 @@
16
15
| Open Authorization (OAuth) | OAuth (Open Authorization) is an authorization framework that enables a user to grant a third-party application access to their resources on another API or service without giving them their credentials (delegation of access in a network of secure systems). It uses tokens to ensure secure and limited access to user data while protecting their privacy. see [https://oauth.net/2/](https://oauth.net/2/)|
17
16
| OpenID Connect (OIDC) | OpenID Connect (OIDC) is a widely used authentication protocol that adds an identity layer on top of OAuth 2.0, allowing applications to verify the identities of users and obtain their basic profile information with user consent, enhancing security and user experience in modern web applications. |
18
17
| ONE Record Client | A software program that sends ONE Record API requests to a ONE Record server. |
19
-
| ONE Record Server | A software program that responses to ONE Record API requests from a ONE Record client on behalf of one or more participants in the Internet of Logistics|
18
+
| ONE Record Server | A software program that responses to ONE Record API requests from a ONE Record client on behalf of one or more participants in the network|
20
19
| ONE Record Notifications API | A dedicated ONE Record API endpoint for receiving notifications about updates related to logistics objects. |
21
-
| Participant | Server that access or shares data via the Internet of Logistics and that has registered with an Accredited Identity Provider and has possession of a valid certificate to prove this |
20
+
| Participant | Server that access or shares data and that has registered with an Accredited Identity Provider and has possession of a valid certificate to prove this |
22
21
| Publisher | The Party that makes their Logistics Objects available through a ONE Record Server |
23
22
| Subscriber | The Party that subscribes to Logistics Objects in order to receive updates automatically |
24
23
| Uniform Resource Identifier (URI) | A Uniform Resource Identifier (URI) is a URL that uniquely identifies a Logistics Object |
This section provides guidelines that MUST be followed by an implementer of the ONE Record API to ensure maximum compatibility with other ONE Record servers and clients on the Internet of Logistics.
5
+
This section provides guidelines that MUST be followed by an implementer of the ONE Record API to ensure maximum compatibility with other ONE Record servers and clients on the ONE Record network.
6
6
These principles MUST be followed in order to be compliant to the ONE Record standard, when implementing and publishing a ONE Record server.
7
7
8
8
This section provides also common knowledge and best practices for the implementation of REST APIs in general and the ONE Record API in particular.
@@ -165,7 +165,7 @@ Some possible changes to the ONE Record API specification COULD be:
165
165
- Addition of new API endpoint
166
166
- Removal of an existing API endpoint
167
167
168
-
Because the URI of a Logistics Object in the Internet of Logistics MUST NOT be changed (cf. [Logistics Object URI](concepts.md#logistics-object-uri)),
168
+
Because the URI of a Logistics Object MUST NOT be changed (cf. [Logistics Object URI](concepts.md#logistics-object-uri)),
169
169
an API versioning via URI Path is **not** possible, e.g.
@@ -420,7 +420,7 @@ It is RECOMMENDED to provide a technical documentation of the implemented and re
420
420
421
421
# Security
422
422
423
-
The ONE Record API specification prescribes only the minimum security requirements that enable secure communication in the Internet of Logistics.
423
+
The ONE Record API specification prescribes only the minimum security requirements that enable secure communication in the IONE Record network.
424
424
This involves securing the communication channel, authentication (verifying the identity of a requestor) and authorization (checking the access right of the requestor).
425
425
More information on authentication and authorization in the ONE Record context is described in the [Security section](security/security-overview.md).
Each Logistics Event in the Internet of Logistics MUST be accessible via its [Logistics Event URI](#logistics-events-uri) using the HTTP GET method.
173
+
Each Logistics Event MUST be accessible via its [Logistics Event URI](#logistics-events-uri) using the HTTP GET method.
174
174
This enables the Holder of the Logistics Object to manage access on the level of individual Logistics Event (see [Access Control page](./security/access-control.md) for more information).
175
175
If the requester is authorized to access this Logistics Event then the response body MUST include the requested Logistics Event.
0 commit comments