diff --git a/.gitignore b/.gitignore index 1b1b6e7..110eaa6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Dependencies -app//node_modules +app/node_modules # Production app/build diff --git a/app/docs/Examples/_category_.json b/app/docs/Examples/_category_.json index f934a87..3f679db 100644 --- a/app/docs/Examples/_category_.json +++ b/app/docs/Examples/_category_.json @@ -1,5 +1,4 @@ { "label": "Example Messages", - "position": 6, - "link":{} + "position": 6 } \ No newline at end of file diff --git a/app/docs/Examples/examples.md b/app/docs/Examples/examples.md index 0aff0da..9720f0b 100644 --- a/app/docs/Examples/examples.md +++ b/app/docs/Examples/examples.md @@ -7,7 +7,7 @@ Monitoring Trips ## Trips -Note that these examples are based on the [monitoring trip profile](Fundamentals/OTM_Profiles/profiles_examples/monitoring_trips). +Note that these examples are based on the [monitoring trip profile](../OTM_profiles/monitoring_trips). ### A (planned) trip @@ -110,7 +110,7 @@ Then, on the stop, a load action is created, with the consignment to be loaded: } ``` -The complete trip can be found [here](json/trip_with_actions.json) +The complete trip can be found [here](/data/trip_with_actions.json) ### A trip with vehicle, trailer and driver information @@ -238,7 +238,7 @@ Lastly, if we need a trailer on the truck we can attach it on a stop (usually th You might wonder why the trailer is on the stop instead of on the vehicle itself. The reason is that in many logistic operations there might be more than one trailer involved. By using one system the simple case might be a little more involved, but it works without any changes for more complex operations. -The complete trip with vehicle information can be found [here](json/trip_with_vehicle.json) +The complete trip with vehicle information can be found [here](/data/trip_with_vehicle.json) ### A trip with realization data @@ -307,7 +307,7 @@ Now the original trip can be enriched with the realized stop data by creating st } ``` -The complete trip with all realization data can be found [here](json/trip_with_realization_data.json) +The complete trip with all realization data can be found [here](/data/trip_with_realization_data.json) ### A trip with consignor/consignees @@ -354,4 +354,4 @@ model this situation in OTM5 by using the designated actor roles _consignor_ and }, ``` -The complete trip using consignor/consignee can be found [here](json/trip_with_consignor_consignee.json). \ No newline at end of file +The complete trip using consignor/consignee can be found [here](/data/trip_with_consignor_consignee.json). \ No newline at end of file diff --git a/app/docs/Examples/trips.md b/app/docs/Examples/trips.md new file mode 100644 index 0000000..9720f0b --- /dev/null +++ b/app/docs/Examples/trips.md @@ -0,0 +1,357 @@ +--- +title: Trips +--- + +Monitoring Trips +===================== + +## Trips + +Note that these examples are based on the [monitoring trip profile](../OTM_profiles/monitoring_trips). + +### A (planned) trip + +We start with a trip, give it a unique ID, and add the relevant parties involved (shipper, carrier): + +```json +{ + "id": "976eed42-bccc-4731-9d01-85ec3a16bd7b", + "status": "requested", + "actors": [ + { + "entity": { + "id": "0d3198ad-2f2d-4aed-8c77-6d7779aefba3", + "name": "Shipping Company TM" + }, + "roles": [ "shipper" ], + "associationType": "inline" + }, + { + "entity": { + "id": "005cffff-4aba-4e2d-a79d-d428ba93ae8a", + "name": "Carrier Transport" + }, + "roles": [ "carrier" ], + "associationType": "inline" + } + ], + "actions": [ ] +} +``` + +Then we create the first stop on the departure location: + +```json + { + "entity": { + "id": "2664fb3c-9ce4-4a56-98d0-4ac76c2a40c4", + "lifecycle": "planned", + "sequenceNr": 0, + "location": { + "entity": { + "id": "5a71bd67-e51c-46d1-842b-5fa171c0eb08", + "name": "Location of distribution center Bananas Inc", + "geoReference": { + "lat": 1, + "lon": 0, + "type": "latLonPointGeoReference" + } + }, + "associationType": "inline" + }, + "actions": [ ], + "actionType": "stop" + }, + "associationType": "inline" + } +``` + +We can add a constraint, to indicate that this stop should be visited between the boundary time windows: +```json +"constraint": { + "entity": { + "value": { + "startTime": "2021-03-25T10:00:00Z", + "endTime": "2021-03-25T11:00:00Z", + "type": "timeWindowConstraint" + } + }, + "associationType": "inline" +}, +``` + +Then, on the stop, a load action is created, with the consignment to be loaded: + +```json + { + "entity": { + "id": "2a806c26-640c-4562-85d5-8ea4b9e7d80f", + "lifecycle": "planned", + "consignment": { + "entity": { + "id": "04a9870f-52c0-463a-80c1-7d1d81c8b38a", + "goods": [ + { + "entity": { + "id": "db504c69-3769-4d70-9403-c870dabdbe4c", + "description": "Ordered box of Bananas", + "quantity": 2, + "type": "items" + }, + "associationType": "inline" + } + ] + }, + "associationType": "inline" + }, + "actionType": "load" + }, + "associationType": "inline" + } +``` + +The complete trip can be found [here](/data/trip_with_actions.json) + +### A trip with vehicle, trailer and driver information + +Continuing, once the trip contains planned actions we can attach a vehicle: +```json + "vehicle": { + "entity": { + "id": "1ee44c03-f899-421f-8e89-8f568ca30424", + "vehicleType": "truck", + "fuel": "Diesel", + "length": { + "value": 9, + "unit": "m" + }, + "height": { + "value": 4.2, + "unit": "m" + }, + "width": { + "value": 2.5, + "unit": "m" + }, + "licensePlate": "AB-12-CD" + }, + "associationType": "inline" + }, +``` + +Whenever we found a driver to drive the truck, we can add that to the actors of the _trip_ (not the vehicle): + +```json +{ + "entity": { + "id": "6084fd58-d26b-47e9-945b-5df9f2a36d70", + "name": "Hank", + "contactDetails": [ + { + "value": "0031699999999", + "type": "phone" + } + ] + }, + "roles": [ "driver" ], + "associationType": "inline" +} +``` + +Lastly, if we need a trailer on the truck we can attach it on a stop (usually the first). As an example here is the complete first stop with trailer attachment: + +```json +{ + "entity": { + "id": "2664fb3c-9ce4-4a56-98d0-4ac76c2a40c4", + "lifecycle": "planned", + "sequenceNr": 0, + "location": { + "entity": { + "id": "5a71bd67-e51c-46d1-842b-5fa171c0eb08", + "name": "Location of distribution center Bananas Inc", + "geoReference": { + "lat": 1, + "lon": 0, + "type": "latLonPointGeoReference" + } + }, + "associationType": "inline" + }, + "actions": [ + { + "entity": { + "lifecycle": "planned", + "transportEquipment": { + "entity": { + "id": "25b01018-a5b4-4cee-a14f-6b72d8624b77", + "equipmentType": "trailer", + "licensePlate": "01-AAA-1" + }, + "associationType": "inline" + }, + "actionType": "attachTransportEquipment" + }, + "associationType": "inline" + }, + { + "entity": { + "id": "2a806c26-640c-4562-85d5-8ea4b9e7d80f", + "lifecycle": "planned", + "consignment": { + "entity": { + "id": "04a9870f-52c0-463a-80c1-7d1d81c8b38a", + "goods": [ + { + "entity": { + "id": "376a5f1f-0b68-4671-bab6-2bd2b63c9f7b", + "description": "Ordered box of Bananas", + "quantity": 2, + "type": "items" + }, + "associationType": "inline" + } + ] + }, + "associationType": "inline" + }, + "actionType": "load" + }, + "associationType": "inline" + } + ], + "constraint": { + "entity": { + "value": { + "startTime": "2021-03-25T10:00:00Z", + "endTime": "2021-03-25T11:00:00Z", + "type": "timeWindowConstraint" + } + }, + "associationType": "inline" + }, + "actionType": "stop" + }, + "associationType": "inline" + }, +``` + +You might wonder why the trailer is on the stop instead of on the vehicle itself. The reason is that in many logistic operations there might be more than one trailer involved. By using one system the simple case might be a little more involved, but it works without any changes for more complex operations. + +The complete trip with vehicle information can be found [here](/data/trip_with_vehicle.json) + +### A trip with realization data + +So, once we have the complete planned trip above we can start driving and enrich the real-time GPS data to the vehicle by some FMS: + +```json +{ + "id": "a9c8746e-d6ca-401b-8890-759188789092", + "lifecycle": "actual", + "vehicle": { + "uuid": "1ee44c03-f899-421f-8e89-8f568ca30424", + "entityType": "vehicle", + "associationType": "reference" + }, + "geoReference": { + "lat": 2, + "lon": 3, + "type": "latLonPointGeoReference" + } +} +``` + +Now the original trip can be enriched with the realized stop data by creating stops with the same UUID, but the lifecycle realized: + +```json + { + "entity": { + "id": "2664fb3c-9ce4-4a56-98d0-4ac76c2a40c4", + "lifecycle": "realized", + "sequenceNr": 0, + "location": { + "uuid": "5a71bd67-e51c-46d1-842b-5fa171c0eb08", + "entityType": "location", + "associationType": "reference" + }, + "startTime": "2021-03-25T10:11:00Z", + "endTime": "2021-03-25T10:34:00Z", + "actions": [ + { + "entity": { + "id": "2a806c26-640c-4562-85d5-8ea4b9e7d80f", + "lifecycle": "realized", + "consignment": { + "uuid": "04a9870f-52c0-463a-80c1-7d1d81c8b38a", + "entityType": "consignment", + "associationType": "reference" + }, + "actionType": "load" + }, + "associationType": "inline" + } + ], + "constraint": { + "entity": { + "value": { + "startTime": "2021-03-25T10:00:00Z", + "endTime": "2021-03-25T11:00:00Z", + "type": "timeWindowConstraint" + } + }, + "associationType": "inline" + }, + "actionType": "stop" + }, + "associationType": "inline" + } +``` + +The complete trip with all realization data can be found [here](/data/trip_with_realization_data.json) + + +### A trip with consignor/consignees + +The above trip depicts the situation where all the goods in the trip belong to a single party, the shipper. However in real +logistic operations it often happens that a carrier transports goods of different parties in a single trip. You can +model this situation in OTM5 by using the designated actor roles _consignor_ and _consignee_ on each consignment: + +```json + "consignment": { + "entity": { + "id": "04a9870f-52c0-463a-80c1-7d1d81c8b38a", + "goods": [ + { + "entity": { + "id": "eb2e8f2a-b573-4d66-9d99-ff9235e10415", + "description": "Ordered box of Bananas", + "quantity": 2, + "type": "items" + }, + "associationType": "inline" + } + ], + "actors": [ + { + "entity": { + "id": "a1c3c25b-f766-45b6-b09d-07005d565353", + "name": "Bananas Inc." + }, + "roles": [ "consignor" ], + "associationType": "inline" + }, + { + "entity": { + "id": "02724538-1022-46cc-8286-186154fc0b9b", + "name": "Fine Food groceries" + }, + "roles": [ "consignee" ], + "associationType": "inline" + } + ] + }, + "associationType": "inline" + }, +``` + +The complete trip using consignor/consignee can be found [here](/data/trip_with_consignor_consignee.json). \ No newline at end of file diff --git a/app/docs/Fundamentals/_category_.json b/app/docs/Fundamentals/_category_.json index dd044ee..20e5102 100644 --- a/app/docs/Fundamentals/_category_.json +++ b/app/docs/Fundamentals/_category_.json @@ -3,7 +3,7 @@ "position": 2, "link": { "type": "doc", - "id": "overview" + "id": "fundamentals" } } diff --git a/app/docs/Fundamentals/design_principles.md b/app/docs/Fundamentals/design_principles.md index d32f315..441768f 100644 --- a/app/docs/Fundamentals/design_principles.md +++ b/app/docs/Fundamentals/design_principles.md @@ -31,7 +31,7 @@ able to process it anyway. The loose format with many optional values allows for handling many use cases with one data model. However, it might result in two parties implementing OTM without being able to communicate automatically. To avoid this, [OTM profiles -were created](OTM_Profiles), so that different use cases have a +were created](../OTM_profiles), so that different use cases have a clear intended structure. Even so, it could still result in small discrepancies. We are continously trying to balance flexibility to enable parties to use OTM broadly, and strict rules so that the parties use OTM consistently. diff --git a/app/docs/Fundamentals/entities.md b/app/docs/Fundamentals/entities.md index 8cbeb49..e4a6904 100644 --- a/app/docs/Fundamentals/entities.md +++ b/app/docs/Fundamentals/entities.md @@ -3,50 +3,15 @@ OTM Entities ### Connecting all entities -Chronologically, it all starts with the [TransportOrder](#tag/TransportOrder), -which groups a set of [Consignments](#tag/Consignment) that need to be shipped -from one location to another. A consignment contains various related -[Goods](#tag/Goods) that are shipped together and administered together. Thus -note that goods are actual physical entities, whereas transport orders and -consignments are administrative ones. The official [Documents](#tag/Document) -that are related to the goods, transport orders, consignments or the delivery -thereof can also be attached either as binary or with a reference to some online -location. +Chronologically, it all starts with the **TransportOrder** (Transport Order), which groups a set of **Consignments** (Consignment) that need to be shipped from one location to another. A consignment contains various related **Goods** (Goods) that are shipped together and administered together. Thus note that goods are actual physical entities, whereas transport orders and consignments are administrative ones. The official **Documents** (Document) that are related to the goods, transport orders, consignments or the delivery thereof can also be attached either as binary or with a reference to some online location. -Ultimately, consignments are moved as part of one or multiple -[Trips](#tag/Trip), where various [Constraints](#tag/Constraint) can be put in -place to ensure consignments are delivered on time, or always abide to a certain -temperature during the trip. The transport orders and consignments can be -associated with various [Actors](#tag/Actor). Such as the shipper, the carrier, -the consignee, consignor, or any legal party that is involved in the logistic -operation. +Ultimately, consignments are moved as part of one or multiple **Trips** (Trip), where various **Constraints** (Constraint) can be put in place to ensure consignments are delivered on time, or always abide to a certain temperature during the trip. The transport orders and consignments can be associated with various **Actors** (Actor). Such as the shipper, the carrier, the consignee, consignor, or any legal party that is involved in the logistic operation. -The trip is an entity that models visiting various [Locations](#tag/Location) -using a single [Vehicle](#tag/Vehicle). As such, when multiple vehicles are -involved, these need to be modelled as multiple trips in OTM. Each location that -is visited at a certain time is a [Stop action](#tag/Action) on which multiple -other actions can occur, such as [Loading](#tag/Action) and -[Unloading](#tag/Action) of various Consignments. Other actions include -[Waiting](#tag/Action) - for example because the dock is still occupied - and -having a [Break](#tag/Action). The big difference is that a break is always -mandatory and waiting can be shorted if the situation changes. +The trip is an entity that models visiting various **Locations** (Location) using a single **Vehicle** (Vehicle). As such, when multiple vehicles are involved, these need to be modelled as multiple trips in OTM. Each location that is visited at a certain time is a **Stop action** (Action) on which multiple other actions can occur, such as **Loading** (Action) and **Unloading** (Action) of various Consignments. Other actions include **Waiting** (Action) - for example because the dock is still occupied - and having a **Break** (Action). The big difference is that a break is always mandatory and waiting can be shortened if the situation changes. -Consignments after unloading can be (optionally) [HandOver](#tag/Action) from -one party (an actor) to another. If needed, you can use a [Move](#tag/Action) -action to model a detailed description of how to travel between two locations -and which [Route](#tag/Route) to take. - -During a trip a [Sensor](#tag/Sensor) in a vehicle can give -[LocationUpdateEvents](#tag/Event) with coordinates of the vehicle, or -[SensorUpdateEvents](#tag/Event) with sensor values, for example the temperature -of the goods, or the speed of the vehicle. After OTM data has been shared, it -can be updated using [UpdateEvents](#tag/Event) with the modified data of the -entities that needed to be updates. Also entities can be _associated_ and -_unassociated_ using the [AssociationCreatedEvent](#tag/Event) and -[AssociationRemovedEvent](#tag/Event). This can be useful to provide or modify -information of which vehicle is going to drive which trip after an initial -planning has been made. +Consignments after unloading can be (optionally) **HandOver** (Action) from one party (an actor) to another. If needed, you can use a **Move** (Action) action to model a detailed description of how to travel between two locations and which **Route** (Route) to take. +During a trip a **Sensor** (Sensor) in a vehicle can give **LocationUpdateEvents** (Event) with coordinates of the vehicle, or **SensorUpdateEvents** (Event) with sensor values, for example the temperature of the goods, or the speed of the vehicle. After OTM data has been shared, it can be updated using **UpdateEvents** (Event) with the modified data of the entities that needed to be updates. Also entities can be _associated_ and _unassociated_ using the **AssociationCreatedEvent** (Event) and **AssociationRemovedEvent** (Event). This can be useful to provide or modify information of which vehicle is going to drive which trip after an initial planning has been made. ### Visually The above can be visualized as follows: diff --git a/app/docs/Fundamentals/overview.md b/app/docs/Fundamentals/overview.md index 8e3021b..01ebe8c 100644 --- a/app/docs/Fundamentals/overview.md +++ b/app/docs/Fundamentals/overview.md @@ -1,6 +1,6 @@ --- -title: Overview -id: overview +title: Fundamentals +id: fundamentals sidebar_position: 1 --- @@ -36,7 +36,7 @@ different parties use the same language for communicating. To meet that purpose OTM needs to be applicable in many use cases which requires great flexibility. This flexiblity can complicate the code if you process OTM internally (for example when dealing with inline vs reference associations). You are not -required - or even encouraged - to completely implement the specification if +required - or even encouraged - to completely implement the specification if it doesn't fit your use cases. Focus on the parts of OTM that you need and translate between OTM and your internal format at the boundaries of your services. @@ -48,7 +48,7 @@ traffic and logistics, as such OTM is pretty loose in what data is required. Many fields are optional, and often data types offer multiple modelling options, such as the many georeference options available on a location. However, for your use case some fields might actually be required, even if the OTM specification -makes them optional. In such cases the recommend approach is to _only_ accept +makes them optional. In such cases the recommended approach is to _only_ accept incoming OTM that you are able to process, and return validation errors otherwise. There is no reason to accept OTM, even if valid, when you are not able to process it anyway. @@ -58,7 +58,7 @@ able to process it anyway. The loose format with many optional values allows for handling many use cases with one data model. However, it might result in two parties implementing OTM without being able to communicate automatically. To avoid this, [OTM profiles -were created](OTM_Profiles), so that different use cases have a +were created](../OTM_profiles), so that different use cases have a clear intended structure. Even so, it could still result in small discrepancies. We are continously trying to balance flexibility to enable parties to use OTM broadly, and strict rules so that the parties use OTM consistently. diff --git a/app/docs/OTM_profiles/fms.md b/app/docs/OTM_profiles/fms.md index 6ca27bf..c404ba1 100644 --- a/app/docs/OTM_profiles/fms.md +++ b/app/docs/OTM_profiles/fms.md @@ -22,7 +22,7 @@ also incorporate other sensor data (such as temperature, road situtations, traffic jams, etc.) later once we have a more solid grip on how to model it in OTM. -One available implementation of this profile is the **[FMS ITS](fms_its_implementation.md)**. +One available implementation of this profile is the **[FMS ITS](fms-it)**. General structure ----------------- @@ -63,7 +63,7 @@ following definition As a next step we will create an official `LocationUpdateEvent` Protobuf schema and make it available here. -Profobuf is also used in the **[FMS ITS](fms_it.md)**. +Profobuf is also used in the **[FMS ITS](fms-it)**. Example ------- diff --git a/app/docs/OTM_profiles/monitoring_trips.md b/app/docs/OTM_profiles/monitoring_trips.md index 79df392..da841eb 100644 --- a/app/docs/OTM_profiles/monitoring_trips.md +++ b/app/docs/OTM_profiles/monitoring_trips.md @@ -15,17 +15,17 @@ The different phases of a trip are: 2. Once a planning is finalized it can be driven. The vehicle and planned times are all known. At this point we might know more about the state of the world and can anticipate what will happen during the trip, such as being delayed because of a traffic jam. Continous location update and traffic events can provide real-time insight in where the vehicle is, that can serve as a basis to make predictions. -3. Once all is set and done the trip is fininshed. All information is known and cannot change anymore since it is in the past. This information is useful so we can compare our original planning with what actually happened so we can make more accurate planning data in the future. It can also be used for billing, or analyzing the data to find bottlebecks and optimize the process for next trips. +3. Once all is set and done the trip is finished. All information is known and cannot change anymore since it is in the past. This information is useful so we can compare our original planning with what actually happened so we can make more accurate planning data in the future. It can also be used for billing, or analyzing the data to find bottlebecks and optimize the process for next trips. General structure ----------------- -Monitoring trips is a complex operation that includes almost every entity and action within OTM, and was actually the primary reason for creating OTM. Looking at the original image from the [overview](otm_overview) we can see that only the TransportOrder is not present. Everything that can be present in phase 1 is black, the additions for phase 2 are made purple, and the only addition for phase 3 is actual _proof of delivery_ using a HandOver made red. +Monitoring trips is a complex operation that includes almost every entity and action within OTM, and was actually the primary reason for creating OTM. Looking at the original image from [OTM entities](../Fundamentals/entities) we can see that for the monitoring trips profile, only the TransportOrder is not present. Everything that can be present in phase 1 is black, the additions for phase 2 are made purple, and the only addition for phase 3 is actual _proof of delivery_ using a HandOver made red. ![](/img/otm5_monitoring_trips_profile.png) -Since this might not give enough insight, we can also the present the hierarchy with the required rules as follows: +Since this might not give enough insight, we can also present the hierarchy with the required rules as follows: - Trip - A trip _must_ have a unique UUID. diff --git a/app/docs/OTM_profiles/vesdi.md b/app/docs/OTM_profiles/vesdi.md index d1b7dc0..01eb198 100644 --- a/app/docs/OTM_profiles/vesdi.md +++ b/app/docs/OTM_profiles/vesdi.md @@ -1,4 +1,4 @@ -CBS profile +CBS Profile ===== :::warning @@ -13,9 +13,9 @@ VESDI is the abbreviation for _Vehicle_, _Emission_, _Shipment_, _Data_, _Interf General structure ----------------- -The basis for the VESDI interface is the OTM realized trip. See also [The official trip API documentation](https://otm5.opentripmodel.org/#tag/Trip/paths/~1api~1v5~1trips/put) and the [realized trip profile in monitoring](monitoring_trips.md#phase-3-realization) Added are specific element related to the vehicle (e.g. type, emission class) and fuel consumption (e.g usage, mileage). Note though that the emission and the measured distance are not part of OTM5.0 yet, but are planned for OTM5.1. +The basis for the VESDI interface is the OTM realized trip. See also [The official trip API documentation](https://otm5.opentripmodel.org/#tag/Trip/paths/~1api~1v5~1trips/put) and the realized trip profile in monitoring Added are specific element related to the vehicle (e.g. type, emission class) and fuel consumption (e.g usage, mileage). Note though that the emission and the measured distance are not part of OTM5.0 yet, but are planned for OTM5.1. The VESDI can be used in B2B communication as well. Example --------- +-------- \ No newline at end of file diff --git a/app/docs/developer/_category_.json b/app/docs/developer/_category_.json new file mode 100644 index 0000000..0dfc406 --- /dev/null +++ b/app/docs/developer/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Developer", + "position": 7 + +} \ No newline at end of file diff --git a/app/versioned_docs/version-5.6/api_specification.md b/app/docs/developer/api_specification.md similarity index 100% rename from app/versioned_docs/version-5.6/api_specification.md rename to app/docs/developer/api_specification.md diff --git a/app/docs/developer/developer.md b/app/docs/developer/developer.md new file mode 100644 index 0000000..83d6c4f --- /dev/null +++ b/app/docs/developer/developer.md @@ -0,0 +1,9 @@ +Developer +=========== + + +This section of the documentation provides detailed information and resources specifically for developers. It includes a section on the OpenAPI Specification (OAS) and a section on validation of OTM specifications. + + + + diff --git a/app/versioned_docs/version-5.6/validation.md b/app/docs/developer/validation.md similarity index 100% rename from app/versioned_docs/version-5.6/validation.md rename to app/docs/developer/validation.md diff --git a/app/docs/faq.md b/app/docs/faq.md index b9f97f9..5c02478 100644 --- a/app/docs/faq.md +++ b/app/docs/faq.md @@ -6,63 +6,30 @@ sidebar_position: 7 Frequently Asked Questions ========================== -* _Is it mandatory to use JSON as file format for OTM5?_ - - > Yes, this is mandatory. OTM5 does not exist as XML and only JSON is and will be supported. By keeping the options to a minum we - ensure it is easier to adopt and also that parties that implement OTM can actually talk with each other. * _How open or free is OTM5 as a standard? How do you prevent that different parties add or change fields?_ > We cannot police every party that _says_ they are doing OTM without actually confirming to the well-defined standard. Simply put, if - they do not follow the structures defined in [the API portal](https://otm5.opentripmodel.org/) then they are not doing OTM. That said, + they do not follow the structures defined in [the API portal](/api) then they are not doing OTM. That said, even within the standard there still is some room for different interpretations, so we try to improve this situation by extending or documentation & examples, and continously improve the standard itself as well. * _OTM5 contains some free text fields, such as the vehicle type, the unit measurement, and the type of transport equipment? Which values should be used for those fields?_ - > We have been working on incorporating 'standard lists' in the specification as well. For currentcies, temperatures, mass, length and - speed values we have provided the options in [the API speficication](https://otm5.opentripmodel.org/) and we are also currently working + > We have been working on incorporating 'standard lists' in the specification as well. For currencies, temperatures, mass, length and + speed values we have provided the options in [the API specification](/api) and we are also currently working on extending that for the different 'types' that are present (such as vehicles, goods items, transport equipment, etc.) -* _The API specification is based on the REST architecture? Is REST therefore mandatory? Are alternatives such as sFTP permitted?_ - - > To prevent many flavours of communicating OTM5 we decided to incorporate the actual protocol of communication within the standard. So yes - the use of REST is mandatory. We understand that moving towards OTM5 is a proces and therefore we like to encourage to focus on the model first, - but to incorporate the REST architecture afterwards as well. - -* _Are any endpoints provided by the OTM standard?_ - - > No, the OTM5 standard only consists of the _specification_ of what OTM is and how it should be used. Parties needing to communicate need to - setup services themselves to actually do this communication. Which party provides the endpoint and which party uses those endpoints needs to be - decided by the parties themselves as well. * _When using Transport Orders is it mandatory to use one, or multiple consignments?_ > A transport without any consignment doesn't make sense. However there is no rule about whether or not a transport order can contain one or multiple consignments. Different parties have different needs, so we cannot mandate a process here. -* _How do you update a transport order with multiple consignments?_ - - > There are two supported options within the OTM5 standard for updates. - > 1. You can send the complete transportOrder, including all consignments (both those that are changed and those that are unchanged). - > 2. You only send an update request to the specific consignments that need updating. - > The advantage of method 1 is that you only need to do one request, but the downside is that the messages can get quite large, even if - most consignments did not change. The advantage of method 2 is that you only send what is changed, but you do need to do multiple requests - to change each consignment. Our view is that parties should always support method 1 and optionally can also support method 2. - -* _What is the difference between actions and events?_ - - > Actions model the dynamic interaction between static entities. Such as loading and unloading goods from and into vehicles. Entities like - vehicles seldomly change, whereas load and unload time windows are often updated. By separateing these in entities and actions we make this - interaction simpler. - > - > Events on the other hand model updates to existing data (such as the updateEvent, or associationCreatedEvent/associationRemovedEvent) or - model changes that are happening in real-time (such as locationUpdateEvents or sensorUpdateEvents). - * _My company does not use UUIDs for identifying entities, are UUIDs mandatory?_ - > Since OTM5.2 you do not have to provide UUIDs anymore when sending entities. However, UUIDs are currently best possible method of + > Since OTM5.2 you do not have to provide UUIDs anymore when sending entities. However, UUIDs are currently the best possible method of ensuring unique IDs among different platforms. So we highly recommend using them as your primary identifiers. Omitting UUIDs is thus allowed when sending entities, however you cannot retrieve entities by any other identifier. This might be accepted if retrieving is not necessary. @@ -70,14 +37,14 @@ Frequently Asked Questions * _What are constraints used for?_ > Constraints are, as the name suggests, are information about restrictions that hold for the actions or entities they are attached to. - This can range from delivery windows for consignments, to vehicle types for certain type of goods. See also [this how-to](http://localhost:3000/developer-portal/adding-constraints/) for more information. + This can range from delivery windows for consignments, to vehicle types for certain type of goods. See also [the usage notes](./usage_notes/adding_constraints) for more information. * _What are the association types that appear in the OTM5 messages?_ > Whenever you look at a hierarchy of entities. Such as a trip, containing stops, containing locations and various sub-actions such as loading and unloading consignments you can see that each entity is wrapped in what is called an _association_. These assocaitions are useful because sometimes we want to provide the information completely (association type inline), and sometimes we just want to refer to an existing entity (association type reference). This allows you - to choose whatever is suited for your operation. See also [this dedicated page](associations.md#associations) about + to choose whatever is suited for your operation. See also [this dedicated page](./Fundamentals/associations) about associations. * _How can you deal with layered data about the load carriers and the goods contained in them?_ @@ -97,5 +64,4 @@ Frequently Asked Questions being loaded and unloaded. Thus an action needs to be able to refer to the consignment. However, when we look at those same consignments from a _track and trace_ perspective we often follow a _single_ consignment that can be part of multiple trips before arriving at its final destination. Thus a consignment contains _all_ load and unload actions in that use case. It can be a bit daunting at first, but we strongly believe that this allows us to - keep the specification fairly small while being useful for a wide range of use cases. See also the [overview](otm_overview.md#overview-of-open-trip-model-v5) for more information. - + keep the specification fairly small while being useful for a wide range of use cases. See also the [overview](./Fundamentals/fundamentals) for more information. diff --git a/app/docs/introduction.md b/app/docs/introduction.md index 43c95d0..deab64b 100644 --- a/app/docs/introduction.md +++ b/app/docs/introduction.md @@ -16,14 +16,17 @@ On this portal 1. **About section** on general knowledge of OTM. 2. **Documentation** explains all different aspects of OTM on a technical level. 3. **Blog** where updates are provided regarding OTM. -4. **[API documentation](/API)** defined using [OpenAPI](https://spec.openapis.org/oas/v3.1.0). It contains all the entities, data structures and operations that OTM5 supports. +4. **[API documentation](/api)** defined using [OpenAPI](https://spec.openapis.org/oas/v3.1.0). It contains all the entities, data structures and operations that OTM5 supports. 5. **Semantic treehouse** which can be used to create messages and validation. 6. **Github repository** for [change requests](https://github.com/opentripmodel/otm5-change-requests), either to the specification or the API documentation page. If you have any questions or suggestions, this is the place to discuss. +7. **SUTC website** contains a link to the SUTC website. **Side Bar** 1. **Fundamentals** explains the core ideas and concepts of OTM. It contains an overview that shows which entities exist in the model and how they are related to each other. -2. **How To** contains a guides on various concepts using examples and more explanation. -3. **OTM profiles** looks at different use cases and ensures that each of them get clear guidelines on how to be modelled in OTM. +2. **OTM profiles** looks at different use cases and ensures that each of them get clear guidelines on how to be modelled in OTM. +3. **Usage Notes** look at how different functionalities within OTM can be used. +4. **Example Messages** contain various examples as messages. +2. **Validation** contains a guide on how validate your OTM messages using STH. +5. **API Specification** contains additional information on the OTM specification. 4. **FAQ** contains frequently asked questions. -5. **Validation** contains a guide on how to validate your message using [Semantic Treehouse](https://sutc.semantic-treehouse.nl/). diff --git a/app/docs/usage_notes/external_attributes.md b/app/docs/usage_notes/external_attributes.md index 643f8ea..c7192e3 100644 --- a/app/docs/usage_notes/external_attributes.md +++ b/app/docs/usage_notes/external_attributes.md @@ -1,7 +1,7 @@ External attributes =================== -`ExternalAttributes` are a data type that can be used to communicate data between parties that is not inherently part of OTM. This allows you to extend the data present in OTM without the need to change the specification. This usually will be administrative, or company-specific data. Note though, that if something _can_ be modeled using just OTM entities it _should_ be done that way. External attributes are often used to provide IDs that are not UUIDs but still need to be communicated. +`ExternalAttributes` are a data type that can be used to communicate data between parties that can not be modelled with OTM. In essence, external attributes can be used as _free fields_ to add that type of data. This allows you to extend the data present in OTM without the need to change the specification. This usually will be administrative, or company-specific data. Note though, that if something _can_ be modeled using just OTM entities it _should_ be done that way. External attributes are often used to provide IDs that are not UUIDs but still need to be communicated. External attributes are nothing more than a list of key-values. This is an example of what it could look like: diff --git a/app/docs/validation.md b/app/docs/validation.md deleted file mode 100644 index 71b69a8..0000000 --- a/app/docs/validation.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Validation -sidebar_position: 5 ---- - -:::info -Here we can put a section on Semantic Treehouse integration. -::: \ No newline at end of file diff --git a/app/docusaurus.config.ts b/app/docusaurus.config.ts index 626fcbd..c672e37 100644 --- a/app/docusaurus.config.ts +++ b/app/docusaurus.config.ts @@ -37,7 +37,7 @@ const config: Config = { { docs: { sidebarPath: "./sidebars.ts", - includeCurrentVersion: false, + includeCurrentVersion: true, }, blog: { showReadingTime: true, @@ -75,7 +75,6 @@ const config: Config = { // }, // ] satisfies Redocusaurus.PresetEntry, ], - themeConfig: { // Replace with your project's social card @@ -101,9 +100,11 @@ const config: Config = { position: "left", label: "Documentation", }, - { to: "/blog", label: "Blog", position: "left" }, + { to: "/docs/OTM_profiles/", label: "OTM Profiles", position: "left" }, { to: "/api", label: "API", position: "left" }, - { to: "/adopters", label: "Adopters", position: "left"}, + { to: "/docs/developer/", label: "Developer", position: "left" }, + // { to: "/blog", label: "Blog", position: "left" }, + { to: "/adopters", label: "Adopters", position: "left" }, { href: "https://sutc.semantic-treehouse.nl/", label: "STH", @@ -133,4 +134,4 @@ const config: Config = { } satisfies Preset.ThemeConfig, }; -export default config; \ No newline at end of file +export default config; diff --git a/app/src/pages/adopters.md b/app/src/pages/adopters.md index 846f96a..4906973 100644 --- a/app/src/pages/adopters.md +++ b/app/src/pages/adopters.md @@ -54,6 +54,5 @@ Below is a table of organisations who made a contribution to the OpenTripModel s | ![](/img/logos_contributors/logo-TANS.png)| TANS | https://www.tans.net | |![](/img/logos_contributors/centric.png) | Centric | https://www.centric.eu/nl/branches/transport-en-logistiek/ | | ![](/img/logos_contributors/navitrans.pjg.jpg)| Rainbow Logistics IT | https://navitrans.rainbowsolutions.nl/| -| ![](/img/logos_contributors/simacan.png) | Simacan | https://www.simacan.com | | ![](/img/logos_contributors/data2track-logo.png) | Data2Track | https://www.data2track.nl/| | ![](/img/logos_contributors/bluerock.png)| VOICT (bluerock) | https://voict.nl/ | diff --git a/app/src/pages/index.md b/app/src/pages/index.md index 9bf7c3e..bd1f7a5 100644 --- a/app/src/pages/index.md +++ b/app/src/pages/index.md @@ -6,7 +6,7 @@ title: About What is the Open Trip Model? ------------ -The Open Trip Model (OTM) is an open-source, lightweight data specification designed to simplify communication across logistics and traffic networks. Created by Simacan, OTM facilitates the real-time exchange of logistic trip data on the web, enabling seamless collaboration among shippers, carriers, software vendors, OEMs, and truck manufacturers. The model addresses the inefficiencies caused by diverse data formats in the logistics sector, which often create complex and costly custom translation layers between companies. By standardizing data exchange, OTM makes the technological landscape simpler and more cost-effective, encouraging innovation and collaboration within the industry. +The Open Trip Model (OTM) is an open-source, lightweight data specification designed to simplify communication across logistics and traffic networks. Originally created by Simacan but now open-source, OTM facilitates the real-time exchange of logistic trip data on the web, enabling seamless collaboration among shippers, carriers, software vendors, OEMs, and truck manufacturers. The model addresses the inefficiencies caused by diverse data formats in the logistics sector, which often create complex and costly custom translation layers between companies. By standardizing data exchange, OTM makes the technological landscape simpler and more cost-effective, encouraging innovation and collaboration within the industry.